如何封装一个自己的 Skill

Skill 是模块化、可自包含的能力包，通过提供专门知识、工作流和工具来扩展 AI Agent 的能力。以下是完整的创建流程：

技能目录结构

每个技能由一个必需的 SKILL.md 文件，以及可选的打包资源组成：

my-skill/
├── SKILL.md          （必需）使用说明与指导
└── 打包资源（可选）
    ├── scripts/      可执行代码（Python/Bash 等）
    ├── references/   按需加载的参考文档
    └── assets/       输出时使用的文件（模板、图标、字体等）

创建流程（6 步）

第 1 步：理解技能的使用场景

明确这个技能要解决什么问题，收集具体的使用示例。例如：

• "帮我旋转这个 PDF"

• "帮我生成一份销售报表"

• "帮我把这段视频转成文字"

第 2 步：规划可复用的资源

针对每个使用示例，分析哪些内容适合沉淀为可复用资源：

第 3 步：初始化技能

运行初始化脚本自动生成模板目录：

scripts/init_skill.py my-skill --path skills/public --resources scripts,references

该脚本会自动创建技能目录、生成带 frontmatter 的 SKILL.md 模板，以及按需创建资源目录。

第 4 步：编辑 SKILL.md

Frontmatter（YAML 元数据）：

---
name: my-skill
description: 描述技能做什么以及何时触发。这是最重要的触发机制，应清晰说明适用场景。
---

• description 是 Agent 判断是否触发技能的核心依据，必须写清楚做什么和何时用

• 不要添加 name 和 description 以外的字段

正文（Markdown 使用说明）：

• 使用祈使式/不定式风格编写

• 保持简洁，控制在 500 行以内

• 只补充 Agent 原本不知道的信息

• 如果内容较多，将详细内容拆分到 references/ 目录，在 SKILL.md 中引用即可

第 5 步：测试并打包

先测试脚本确保功能正确，然后运行打包命令：

scripts/package_skill.py path/to/my-skill

打包脚本会自动校验以下内容：

• YAML frontmatter 格式与必填字段

• 技能命名规范与目录结构

• 描述的完整性

校验通过后生成 .skill 文件（本质上是 zip 格式），可直接分发给他人使用。

第 6 步：基于真实使用迭代

在实际任务中使用技能，观察不足之处，持续优化 SKILL.md 和打包资源。

核心设计原则

1. 简洁优先 -- 上下文窗口是共享资源，每段信息都要问"Agent 真的需要这个吗？"

2. 渐进式披露 -- 元数据始终可见 → SKILL.md 触发时加载 → 打包资源按需加载，层层递进

3. 设定合适的自由度 -- 操作脆弱的任务给严格护栏（固定脚本），灵活的任务给更多自主空间（文本说明）

4. 避免冗余 -- 同一信息只存在于 SKILL.md 或 references 之一，不要两边重复

命名规范

• 只使用小写字母、数字和连字符

• 长度控制在 64 字符以内

• 优先使用动词导向的短语，如 rotate-pdf、build-dashboard