每个 Skill 由一个必需的 SKILL.md 文件和可选的打包资源组成。Skill 应建立在工作区的 .codebuddy/skills/ 目录下。

skill-name/ ├── SKILL.md (必需) │ ├── YAML frontmatter 元数据 (必需) │ │ ├── name: (必需) │ │ └── description: (必需) │ └── Markdown 指令 (必需) └── Bundled Resources (可选) ├── scripts/ - 可执行代码 (Python/Bash 等) ├── references/ - 旨在根据需要加载到上下文中的文档 └── assets/ - 用在输出中的文件 (模板、图标、字体等)

SKILL.md (必需)

这是 Skill 的核心定义文件。

元数据 (YAML Frontmatter):name 和 description 决定了 AI 何时会使用这个 Skill。描述需具体说明 Skill 的功能和使用场景。

示例：

--- name: pdf-editor description: This skill should be used when users ask to modify, rotate, or extract text from PDF files. allowed-tools: # 可选，指定允许使用的工具 disable: false # 可选，是否禁用 --- # PDF Editor To rotate a PDF...

打包资源 (可选)

1. Scripts (scripts/)

用于需要确定性可靠性或被重复重写的任务的可执行代码。

用途：当代码被重复重写或需要高可靠性时。

示例：scripts/rotate_pdf.py 用于 PDF 旋转。

2. References (references/)

旨在根据需要加载到上下文中以辅助 AI 思考的文档和参考资料。

用途：数据库架构、API 文档、领域知识、公司政策等。

优势：保持 SKILL.md 精简，仅在 AI 确定需要时才加载。

3. Assets (assets/)

不打算加载到上下文中，而是用于 AI 生成的输出中的文件。

用途：品牌资产、PPT 模板、HTML/React 样板代码等。

渐进式披露设计原则

Skills 使用三级加载系统来高效管理上下文：

元数据 (Metadata)：始终在上下文中 (~100 词)。

Skill 主体 (SKILL.md body)：当 Skill 被触发时加载 (<5k 词)。

打包资源 (Bundled resources)：按需由 AI 加载 (无限制)。