md-tools 最核心的一节：写出一份合格的 SKILL.md，把技能的名字、描述、用法、安全预览规则都定义好。frontmatter 里的 name 和 description，直接决定 Pi 会不会在合适的时机调用它。技能的本质：一个带 SKILL.md 的目录
官方说得非常直白：一个技能就是一个目录，里面有个 SKILL.md，其他东西都随意。 目录结构参考：
my-skill/
├── SKILL.md # 必需：frontmatter + 指令
├── scripts/ # 辅助脚本
│ └── process.sh
├── references/ # 按需加载的详细文档
│ └── api-reference.md
└── assets/
└── template.json
对 md-tools，你已经有 index.js 和 README，正好可以放进 scripts/ 和 references/，稍作调整就能成为一个技能包。
frontmatter：技能的「身份证」
SKILL.md 顶部用 frontmatter（--- 包起来）声明元信息。官方给了标准字段：
| 字段 | 必填 | 说明 |
|---|---|---|
name |
是 | 最多 64 字符；小写字母、数字、连字符 |
description |
是 | 最多 1024 字符；技能做什么、何时用 |
license |
否 | 许可证名或指向打包文件的引用 |
compatibility |
否 | 最多 500 字符；环境要求 |
metadata |
否 | 任意键值映射 |
allowed-tools |
否 | 预批准工具的空格分隔列表（实验性） |
disable-model-invocation |
否 | 为 true 时技能从系统提示词隐藏，只能 /skill:name 调用 |
一个最小但合格的 md-tools 技能头：
---
name: md-tools
description: 处理 markdown 文件的工具箱。提供 stats（统计字数/段落/标题）、convert（转纯文本）、rename（改名，操作前先预览）。处理 .md 文档时使用。
---
name 的规则：小写 + 连字符
官方对 name 有严格要求：
- 1 到 64 个字符
- 只能小写字母、数字、连字符
- 不能以连字符开头或结尾
- 不能有连续的连字符
| 合法 | 非法 |
|---|---|
pdf-processing |
PDF-Processing |
data-analysis |
-pdf |
code-review |
pdf--processing |
注意一个 Pi 的特别之处：官方不要求技能名跟父目录同名（Agent Skills 标准里要求，但 Pi 认为这对共享技能目录不利，所以放宽了）。不过为了清晰，还是建议保持一致。
description：决定它何时被调用
description 是技能的「自我介绍」，直接决定 agent 何时加载它。文档给了好坏的对比：
好的：
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.
差的：
description: Helps with PDFs.
看出区别了吗？好的描述说清做什么 + 什么时候用，差的太笼统。对我们，把它翻成 md-tools 的中文描述也要遵守同样原则：具体到「能做什么、遇到什么任务该用」。
落地练习：写出你的第一份 SKILL.md
- 在
~/.pi/agent/skills/下建md-tools/，写一份SKILL.md，frontmatter 含合格的name和具体的description - 正文里用
## Setup、## Usage分节，写清三个命令的用法和「先预览再执行」的安全规则 - 用相对路径引用你的
index.js（比如./scripts/index.js）
怎么判断做对了？——frontmatter 能被识别（无加载警告），
/skill:补全能看到它，描述足够具体。
卡住了怎么办？ 有警告 → 检查 name 是否违规（大小写/连字符）。加载不出来 → 确认 description 没缺（缺 description 的技能不会被加载）。不知道正文怎么写 → 先只写名字和描述，正文照抄 README 的用法。
常见坑：description 写得「太抽象」
最常见的失败原因：description: 帮助处理 markdown。 这种话等于没说——agent 根本不知道何时该用你，于是永远不加载。
记住：description 是「匹配触发器」，不是「简介」。 它必须写出「做什么 + 何时用」。对 md-tools 就要写清 stats/convert/rename 各自干什么、处理 markdown 文档时调用。越具体，命中率越高。
小结
- 技能 = 一个目录 +
SKILL.md，其他随意 - frontmatter 关键字段：
name、description必填 name要小写+连字符，不能前后/连续连字符description决定何时调用，要具体- Pi 不强制 name 与目录同名（与标准不同）
下一节，让技能「活」起来——用 /skill:name 调用它，并跨 Harness 复用。