Claude Code Skills Guide

Claude Code Skills 完整指南

⚠️ 核心约束

1. 创建 Skill 前 MUST 使用 AskUserQuestion 确认配置
2. SKILL.md 行数 MUST ≤200 行
3. 副作用型 Skill MUST 设置 disable-model-invocation: true
4. 回答问题 MUST 从 reference/ 读取，MUST NOT 编造

执行模式

$ARGUMENTS

模式 A：创建 Skill

流程（按顺序执行）

步骤 1：捕获意图 → 步骤 2：判断配置 → 步骤 3：确认配置 → 步骤 4：编写 → 步骤 5：验证

步骤 1：捕获意图

如果对话中已有工作流程，提取：工具、步骤、修正、输入输出。

如果信息不完整，询问：

• 这个 Skill 做什么？
• 什么时候触发？
• 输出格式是什么？

步骤 2：判断配置

功能模式：

调用控制：

步骤 3：确认配置

⚠️ MUST 使用 AskUserQuestion 确认三个问题：

问题 1 - 功能类型：

{
  "questions": [{
    "question": "确认 Skill 功能类型：",
    "header": "功能",
    "multiSelect": false,
    "options": [
      {"label": "文档/资产创建", "description": "生成文档、模板、配置文件"},
      {"label": "工作流程自动化", "description": "自动化多步骤工作流"},
      {"label": "多 MCP 协调", "description": "跨多个 MCP 服务器操作"}
    ]
  }]
}

问题 2 - 调用控制：

{
  "questions": [{
    "question": "确认调用控制方式：",
    "header": "调用",
    "multiSelect": false,
    "options": [
      {"label": "副作用型", "description": "deploy/commit → 只能手动触发"},
      {"label": "背景知识型", "description": "架构/规范 → 自动加载"},
      {"label": "普通工作流", "description": "默认配置"}
    ]
  }]
}

问题 3 - 工具权限：

{
  "questions": [{
    "question": "选择需要的工具（免确认）：",
    "header": "工具",
    "multiSelect": false,
    "options": [
      {"label": "只读", "description": "Read Grep Glob"},
      {"label": "修改", "description": "读写 + Edit Write"},
      {"label": "Git/GitHub", "description": "Bash(gh/git *) + 读写"},
      {"label": "无限制", "description": "不设置"}
    ]
  }]
}

步骤 4：编写 SKILL.md

Frontmatter 规范：

description 格式：

<功能简述>。当用户说"<关键词>"时触发。即使用户提到<相关概念>，也应使用此 skill。

步骤 5：验证

✅ 检查点：

• name 合规
• description 有触发关键词且 pushy
• 副作用型已设置 disable-model-invocation: true
• 背景知识型已设置 user-invocable: false
• 行数 ≤200

wc -l <skill-dir>/SKILL.md

模式 D：优化 Skill

诊断

优化

检查点

• 行数 ≤200
• description 已优化
• 配置正确

模式 E：打包

python scripts/quick_validate.py <skill-dir>
python scripts/package_skill.py <skill-dir>

模式 B：解答问题

MUST 从 reference/ 读取，MUST NOT 编造。

模式 C：快速参考

目录结构

skill-name/
├── SKILL.md              # MUST - ≤200行
├── reference/            # 可选
├── scripts/              # 可选
├── agents/               # 可选
└── evals/                # 可选 - 测试用例

Frontmatter

两层分类

详细资源（按需读取）

Agents（按需委托）

脚本

核心流程

理解需求 → 确认配置 → 编写 Skill → 测试验证 → 改进 → 打包

MUST 使用 TaskList 追踪进度。