SKILL 文档编写

SKILL front matter 完整模板

入口文件顶部使用 YAML 围栏（两行 ---）包住元数据。以下是包含所有必要字段的完整模板：

---
name: skill-kebab-name          # kebab-case，与仓库路径一致
description: |
  一句话说明：何时触发、输入是什么、产出是什么、禁止做什么。
  示例：当用户要求审查 PR 时；输入 diff 文本；产出结构化评审报告；禁止直接修改代码。
version: "1.2.0"                # 语义化版本，破坏性变更升 major
triggers:
  - "审查.*PR|review.*pull request"   # 正则匹配用户意图
  - "代码审查|code review"
  - "检查.*代码质量"
steps:
  - id: step-1
    action: 读取 diff 文本，提取变更的文件列表
  - id: step-2
    action: 对每个文件检查命名规范、函数长度、注释覆盖
  - id: step-3
    action: 检查安全问题（SQL 注入、未验证输入、硬编码密钥）
  - id: step-4
    action: 输出 JSON 格式的评审结果
constraints:
  - 禁止直接修改用户代码，只输出建议
  - 禁止在评审结果中包含用户代码的完整副本
  - 每条评审意见必须包含行号和具体改法
examples:
  - input: "请审查这个 PR：[diff 内容]"
    output: '{"issues": [...], "summary": "...", "score": 85}'
output_format:
  type: json
  schema:
    issues: "array of {file, line, severity, message, suggestion}"
    summary: "string"
    score: "integer 0-100"
---

触发条件：好/坏对比

触发条件必须精确到可以用正则或关键词匹配——模糊的触发导致误触发或漏触发。

# ❌ 坏的触发条件——太模糊，任何编程问题都会触发
triggers:
  - "代码"
  - "帮我看看"
  - "有问题"

# ✅ 好的触发条件——精确描述任务类型、技术栈和动作
triggers:
  - "审查.*PR|review.*pull.?request"      # 明确动作：审查
  - "检查.*代码质量|code.?quality"         # 明确目标：质量
  - "找.*bug|debug.*代码"                  # 明确意图：调试
  - input_contains: ["diff", "patch"]      # 输入特征匹配

# ❌ 坏的 description——没有说明输入输出和边界
description: 帮助用户处理代码相关问题

# ✅ 好的 description——包含触发条件、输入、输出、禁止事项
description: |
  当用户提供代码 diff 或 PR 链接要求审查时触发。
  输入：unified diff 文本或 GitHub PR URL。
  产出：JSON 格式评审报告（问题列表、严重级别、改法建议）。
  禁止：直接修改代码；禁止在输出中包含完整代码副本。

• 每个 trigger 用独立正则，避免一个大正则难以维护。
• 在 constraints 中用否定形式写清禁止事项（"禁止X" 而非 "尽量不要X"）。

steps 粒度标准：每步必须是原子操作

每个 step 是一个可独立执行、可独立验证的原子动作。以下是 5 步代码审查 SKILL 的正确粒度示例：

# ❌ 粒度太粗——无法验证，模型不知道从哪里开始
steps:
  - 审查代码
  - 给出反馈

# ✅ 正确粒度——每步原子、有明确输入输出、可独立验证
steps:
  - id: step-1
    action: 解析 diff 文本，提取变更文件列表和变更行范围
    input: unified diff 字符串
    output: [{file, added_lines, removed_lines}]
    verify: 列表非空，每项包含 file 字段

  - id: step-2
    action: 对每个变更文件检查函数长度（超 50 行标记为 WARNING）
    input: step-1 的文件列表 + 原始代码
    output: [{file, line, type: "LONG_FUNCTION", message}]
    verify: 所有标记项都有 line 字段

  - id: step-3
    action: 检查安全问题（正则匹配 SQL 拼接、eval()、硬编码密钥模式）
    input: 变更行文本
    output: [{file, line, type: "SECURITY", severity: "ERROR", message}]
    verify: severity 只能是 ERROR/WARNING/INFO

  - id: step-4
    action: 合并 step-2 和 step-3 的结果，按 severity 降序排列
    input: step-2 + step-3 的 issues 列表
    output: 合并排序后的 issues 列表

  - id: step-5
    action: 输出 JSON 报告，计算总分（100 - ERROR*10 - WARNING*3）
    input: step-4 的 issues 列表
    output: '{"issues": [...], "summary": "...", "score": 0-100}'
    verify: score 在 [0, 100] 范围内

