AI 实战文档

Appearance

怎么写 Skill ​

这里给一个可落地的写作流程，默认面向开发者和产品经理协作场景。

Step 1：定义任务边界 ​

先写清楚这 4 件事：

  • 解决什么问题。
  • 不解决什么问题。
  • 成功判定标准。
  • 失败时怎么处理。

任务边界模板 ​

yaml
name: release-readiness-check
description: 发布前检查评测、监控、回滚配置是否齐备

# 边界定义
scope:
  - 检查评测报告是否通过门禁
  - 检查监控告警是否配置
  - 检查回滚策略是否明确

out_of_scope:
  - 不执行实际发布
  - 不修改任何配置
  - 不评估业务价值

success_criteria:
  - 所有门禁检查通过
  - 输出风险等级和建议

failure_handling:
  - 门禁未通过时列出阻塞项
  - 信息不足时明确标注

Step 2：拆执行链路 ​

推荐按 4 段写：

  1. Gather：收集上下文与输入。
  2. Decide：做路径判断。
  3. Execute：执行动作。
  4. Verify：验证结果。

执行链路示例 ​

yaml
workflow:
  gather:
    - 读取变更说明（changelog）
    - 读取评测报告（eval_report）
    - 读取监控配置（alert_rules）
    - 读取回滚配置（rollback_config）

  decide:
    - 判断评测结果是否达标
    - 判断监控覆盖是否完整
    - 判断回滚条件是否清晰

  execute:
    - 生成分项检查结果
    - 汇总风险等级
    - 输出建议

  verify:
    - 检查输出格式是否合规
    - 检查所有引用来源是否可追溯
    - 检查建议是否可执行

Step 3：添加最小资产 ​

  • 至少 1 个模板。
  • 至少 1 个例子。
  • 至少 1 个校验脚本或检查清单。

模板示例 ​

markdown
# 发布就绪检查报告

## 基本信息

- 检查时间：{timestamp}
- 变更版本：{version}
- 检查人：{checker}

## 评测检查

| 指标       | 阈值 | 实际值  | 状态     |
| ---------- | ---- | ------- | -------- |
| 任务成功率 | ≥95% | {value} | {status} |
| 事实准确率 | ≥90% | {value} | {status} |
| 时延 P95   | ≤10s | {value} | {status} |

## 监控检查

- [ ] 错误率告警已配置
- [ ] 时延告警已配置
- [ ] 成本告警已配置

## 回滚检查

- 回滚触发条件：{conditions}
- 回滚执行步骤：{steps}
- 回滚验证方法：{verification}

## 风险评估

- 风险等级：{low|medium|high}
- 阻塞问题：{blocking_issues}
- 建议行动：{recommendations}

检查清单示例 ​

markdown
# Skill 质量检查清单

## 边界定义

- [ ] 明确说明能做什么
- [ ] 明确说明不能做什么
- [ ] 定义成功判定标准
- [ ] 定义失败处理方式

## 流程设计

- [ ] Gather 阶段输入清晰
- [ ] Decide 阶段判断逻辑明确
- [ ] Execute 阶段动作可执行
- [ ] Verify 阶段验证标准可量化

## 资产完备

- [ ] 提供输入模板
- [ ] 提供输出模板
- [ ] 提供示例数据
- [ ] 提供校验脚本或检查清单

## 文档质量

- [ ] 有简明使用说明
- [ ] 有常见问题解答
- [ ] 有版本记录
- [ ] 有维护者信息

Step 4：定义质量门禁 ​

至少包含：

  • 输出格式是否合规。
  • 关键事实是否可追溯。
  • 安全与合规是否满足最小要求。

质量门禁配置 ​

yaml
quality_gates:
  format_check:
    type: json_schema
    schema: ./schemas/output.schema.json
    severity: blocking

  citation_check:
    type: all_sources_traceable
    severity: warning

  safety_check:
    type: no_sensitive_data
    severity: blocking

  custom_checks:
    - name: no_placeholder_values
      type: regex
      pattern: '\{[^}]+\}'
      severity: warning
      message: 输出中存在未替换的占位符

Step 5：做灰度发布 ​

  • 先让少数任务使用新 Skill。
  • 记录失败样本。
  • 再逐步扩大覆盖范围。

灰度发布策略 ​

yaml
rollout:
  stage_1:
    description: 内部测试
    scope: [dev_team]
    duration: 1_week
    success_threshold: 95%

  stage_2:
    description: 小范围试点
    scope: [beta_users]
    duration: 2_weeks
    success_threshold: 90%

  stage_3:
    description: 全量发布
    scope: [all_users]
    rollback_on:
      - success_rate < 85%
      - critical_errors > 3

完整 Skill 模板 ​

txt
# SKILL.md

## name

release-readiness-check

## description

用于发布前检查评测、监控、回滚配置是否齐备。

## triggers

- 发布前自动触发
- 手动调用：`/skill release-check --version {version}`

## inputs

| 参数 | 类型 | 必填 | 说明 |
|-----|------|-----|------|
| version | string | 是 | 发布版本号 |
| changelog | string | 否 | 变更说明文件路径 |
| eval_report | string | 否 | 评测报告路径 |

## workflow

1. 读取变更与评测报告
2. 检查门禁阈值
3. 生成风险分级
4. 给出上线建议

## outputs

```json
{
  "risk_level": "low|medium|high",
  "blocking_issues": ["issue1", "issue2"],
  "warnings": ["warning1"],
  "launch_recommendation": "proceed|wait|abort",
  "conditions": ["condition1"]
}

examples ​

示例 1：正常发布 ​

输入：版本 1.2.0，评测通过，监控已配置

输出：

json
{
  "risk_level": "low",
  "blocking_issues": [],
  "warnings": [],
  "launch_recommendation": "proceed"
}

示例 2：评测未通过 ​

输入：版本 1.3.0，评测成功率 88%

输出：

json
{
  "risk_level": "high",
  "blocking_issues": ["评测成功率 88% 低于阈值 95%"],
  "launch_recommendation": "abort"
}

references ​

version ​

  • 1.0.0 (2026-03-08): 初始版本