skills-01.Skill 构建示例与 Agent 解析机制

本文是《skills-00.Agent Skills 学习路线与自建指南》的续篇：用一份可落地的最小示例，把 `SKILL.md` 里各块关键字/职责、撰写禁忌，以及 Agent 如何基于这些信息做发现、加载与调用串成一条可对照阅读的说明。

一、示例场景与目录结构

假设团队希望 Agent 在「写提交说明」「整理暂存区说明」时，统一遵循 Conventional Commits，并输出中英文可选、带 scope 的规范格式。
推荐目录名（小写、连字符）：

git-commit-conventional/
├── SKILL.md
├── reference.md          # 可选：类型与破坏性变更细则
└── scripts/              # 本示例可省略；复杂校验时再建
    # validate-msg.sh

下文 `SKILL.md` 全文即该 Skill 的唯一必填交付物；`reference.md` 演示渐进披露（正文只指路，细节另文件）。

二、完整示例：`SKILL.md`（含阅读要点）

下面是一份自洽可运行的示例；上方 YAML 与 下方 Markdown 正文 在运行时职责不同（见第三节）。

---
name: git-commit-conventional
description: >-
  Drafts Git commit messages in Conventional Commits format (type, optional scope,
  subject, body, footer). Use when the user asks for commit messages, conventional commits,
  提交说明, changelog-style commits, or staging/commit workflow wording.
---
# Conventional Commits（约定式提交）
## 何时启用本 Skill
- 用户要**生成/改写** `git commit -m` 文案，或描述「怎么写提交说明」。
- 用户提到 **feat/fix/docs/chore**、**scope**、**BREAKING CHANGE** 等。
## 输出格式（必须遵守）
1. **Subject 一行**（≤ 72 字符建议）：`<type>(<scope>): <subject>`
2. **空一行**
3. **Body**（可选）：说明动机与对比；可换行。
4. **Footer**（可选）：`BREAKING CHANGE:` 或 `Closes #123`。
**type 常用值**：`feat` `fix` `docs` `style` `refactor` `perf` `test` `chore` `ci` `build`。
## 工作流
1. 若用户未给出变更摘要：先根据**已打开文件/最近 diff** 归纳 1～2 句「做了什么」。
2. 选定 **type**；若影响面清晰，给 **scope**（目录或模块名，小写）。
3. **subject** 使用祈使语气（「添加」而非「已添加」），不加句号。
4. 若 API 行为不兼容：在 footer 写 **BREAKING CHANGE** 说明迁移方式。
## 更多规则与示例
完整类型说明、反例与多语言 subject 习惯，见同目录 [reference.md](reference.md)。
## 自检清单（输出前在内心过一遍）
- [ ] type 是否反映**真实变更性质**（避免用 `chore` 掩盖功能变更）。
- [ ] subject 是否**一句说清**、无模糊词（如 update/fix 无宾语）。
- [ ] 若用户要中文 subject：**仍保持** `type(scope):` 前缀，subject 可为中文。

阅读要点（对应后文「字段表」）：

--- 之间的 YAML：参与 技能注册与发现，通常整段较短，模型会频繁「看见」的是其中的 description。
# 开始的正文：在 Skill 被选中之后才作为操作手册加载，用来约束推理步骤与输出形态。
相对链接 [reference.md](reference.md)：告诉 Agent 下一步可读哪个文件；是否读取由当前任务需要决定（渐进披露）。

三、各部分「关键字」作用与撰写注意事项

1. YAML 元数据（机器与路由层）

关键字	是否必填	作用	撰写注意事项
`name`	是	Skill 的稳定标识（目录名往往与之对齐）；供工具链、日志与人类排查。	小写字母、数字、连字符；短而可区分；避免 `helper`、`utils` 等泛名。长度上限以产品文档为准（常见 ≤ 64 字符）。
`description`	是	技能发现的主信号：运行时把它放进「可选技能摘要」里，供模型做意图 ↔ 技能匹配。	第三人称、一句能力 + 多组触发词（中英、用户口语）。避免空泛；不要把长篇步骤写进 `description`。可用 YAML 多行 `>-` 保持可读。
`license` 等	视生态而定	部分模板或市场规范要求声明许可证。	若无可省略；与仓库根 `LICENSE` 保持一致，避免矛盾。
常见失误：

description 只写「帮助写代码」，没有 WHEN → 模型难以在「写提交说明」场景选中该 Skill。
把几千字规范塞进 description → 浪费路由上下文，且与「正文后载」的设计相悖。

2. Markdown 正文（触发后的「执行手册」）

结构块	作用	撰写注意事项
一级标题 `#`	人类与 Agent 的技能名片；部分界面用它展示标题。	与 `name` 语义一致即可，可读性优先。
`## 何时启用`	显式触发条件，减少误触发与漏触发。	写用户原话可能出现的词（如「提交说明」「conventional」）。
`## 输出格式` / 模板	强约束输出，降低格式漂移。	给最小可用模板；需要多场景时用「若…则…」分支，避免 20 种并列自由发挥。
`## 工作流`（步骤）	链式推理顺序：先收集信息再落笔。	步骤可执行；若依赖 `git diff`，写明「向用户确认是否允许读取」。
自检清单	输出前自查，适配无外部脚本的场景。	条目可勾选、与团队红线一致。
指向 `reference.md`	渐进披露：正文保持短，细节外置。	`reference.md` 内避免再链到 `ref2/ref3` 过深；一层为宜。

3. 可选文件：`reference.md` / `scripts/` / `assets/`

