| name | skill-authoring |
| description | 指导如何从零撰写或改写符合 Agent/Cursor 约定的 SKILL.md（含 YAML 头、触发描述、步骤与示例）。适用于用户要求「新建技能」「生成 Agent Skill」「写一个 SKILL.md」「给项目加技能」等场景；输出可直接落盘到 skills 目录供 skill 工具加载。 |
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 含空格或下划线（不符合常见约定）。
- 把本技能用于「执行被生成技能的具体业务」——本技能只负责撰写技能文件，不负责执行生成后的领域任务（除非用户另有明确要求）。
