AI 实战文档

Appearance

Skill 最佳实践 ​

1. 任务导向，不要概念导向 ​

Skill 必须服务具体任务，不要写成百科条目。

正确示例 ​

yaml
name: release-readiness-check
description: 发布前检查评测、监控、回滚配置是否齐备
task: 检查发布就绪状态
input: 版本号、评测报告
output: 风险等级、阻塞问题、建议

错误示例 ​

yaml
name: release-management
description: 关于发布管理的所有知识
task: 学习发布管理
# 太宽泛，不是具体任务

2. 先可执行，再可扩展 ​

先保证一个最小流程跑通，再逐步增加自动化。

最小可用版本 ​

yaml
version: 1.0.0
workflow:
  - step: 读取评测报告
    action: file.read
  - step: 检查门禁阈值
    action: validate.threshold
  - step: 生成风险等级
    action: assess.risk

扩展版本 ​

yaml
version: 2.0.0
workflow:
  - step: 读取评测报告
    action: file.read
  - step: 读取变更说明
    action: file.read
  - step: 读取监控配置
    action: file.read
  - step: 检查门禁阈值
    action: validate.threshold
  - step: 检查监控配置
    action: validate.monitoring
  - step: 检查回滚策略
    action: validate.rollback
  - step: 生成风险等级
    action: assess.risk
  - step: 生成建议
    action: generate.recommendations

3. 强制输出结构化结果 ​

Skill 结果建议固定字段，便于评测、审计、回放。

推荐输出结构 ​

json
{
  "metadata": {
    "skill_name": "release-readiness-check",
    "version": "1.0.0",
    "executed_at": "2026-03-08T10:00:00Z",
    "duration_ms": 1234
  },
  "status": "success",
  "summary": {
    "risk_level": "low",
    "blocking_issues": [],
    "warnings": ["监控告警阈值偏高"],
    "total_checks": 10,
    "passed_checks": 9
  },
  "findings": [
    {
      "id": "check-1",
      "category": "evaluation",
      "status": "passed",
      "message": "评测成功率 95% 超过阈值 90%"
    }
  ],
  "recommendations": [
    "建议降低监控告警阈值",
    "可以考虑增加更多回归测试"
  ]
}

输出字段规范 ​

字段必需说明
metadata是执行元信息
status是success / partial / failed
summary是执行摘要
findings是详细发现列表
recommendations否改进建议

4. 绑定样本和反例 ​

每个 Skill 都应有：

成功样本 ​

yaml
# examples/success-1.yaml
input:
  version: 1.2.0
  eval_report: path/to/report.json
expected_output:
  status: success
  summary.risk_level: low
  summary.blocking_issues: []

边界样本 ​

yaml
# examples/edge-1.yaml
input:
  version: 1.2.0
  eval_report: path/to/report-with-warnings.json
expected_output:
  status: success
  summary.risk_level: medium
  summary.warnings:
    - 评测成功率接近阈值

失败样本 ​

yaml
# examples/failure-1.yaml
input:
  version: 1.3.0
  eval_report: path/to/failing-report.json
expected_output:
  status: failed
  summary.risk_level: high
  summary.blocking_issues:
    - '评测成功率 85% 低于阈值 90%'

5. 版本化与变更日志 ​

每次修改 Skill，记录：

变更日志格式 ​

markdown
# CHANGELOG.md

## [1.2.0] - 2026-03-08

### Added

- 新增监控配置检查
- 新增回滚策略检查

### Changed

- 调整风险等级计算逻辑
- 优化输出格式

### Fixed

- 修复评测报告解析错误

### Deprecated

- 旧版输出格式将在 2.0 移除

## [1.1.0] - 2026-03-01

### Added

- 初始版本

版本号规则 ​

yaml
版本号格式: MAJOR.MINOR.PATCH

MAJOR: 不兼容的变更
  - 输出格式变化
  - 必需输入变化
  - 工作流重构

MINOR: 向后兼容的新功能
  - 新增可选输入
  - 新增输出字段
  - 新增检查项

PATCH: 向后兼容的问题修复
  - Bug 修复
  - 性能优化
  - 文档更新

6. 双角色复核 ​

开发者复核清单 ​

markdown
## 可执行性复核