完整真实 SKILL 示例：代码审查

以下是一个生产可用的代码审查 SKILL 完整示例（25+ 行）：

---
name: code-review-pr
description: |
  当用户提供代码 diff 或 PR 内容要求审查时触发。
  输入：unified diff 文本。
  产出：JSON 格式评审报告，包含问题列表、严重级别和改法建议。
  禁止：直接修改代码；禁止在输出中复制完整源文件。
version: "2.0.0"
triggers:
  - "审查.*PR|review.*pull.?request"
  - "代码审查|code.?review"
  - input_contains: ["diff", "@@"]
constraints:
  - 禁止直接修改用户提交的代码
  - 每条问题必须包含 file、line、severity、message、suggestion 五个字段
  - severity 只允许 ERROR / WARNING / INFO 三个值
  - 输出必须是合法 JSON，不得包含 markdown 代码块包裹
steps:
  - id: parse-diff
    action: 解析 unified diff，提取变更文件列表和每个文件的变更行范围
    output: "list[{file: str, hunks: list[{start, lines}]}]"

  - id: check-style
    action: |
      对每个变更行检查：
      1. 函数超 50 行 → WARNING: LONG_FUNCTION
      2. 行长超 120 字符 → INFO: LONG_LINE
      3. 缺少文档注释（public 函数）→ WARNING: MISSING_DOCSTRING
    output: "list[Issue]"

  - id: check-security
    action: |
      用以下正则扫描变更行：
      - SQL 拼接：r"[\"'].*(SELECT|INSERT|UPDATE).*[\"']\s*\+" → ERROR
      - eval/exec 调用：r"\beval\s*\(|\bexec\s*\(" → ERROR
      - 硬编码密钥：r"(api_key|secret|password)\s*=\s*[\"'][^\"']{8,}" → ERROR
    output: "list[Issue]"

  - id: check-tests
    action: 检查变更的函数是否有对应测试文件；若变更 src/foo.py 但 tests/test_foo.py 未变更，输出 WARNING: MISSING_TEST_UPDATE
    output: "list[Issue]"

  - id: aggregate
    action: 合并所有 issues，按 severity 降序（ERROR > WARNING > INFO）排列
    output: "list[Issue] sorted"

  - id: score-and-report
    action: |
      计算总分：score = max(0, 100 - len(ERROR)*10 - len(WARNING)*3 - len(INFO)*1)
      输出完整 JSON 报告
    output: |
      {
        "issues": [{"file": "...", "line": 42, "severity": "ERROR",
                    "message": "...", "suggestion": "..."}],
        "summary": "发现 2 个 ERROR，3 个 WARNING",
        "score": 74
      }

examples:
  - input: |
      --- a/src/user.py
      +++ b/src/user.py
      @@ -10,3 +10,4 @@
       def get_user(id):
      +    query = "SELECT * FROM users WHERE id = " + id
           return db.execute(query)
    expected_issues:
      - {file: "src/user.py", line: 11, severity: "ERROR", message: "SQL 字符串拼接存在注入风险"}
---

  [ 对齐 name / description 与触发话术 ]
        |
        v
  [ 写 front matter 所有必要字段 ]
        |
        v
  [ 原子步骤（每步有 action/output/verify）]
        |
        v
  [ constraints 用否定形式写禁止事项 ]
        |
        v
  [ examples 含 input/expected 可验证 ]

Front matter 草稿实验室

在文本框中编辑草稿：左侧清单根据内容勾选常见 front matter 要点；右侧为只读预览，高亮行首 YAML 键与 Markdown 标题（便于扫读，仍以左侧为准编辑）。