用途
skill-authoring 用于编写 pi 技能。技能是 Markdown 文件（SKILL.md），用来教智能体完成它默认不会的事情。每个技能覆盖单一领域内的一个或多个用例，例如“NixOS 配置管理”下可包含系统更新、home manager、包搜索等子领域。当用户请求与触发描述匹配时，智能体会加载整个文件。
文件布局
my-skill/
├── SKILL.md # Frontmatter + workflow instructions (keep under 120 lines)
├── references/ # Deep docs loaded on demand (API specs, advanced patterns)
└── scripts/ # Helper scripts the agent runs directly
模板和智能体在输出中使用的文件放在 assets/。scripts/ 中的脚本是确定性代码，不会在每次调用时被重写。
Frontmatter
每个技能都需要 name、description 和 keywords。其他字段取决于技能类型。
必填字段：
---
name: my-skill-name # kebab-case, matches directory name (max 64 chars)
description: "Does X. Use when Y."
keywords: ["keyword1", "keyword2", "keyword3"]
---
- name：仅小写字母、数字、连字符，不能以连字符开头或结尾。
- description：带引号的字符串。第一句以动词开头，第二句以“Use when”开头。
- keywords：单个小写单词组成的数组，用于评分。每个单词匹配得 1.0 分，至少需要 2 个匹配（分数 >= 2.0）才会被注入。应选择用户实际会输入的词，并避免与其他技能共用关键词。
按类型可选的字段：
工具类技能（位于 tools/ 目录，name 等于工具名）：
related: [other-skill] # co-inject related skills
知识类技能（领域知识）：
topic: State-Space Search # required — display heading in injected block
token_cost: 120 # estimated token budget (default: 150)
requires_tools: [read, find] # tools needed before this skill fires
协议类技能（行为规则）：
topic: Conventional Commits # required — display heading in injected block
正文结构（120 行以内）
# Skill Name
One-line summary of the domain this skill covers.
## Workflow / Commands
Step-by-step examples or command reference with inline code snippets.
## Details
Common variations, edge cases, or tricky parts specific to this domain.
## Constraints / Best Practices
Rules, gotchas, and things the agent must do (or not do).
See [deep reference](references/DEEP.md) for API specs and advanced usage.
- Workflow/Commands：编号步骤，配具体的内联示例——命令、代码片段或配置。
- Details：主要用例变体的简短上下文。
- 深入内容链接到 references/，只允许一层链接。
现有技能示例
好的示例——聚焦领域、多个用例：
# nh: one domain (Nix operations), three sub-domains (system updates, home manager, package search)
description: "Switches NixOS/Home Manager configurations, cleans old generations, and performs system maintenance. Use when running os/home switch, pruning the Nix store, or managing system generations."
好的示例——领域内单一用例：
# transcribe-audio: one domain (audio transcription), one primary use case
description: "Transcribes audio files to text using whisper-cpp. Use when converting speech to text, transcribing podcasts, lectures, or meetings."
校验清单
- name 为 kebab-case 且与目录名完全一致
- description 是带引号的字符串，含动词开头的句子 + “Use when...” 子句
- keywords 为单个小写单词，每个技能至少 3 个
- 知识与协议类技能需有 topic
- related 列出逻辑相关的技能以便共同注入
- 正文在 120 行以内（超出部分移到 references/）
- 每个关键概念至少有一个具体的内联示例
- SKILL.md 与 references 之间无重复内容
- 所有文件链接指向存在的路径
- keywords 不与其他技能冲突
常见错误
- description 使用 > 折叠符而非带引号字符串——应改为带引号字符串
- 缺少“Use when...”子句——应补充触发条件
- SKILL.md 与 references 内容重复——细节只保留在 references
- 对智能体已知概念做冗长解释——应删除
- 智能体永远不会读取的多余文件（README、changelog）——应移除