把 md-tools 封装成 Skill

目标：从「脚本」到「技能包」

入门课的 md-tools 是一堆脚本 + README + AGENTS.md。这一节把它收进标准的技能目录结构：

md-tools/
├── SKILL.md            # frontmatter + 指令
├── scripts/
│   └── index.js        # 你入门课写的工具箱
└── references/
    └── usage.md        # 详细用法（可放原 README）

用到的正是 M02 学过的结构。现在把技能名定为 md-tools，放全局 ~/.pi/agent/skills/，让它处处可用。

第一步：写合格的 SKILL.md

frontmatter 要满足 M02 的规则：name 小写+连字符、description 具体到「做什么 + 何时用」：

---
name: md-tools
description: 处理 markdown 文件的工具箱。提供 stats（统计字数/段落/标题）、convert（转纯文本）、rename（改名，操作前先预览确认）。处理 .md 文档、整理 markdown 内容时使用。
---
# MD Tools

处理 markdown 文件的命令行工具箱，调用脚本 scripts/index.js。

## 命令

- stats <file>     统计字数、段落数、标题数
- convert <file>   转为纯文本并输出
- rename <file>    预览改名，确认后才执行

## 安全规则

任何会改动文件的操作，先打印「将做什么」并等待确认，尤其是 rename。

记住 M02 的教训：description 别写「帮助处理 markdown」这种空话，要能触发模型在合适的时机调用。

第二步：把脚本和文档收进包

把你的 index.js 放进 scripts/，把用法说明放进 references/。在 SKILL.md 里用相对路径引用：

## 用法

```bash
./scripts/index.js stats 文档.md
./scripts/index.js convert 文档.md
./scripts/index.js rename 文档.md

详见 用法参考。

相对路径是技能跨目录复用的关键——**整个 `md-tools/` 目录搬到任何项目里，引用都不破。**

---

## 第三步：分层放技能

想清楚给谁用，决定放哪：

| 用法 | 位置 |
| --- | --- |
| 所有项目都能用 | `~/.pi/agent/skills/`（全局） |
| 只给本项目 | `.pi/skills/`（项目级，需信任） |
| 给 Claude Code 共享 | 加进 `settings.json` 的 `skills` |

对我们，放全局最符合「一键复用」的目标。同时验证项目已被信任，项目级资源才能加载。

---

## 落地练习：把 md-tools 打包成技能

1. 建 `~/.pi/agent/skills/md-tools/`，把 SKILL.md、scripts/、references/ 放好
2. 启动 pi，确认 `/skill:md-tools` 能看到并加载它
3. 到另一个项目目录里，用 `/skill:md-tools stats README.md` 验证「跨项目可用」

> 怎么判断做对了？——技能在任何项目都能被 `/skill:md-tools` 加载，且能通过相对路径正确调用脚本。

**卡住了怎么办？** 加载不出 → 检查 SKILL.md 的 name/description 是否合格、位置是否被扫描。跨项目失效 → 确认放进了全局目录。脚本路径错 → 检查相对路径是否写对。

---

## 常见坑：把整个项目塞进技能目录

容易贪多：把 `node_modules`、无关文件全塞进技能包。**技能要「够用就好」**——只放 SKILL.md、需要的脚本、按需加载的参考文档。

包越大，越难维护、越难共享、越容易带上多余依赖。`md-tools` 只需要脚本和一份用法说明，其他别塞。

---

## 小结

1. 技能结构：SKILL.md + scripts/ + references/，相对路径引用
2. frontmatter 的 name / description 要合格且具体
3. 全局放 `~/.pi/agent/skills/` 实现跨项目复用
4. 项目级需信任；跨工具用 `skills` 设置共享
5. 技能要够用就好，别整包塞进来

下一节，用 Extension 注册自定义命令，把 md-tools 完整跑通。