- [ ] 每个步骤有明确的输入输出
- [ ] 依赖的工具或资源可用
- [ ] 脚本可以在 CI 环境运行
- [ ] 错误处理完善
- [ ] 日志输出清晰
- [ ] 有单元测试
- [ ] 有集成测试

## 技术复核

- [ ] 代码风格符合规范
- [ ] 无安全漏洞
- [ ] 性能满足要求
- [ ] 无硬编码配置

产品经理复核清单 ​

markdown
## 业务价值复核

- [ ] 任务边界清晰
- [ ] 成功标准可量化
- [ ] 失败处理合理
- [ ] 用户价值明确

## 体验复核

- [ ] 输入要求合理
- [ ] 输出易于理解
- [ ] 错误信息友好
- [ ] 执行时间可接受

## 风险复核

- [ ] 高风险场景已识别
- [ ] 降级策略已定义
- [ ] 人工复核点已标注

7. 设退场机制 ​

当 Skill 长期不使用或被替代，要明确下线。

退场条件 ​

yaml
退场条件:
  - 90 天内未使用
  - 已有新 Skill 替代
  - 业务场景已不存在
  - 维护成本高于收益

退场流程 ​

yaml
退场流程:
  1. 通知:
    - 通知所有使用者
    - 标记为 deprecated
    - 更新文档

  2. 过渡期:
    - 提供迁移指南
    - 保留 30 天过渡期
    - 支持问题解答

  3. 下线:
    - 移除触发入口
    - 归档到 deprecated 目录
    - 更新索引

  4. 清理:
    - 清理依赖资源
    - 更新相关文档
    - 通知完成

迁移指南模板 ​

markdown
# 迁移指南：从 old-skill 到 new-skill

## 为什么迁移

old-skill 已废弃，原因是...

## 迁移步骤

1. 将触发关键词从 `old-skill` 改为 `new-skill`
2. 更新输入参数...

## 输入变化

| old-skill | new-skill   | 说明     |
| --------- | ----------- | -------- |
| param_a   | param_a     | 保持不变 |
| param_b   | param_b_new | 名称变化 |
| -         | param_c     | 新增参数 |

## 输出变化

...

## 常见问题

Q: 迁移后数据会丢失吗？
A: ...

Q: 可以继续使用 old-skill 吗？
A: 过渡期内可以，但建议尽快迁移

8. 性能优化 ​

执行效率 ​

yaml
优化建议:
  - 缓存中间结果
  - 并行执行独立步骤
  - 增量处理大文件
  - 避免重复计算

示例：并行执行 ​

yaml
workflow:
  execute:
    - step: 并行检查
      parallel:
        - action: check.security
        - action: check.style
        - action: check.performance

9. 可观测性 ​

日志规范 ​

yaml
日志级别:
  ERROR: 执行失败，无法继续
  WARN: 遇到问题，但可以继续
  INFO: 关键步骤完成
  DEBUG: 详细调试信息

日志格式: |
  [TIMESTAMP] [LEVEL] [SKILL_NAME] [STEP] Message

指标收集 ​

yaml
指标:
  - skill.execution.count: 执行次数
  - skill.execution.duration: 执行时长
  - skill.execution.success_rate: 成功率
  - skill.findings.count: 发现数量

10. 安全考虑 ​

输入验证 ​

yaml
安全检查:
  - 输入长度限制
  - 输入类型验证
  - 敏感信息过滤
  - 路径穿越检查

权限控制 ​

yaml
权限设计:
  - 最小权限原则
  - 按需申请权限
  - 敏感操作审计
  - 超时自动终止

输出脱敏 ​

yaml
脱敏规则:
  - 移除敏感数据
  - 哈希标识符
  - 截断长文本
  - 过滤密钥信息

检查清单 ​

markdown
## Skill 发布前检查清单

### 基础检查

- [ ] SKILL.md 完整
- [ ] 版本号正确
- [ ] 变更日志更新
- [ ] 作者信息正确

### 功能检查

- [ ] 输入验证完整
- [ ] 输出结构正确
- [ ] 错误处理完善
- [ ] 降级策略定义

### 质量检查

- [ ] 测试用例覆盖
- [ ] 样本和反例绑定
- [ ] 双角色复核完成

### 文档检查

- [ ] 使用说明清晰
- [ ] 示例可运行
- [ ] FAQ 完善

### 运维检查

- [ ] 日志输出清晰
- [ ] 指标收集完整
- [ ] 告警配置正确