vh992098059 Agent Skill 撰写指南（生成 SKILL.md）
何时使用本技能
用户希望新增或重写一个可被智能体加载的技能时：先根据需求确定技能目录名与用途，再按下方结构产出完整 SKILL.md 正文（含 frontmatter），必要时说明保存路径与如何在对话中通过 skill 工具加载。
目录与文件约定
- 每个技能一个子目录，目录名使用 kebab-case（小写、连字符），例如
pdf-form-filler。 - 目录内至少包含
SKILL.md；可选reference.md、examples.md或scripts/。 - 在本仓库中，运行时技能根目录一般为
backend/skills/，新技能路径为：backend/skills/<技能目录名>/SKILL.md
SKILL.md 必备结构
YAML frontmatter（文件最开头，用
---包裹）name：与目录名一致，仅小写字母、数字、连字符，长度 ≤ 64。description：必填，≤1024 字符。用第三人称写清「做什么 + 何时触发」，并包含用户可能说的关键词，便于检索与路由。
正文（Markdown）
- 一级标题：技能可读名称。
- 分节建议：
## 适用场景## 操作步骤## 约束与禁止## 示例（按需）。 - 指令要可执行：步骤编号、条件分支、输出格式（如表格、模板）写清楚。
- 避免空泛；避免与通用常识重复的长篇背景。
description 撰写要点
- 第三人称：例如「整理 Git 提交信息并生成符合 Conventional Commits 的说明」，不要写「我可以帮你…」。
- 同时包含 WHAT 与 WHEN：能力描述 + 触发词（如「用户提到 PR、commit、changelog」）。
- 若技能仅在本项目有效，可在 description 末尾一句点明（可选）。
生成新技能时的流程
- 澄清或推断：技能名称、主要任务、目标用户、是否仅本项目、是否需要示例或脚本。
- 定目录名：
name与文件夹名一致。 - 写完整 SKILL.md：frontmatter + 正文，一次性给出可直接保存的文件内容。
- 交付说明：告知保存路径为
backend/skills/<name>/SKILL.md；保存后需重启或确保skills.baseDir指向该目录，智能体即可通过skill工具按名称加载。
输出格式（给用户的回复）
- 优先用单个 Markdown 代码块给出完整
SKILL.md，便于复制保存。 - 若用户需要「同时生成 reference/example」，可另附第二个代码块或说明可选文件内容。
- 不要省略 frontmatter；不要省略对
name与目录名一致性的提醒。
反例（应避免）
- 仅有 slogan、无步骤；description 过短且无语境触发词。
- frontmatter 与正文标题不一致；
name含空格或下划线（不符合常见约定）。 - 把本技能用于「执行被生成技能的具体业务」——本技能只负责撰写技能文件，不负责执行生成后的领域任务（除非用户另有明确要求）。