路径	作用	Agent 典型用法
`reference.md`	长说明、条款、API 片段	按需读取：当 `SKILL.md` 指向它且任务需要细节时，再加载进上下文。
`scripts/`	可执行脚本	执行（拿结果）或只读（改环境前慎用）；Skill 内应写明推荐命令与期望输出。
`assets/`	模板、图片、样例文档	多用于生成物拼装；未必整文件进上下文。

`scripts/` 里可以写什么语言？

规范层面：Cursor / Claude 类 Skill 文档没有规定 scripts/ 只能放某一种语言——它就是普通文件目录，真正能否跑起来取决于 Agent 执行命令时所用的环境（本机 PATH、解释器、用户是否批准运行终端命令等）。
实践上常见、文档示例里也最多出现的是：

类型	说明
Shell	`bash` / `sh`（Linux、macOS、WSL）；Windows 上常见 cmd / PowerShell（`.ps1`）。
Python	`python scripts/foo.py`，需已安装对应版本与依赖。
Node.js	`node scripts/foo.mjs` 等，需已安装 Node。
其他	只要能用一条可重复命令启动（如 `ruby`、`go run`），理论上都可；但跨机器复现时负担更大，Skill 里应写清依赖与命令。
撰写注意（与官方 create-skill 一致）：路径用正斜杠 `scripts/helper.py`；在 `SKILL.md` 里写清推荐调用方式（如 `python scripts/validate.py`）以及期望退出码/输出，便于 Agent 执行与排错。
注意：是否「自动执行脚本」取决于 Agent 权限与沙箱，Skill 里应写清需要用户批准的情形。

四、Agent 如何解析与调用（概念模型）

下面用与实现细节解耦的方式描述「从用户输入到 Skill 生效」的常见链路。实际栈可能把部分步骤放在客户端 / 编排层 / 模型中不同模块完成。

1. 注册阶段（Skill 安装或项目加载时）

flowchart LR
  subgraph scan[扫描 skills 目录]
    D[各子目录中的 SKILL.md]
  end
  D --> P[解析 YAML frontmatter]
  P --> R[注册表: name + description + 路径]

解析对象：主要是 YAML，得到每条 Skill 的 name、description 与文件位置。
不一定会把整个 Markdown 正文塞进常驻上下文；正文多为 按需加载。

2. 匹配阶段（用户发来一条请求）

flowchart TD
  U[用户自然语言请求] --> C[当前对话上下文 + 可用技能摘要]
  C --> M[模型根据语义做技能匹配]
  M -->|命中| S[选定 Skill: name]
  M -->|未命中| X[按通用能力回答或追问]

模型「看见」的：通常是各 Skill 的 description（及可能有的 name），而不是全部正文。
匹配依据：用户问题中的任务类型、对象、关键词 与 description 中的 WHAT/WHEN 是否对齐。

3. 加载与执行阶段（Skill 被选中后）

flowchart TD
  S[已选 Skill] --> L[加载 SKILL.md 正文到上下文]
  L --> F{需要 reference 或脚本?}
  F -->|是| R[读取/执行 并带回结果]
  F -->|否| O[按步骤生成回复或工具调用]
  R --> O

正文加载：SKILL.md 中 Instructions / 工作流 / 模板 成为当前轮及后续若干轮的高优先级指令（与系统提示、用户消息共同作用）。
多轮交互：若信息不足，Agent 按 SKILL.md 的「先问再写」顺序追问；追问策略也由正文约束。
工具调用：若正文要求「运行某脚本」，则走 终端 / MCP 等通道；成功与否再反馈到对话。

4. 与「Rules / 系统提示」的关系（直觉）

层级	典型内容	与 Skill 的关系
全局 Rules	全仓库写作风格、安全红线	始终偏强；Skill 不应与之冲突。
Skill	某一类任务的专项 SOP	仅在命中场景加载，专项覆盖通用。
用户当轮指令	「这次只要一行 subject」	当轮优先；Skill 内应允许「用户显式覆盖模板」。

五、配套 `reference.md` 示例片段（可选）

为保持 SKILL.md 篇幅可控，可将 类型语义、破坏性变更示例 放到 reference.md。撰写时注意：

标题分级清晰，便于 Agent 局部引用。
避免与 SKILL.md 重复同一段；一处为「流程」，一处为「词典」。

六、验收：怎样算「这个 Skill 写好了」

冷启动：新对话只说「帮我写个符合约定式提交的 message，这次是加了一个登录校验」，Agent 能选中本 Skill 并给出 带 type/scope 的结果。
负例：用户问「这行 Python 为什么报错」，不应只因仓库里有本 Skill 就强行写 commit message。
可维护：团队改 commit 规范时，只改 SKILL.md + reference.md，不拆散到多份口头文档。

小结

name / description：面向 路由与发现——要短、要准、description 必须含 场景关键词。
正文：面向 触发后的执行——步骤、模板、自检、外链分工明确。
Agent 行为：先 用 description 做技能匹配，再 加载正文与按需资源，在多轮对话中按正文 推进流程；具体注入格式随产品迭代可能变化，以官方文档为准。
前篇总览见：skills-00.Agent Skills 学习路线与自建指南。

本文是 《skills-00.Agent Skills 学习路线与自建指南》 的续篇：用一份可落地的最小示例，把 SKILL.md 里各块关键字/职责、撰写禁忌，以及 Agent 如何基于这些信息做发现、加载与调用 串成一条可对照阅读的说明。