04 · 创建自定义 Skill

03-探索内置Skills ｜ 下一篇 → 05-在API-Code-SDK中用Skills

目标

从零写一个自己的 Skill，掌握 SKILL.md 格式 + 渐进式披露这两个核心。

第一步：建文件夹

my-report-skill/
├── SKILL.md
├── reference.md        # 细节，按需加载
└── templates/
    └── weekly.md       # 周报模板

第二步：写 SKILL.md

---
name: weekly-report
description: 按公司规范生成周报。当用户说"写周报""周总结""本周汇报"时使用。
  会套用 templates/weekly.md 模板，输出包含进展/风险/下周计划三段。
---

# 周报生成

## 何时使用
- 用户要写周报 / 周总结 / 本周汇报

## 工作流
1. 收集：本周完成项、进行中、风险、下周计划
2. 套用 templates/weekly.md 的结构
3. 文风：简洁、动词开头、量化结果
4. 输出后自检：三段是否齐全、有没有空话

## 资源
- 模板：templates/weekly.md
- 详细文风规范与示例：见 reference.md

核心机制：渐进式披露（Progressive Disclosure）

智能体先只读 description（一两句），判断要不要用；决定用了，才读 SKILL.md 正文；需要更多细节时，才去读 reference.md / 模板。

第 1 层：description（始终可见，极短）   ← 决定"要不要触发"
   ↓ 触发后
第 2 层：SKILL.md 正文（何时用 + 步骤）   ← 决定"大致怎么做"
   ↓ 需要时
第 3 层：reference.md / 脚本 / 模板        ← 加载"具体细节"

好处：上下文不被一次性塞满——你可以写很厚的参考资料，但只有真正用到时才加载。

写好 Skill 的要点

1. description 是触发开关：写清「什么场景该用我」+ 关键词，写不好就不会被触发。
2. SKILL.md 保持精简：高层步骤 + 指向细节，别把整本手册塞进来。
3. 细节下沉：长 API、长示例放 reference.md；模板放 templates/。
4. 确定性步骤写成脚本：能用脚本保证的（解析、生成、校验），别让模型每次现编。
5. 加自检清单：让智能体做完自己核对，提高稳定性。

第三步：放对位置

• Claude Code：放到项目的 .claude/skills/<name>/ 或个人 ~/.claude/skills/。
• Claude.ai / API / Agent SDK：按各自方式注册（见 05-在API-Code-SDK中用Skills）。

本节实操

• 给你 第 1 节选的工作流写一个 SKILL.md
• 把细节拆到 reference.md，体会渐进式披露
• description 反复打磨，确保能被正确触发

下一篇 → 05-在API-Code-SDK中用Skills