Claude Skill 核心构建指南

1. 核心设计理念：三层渐进式披露

不要把所有指令塞进一个文件。优秀的 Skill 应该按需加载，节省 Token 并提高精准度：

第一层：触发器 (YAML)

常驻系统提示词。只告诉 Claude “我是谁，什么时候叫我”。

第二层：核心指令 (SKILL.md)

触发后加载。包含具体的工作流、质量检查清单和输出模板。

第三层：外部文件挂载

按需读取。存放外部知识库 (references/)、UI 资产 (assets/) 或 Python 自动化脚本 (scripts/)。

2. 规范的工程目录结构

将 Skill 视为一个微型软件项目，必须严格遵守文件命名和结构规范：

your-skill-name/               # 文件夹名必须是全小写、短横线 (kebab-case)
├── SKILL.md                   # 必选 核心文件 (文件名必须全大写)
├── scripts/                   # 可选 存放 Python/Bash 自动化验证脚本
│   └── validate.py
├── references/                # 可选 存放业务知识库、API文档、规范红线
│   └── brand_guidelines.md
└── assets/                    # 可选 存放Logo图片、HTML模板文件
    └── report_template.md

🚨 绝对避坑指南：
1. 文件夹内 绝对不要放 README.md，这会干扰 Claude 读取指令！(如果要开源发 GitHub，README 放在仓库最外层)。
2. SKILL.md 必须完全匹配大小写，不能是 skill.md 或 SKILL.MD。

3. 编写高质量触发器 (Frontmatter)

YAML 部分决定了你的 Skill 会不会被 Claude “过度触发”或“触发不足”。

❌ 错误示范

---
name: My Report Writer
description: 写报告用的。
---

名字带空格、大写（违规）。
描述太模糊，没写触发条件。

✅ 规范示范

---
name: business-report-generator
description: 生成具备固定VI元素的商业报告。当用户请求撰写报告、提供业务数据分析时触发。不适用于写私人邮件。
---

做什么：生成VI元素的商业报告。
何时用：请求撰写报告时（正向触发）。
何时不用：写私人邮件时（负向触发）。

4. 高阶工作流：迭代修正模式 (Iterative Refinement)

告别“一次性输出”，教 Claude 像人类专家一样“打稿 -> 质检 -> 修改 -> 交付”。

核心指令写法示例 (放置于 SKILL.md 中)：

### Phase 1: Context & Knowledge (加载知识)
1. 动笔前，必须先读取 `references/brand_guidelines.md` 中的品牌规范。

### Phase 2: Initial Draft (内部打稿)
1. 生成初稿，保存为临时文件 `draft.md`。
2. **严禁向用户直接展示初稿。** (Do not show this draft to the user yet.)

### Phase 3: Python Validation (代码质检)
1. 在后台静默运行: `python scripts/validate.py --file draft.md`。

### Phase 4: Refinement Loop (打回重造)
1. 若脚本报错，必须修改对应问题并重新运行脚本。
2. **重复此步骤，直到脚本输出“验证通过”。**

### Phase 5: Finalization (最终交付)
1. 只有验证通过后，才将最终报告输出给用户。

5. 测试、分发与调用

1如何进行严格测试？

正反向触发测试： 故意输入无关话题（如“今天天气”），确保 Skill 保持安静不乱抢戏。
功能测试： 检查输出是否 100% 带有 Logo、序列号等硬性规范。

2如何分发给团队？ (Claude.ai 网页版)

将 your-skill-name/ 整个文件夹打包成 .zip 压缩包。进入 Claude 左下角设置 Settings -> Capabilities -> Skills -> Upload skill 即可启用。

3如何在代码终端调用？ (Claude Code)

无需打包 Zip，直接将文件夹原封不动拖入本地的 skills/ 目录下。在终端输入触发指令，Claude 就会在后台自动读取并执行你的 Python 质检脚本！