Skill 文件结构解剖

每个 Skill 由一个核心文件 SKILL.md 和可选的 resources/ 目录组成。

完整结构

my-skill/
├── SKILL.md              # 必需：Skill 入口文件
└── resources/            # 可选：附加资源
    ├── examples.md       # 使用示例
    ├── reference.md      # 参考资料
    ├── templates/        # 模板文件
    │   └── report.md
    └── scripts/          # 辅助脚本
        └── validate.sh

SKILL.md 详解

SKILL.md 使用 Markdown + YAML Frontmatter 格式：

---
name: my-awesome-skill
description: |
  Short one-line summary of what this Skill does.
  Used for trigger matching — be specific and distinct.
metadata:
  type: workflow
  version: "1.0"
triggers:
  - "do the thing"
  - "run awesome workflow"
  - "awesome skill"
allowed-tools:
  - Bash
  - Read
  - Write
---

# My Awesome Skill

## When to Use
- Scenario A: ...
- Scenario B: ...

## Workflow
1. Step one — do this
2. Step two — do that
3. Step three — verify

## Output Format
- Result should include...
- Always check...

## Notes
- Edge case: ...
- Limitation: ...

Frontmatter 字段

字段	必需	说明
name	是	kebab-case 唯一标识符
description	是	一行描述，用于触发匹配
triggers	否	额外的触发关键词列表
allowed-tools	否	限制 Skill 可用的工具
metadata.type	否	Skill 分类

Prompt 部分

Frontmatter 之后的所有 Markdown 内容是 Prompt 部分。这是 Skill 的核心——描述 Skill 的行为、工作流程和领域知识。

编写要点

• 明确边界: 清楚说明什么情况用、什么情况不用
• 步骤清晰: 工作流程用编号列表
• 输出规范: 说明期望的输出格式
• 反面案例: 列出常见错误和反面模式

Resources 目录

resources/ 下的文件不会被自动加载到上下文，但 Claude Code 可以在需要时读取。

• 适用场景: 长篇参考文档、模板、数据文件
• 不适用场景: 核心工作流程描述（应该放在 SKILL.md 中）

下一步

• Frontmatter 配置 — 深入 Frontmatter 字段
• Prompt 设计 — Prompt 编写最佳实践