基础篇

目录¶

1. Skill 出现的背景
   • 1.1 AI 编程助手的上下文困境
   • 1.2 从 prompt 到可复用的知识单元
2. Skill 基本介绍
   • 2.1 一个 Skill 长什么样
   • 2.2 两种分类维度
   • 2.3 调用方式
   • 2.4 Frontmatter 字段参考
3. 部署位置与适用场景
   • 3.1 什么时候不需要 Skill
   • 3.2 创建你的第一个 Skill：先迭代，再提炼
   • 3.3 分发渠道：从本地到 API
4. 进阶结构：封装脚本与辅助文档
   • 4.1 各目录的职责
   • 4.2 脚本封装的价值
5. 渐进式披露：解决 AI 上下文瓶颈的优雅之道
   • 5.1 核心原理
   • 5.2 选择性加载表
   • 5.3 长文件加 Table of Contents
   • 5.4 主文件三原则：Quick Reference、80/20 分层与契约式引用
   • 5.5 内容拆分决策树：五大原则
6. 工具隔离与安全设计
   • 6.1 allowed-tools 的设计哲学：从功能配置到安全约束
   • 6.2 Skill 权限三问框架
   • 6.3 三层权限体系：能力越强，治理越前置
   • 6.4 生产级 Skill 安全设计清单

1. Skill 出现的背景¶

1.1 AI 编程助手的上下文困境¶

大语言模型（LLM）在代码生成和审查方面表现出色，但有一个根本性的限制——上下文窗口是有限的公共资源。每一条指令、每一份文档、每一段对话历史都在消耗这个窗口。当项目规模增长，团队需要传递给 AI 的规范、流程、模板越来越多时，"把所有东西塞进 CLAUDE.md"这条路很快会走到尽头：

• CLAUDE.md 超过 200 行后，AI 对指令的遵从度开始下降
• 不同任务需要不同的领域知识，但全量加载浪费 token
• 团队成员各自维护 prompt 片段，知识无法沉淀和复用

1.2 从 prompt 到可复用的知识单元¶

Skill 的出现正是为了解决这个矛盾：把可复用的领域知识和工作流程封装成独立的、按需加载的模块。它遵循 Agent Skills 开放标准，不绑定单一平台。

与传统的 prompt engineering 相比，skill 的核心区别在于：

2. Skill 基本介绍¶

2.1 一个 Skill 长什么样¶

最简形态只需一个 SKILL.md 文件：

my-skill/
└── SKILL.md

SKILL.md 由两部分组成：

---
name: my-skill
description: 描述 skill 的用途和触发条件。Claude 通过这段描述决定是否自动加载。
---

# My Skill

这里是 Claude 执行 skill 时遵循的指令。

• YAML frontmatter（--- 之间）：告诉 Claude 什么时候使用这个 skill
• Markdown 正文：告诉 Claude 怎么做

2.2 两种分类维度¶

按内容类型：

按用途领域（来自 Anthropic 官方指南）：

两种分类正交互补：知识型/任务型描述 内容性质，三类领域描述 解决什么问题。

2.3 调用方式¶

• 用户主动调用：在 Claude Code 中输入 /skill-name
• Claude 自动加载：Claude 根据 frontmatter 中的 description 判断当前任务是否匹配
• 参数传递：支持 $ARGUMENTS（全部参数）、$0、$1（位置参数）

2.4 Frontmatter 字段参考¶

必需字段：

可选字段：

安全限制： - description 中禁止 XML 角括号（< >），因为 frontmatter 出现在系统提示中，恶意内容可能注入指令 - Skill 名称不允许包含 claude 或 anthropic（保留前缀） - Skill 文件夹名称必须与 name 一致，使用 kebab-case

3. 部署位置与适用场景¶

Skill 支持四级部署，高优先级覆盖低优先级：

选择建议：

• 安全审查、代码规范 → 企业级部署，确保全员一致
• 个人效率工具（如 tech-doc-writer、google-search） → 个人级
• 项目专属流程（如特定项目的 CI workflow、PR 模板） → 项目级，提交到 Git
• 团队共享的通用工具 → 插件发布

3.1 什么时候不需要 Skill¶

并非所有知识都适合封装为 skill。以下场景应选择其他机制：

判断标准：如果这份知识（1）会被反复使用，（2）内容超过 50 行，（3）不是每次会话都需要——那它适合做成 skill。三个条件不全满足时，优先考虑更轻量的机制。

3.2 创建你的第一个 Skill：先迭代，再提炼¶

以"Go 代码格式化检查"为例，演示从普通对话到可复用 skill 的完整过程。这个过程分为两个阶段：先通过手动迭代得到一份可用的草稿，再用 skill-creator 将草稿打磨为生产级 skill。

第 1 步：在对话中反复解决同一个任务

不要急着写 SKILL.md。先在 Claude Code 的普通对话中直接提需求：

> 帮我检查当前项目有没有格式不规范的 Go 文件，有的话帮我修复

Claude 会执行 gofmt -l .，找到问题文件并修复。但你可能发现它的行为不够理想——比如改了 vendor/ 下的文件、没有优先用 goimports、修复后没有二次验证。

继续在对话中纠正：

> 不要动 vendor 目录。如果有 goimports 优先用它。修完后再跑一遍确认

重复 2-3 次，直到 Claude 的执行流程让你满意。此时你脑中已经有了一套验证过的工作流。

第 2 步：把成功的方法提炼为 SKILL.md

现在再创建 skill——你不是凭空写指令，而是把已经验证过的 prompt 持久化：

mkdir -p ~/.claude/skills/fmt-check

在 ~/.claude/skills/fmt-check/SKILL.md 中写入：

---
name: fmt-check
description: >
  Check and fix Go code formatting issues. Triggers when the user asks
  to format code, check formatting, or fix style issues in Go files.
---

# Format Check

## Workflow

1. Run `gofmt -l .` to list files with formatting issues.
2. If no files found, report "All files properly formatted."
3. If files found, run `gofmt -w <file>` for each file.
4. Run `gofmt -l .` again to verify all issues are fixed.
5. Report which files were modified.

## Rules

- Never modify files outside the current Go module.
- If `goimports` is available, prefer it over `gofmt` (it also handles imports).

这份 SKILL.md 的每一条规则都来自第 1 步的实际纠正——"不动 vendor"变成了 Rules 中的边界约束，"优先用 goimports"变成了工具选择规则，"修完再验证"变成了 Workflow 的第 4 步。

第 3 步：用 skill-creator 打磨

手动写出的 SKILL.md 能用，但存在盲区：

• description 可能无法覆盖所有合理的触发表述（比如用户说"检查一下 go 格式"而非"格式化"）
• 2-3 轮对话纠正能覆盖的边界情况有限
• 没有客观数据证明这个 skill 是否真的比不用 skill 更好

Anthropic 官方的 skill-creator 正是为了解决这些问题。它自动化了手动创建中最难、也最容易被省略的环节：

1. 访谈式查漏——主动追问触发场景、期望输出格式、边界情况和 test case，减少因经验有限导致的遗漏
2. 自动生成 eval 并运行——创建测试场景，同时运行 with-skill 和 without-skill 两组对照，用数据代替猜测
3. Description 优化循环——生成 20 条 should-trigger / should-not-trigger 查询，按 train/test split 运行优化迭代。这是手动创建最难做到、对 skill 能否被正确触发影响最大的环节
4. 可视化反馈——浏览器界面查看每条输出和 benchmark 对比数据，形成闭环

以前面的 fmt-check 为例，直接在 Claude Code 中调用：

> 用 skill-creator 评估并改进 fmt-check skill

skill-creator 可能会发现：description 中缺少"检查 go 格式"这一常见表述导致触发遗漏、多模块 monorepo 是未覆盖的边界情况、"帮我格式化 Python 代码"会错误触发这个 skill。这些问题在手动创建中很难主动发现。

完整的三维评估方法论（触发准确率、任务性能、token 成本效益）和真实案例分析详见第 10 章。

第 4 步：使用并持续迭代

在 Claude Code 中，你现在可以： - 输入 /fmt-check 主动调用 - 或者直接说"帮我检查一下代码格式"，Claude 会根据 description 自动加载这个 skill

使用几次后，你可能会发现新的改进点： - 需要支持 goimports-reviser——把它加到 Rules 中 - 需要在 CI 中也能用——把 skill 目录从 ~/.claude/skills/ 移到项目的 .claude/skills/，提交到 Git - 做了较大改动后，重新跑一轮 skill-creator 评估，确认改动没有引入回归

什么时候手动创建就够了？

• 个人使用、逻辑简单、低风险场景——第 1-2 步足矣
• 团队共享、触发表述多样、边界情况复杂——建议用 skill-creator 完整走一遍。即使你决定手动创建，也建议至少做两件事：跑 2-3 个 test case 的快速 eval（暴露隐患），以及跑一轮 Description 优化（投入小、收益高）。一个触发不准的 skill 等于白写

这就是 skill 的核心创建路径：对话中迭代 → 提炼为 skill → 用 skill-creator 打磨 → 实战中持续改进。完整的 skill 生命周期还包括量化评估（第 10 章）和开发流程集成（第 12 章）：构建 → 评估验证 → 迭代改进 → 融入流程 → 持续监控。后续章节将展开每个环节的最佳实践。

3.3 分发渠道：从本地到 API¶

除了本地四级部署（§3），skill 还支持更广泛的分发方式：

API vs 交互式：日常开发和手动测试用 Claude.ai / Claude Code；生产部署、自动化管线、Agent 系统用 API。Skills API 需要 Code Execution Tool beta 支持。

Skills 遵循 Agent Skills 开放标准，skill 天然具备跨平台可移植性——同一个 skill 无需修改即可在 Claude.ai、Claude Code 和 API 上运行。

4. 进阶结构：封装脚本与辅助文档¶

当 skill 的复杂度超过单文件所能承载的范围时，需要引入更丰富的目录结构。以评分 9.5/10 的 go-ci-workflow skill 为例：

go-ci-workflow/
├── SKILL.md                           # 入口：236 行操作框架
├── agents/
│   └── openai.yaml                    # UI 元数据
├── scripts/
│   ├── discover_ci_needs.sh           # 仓库形态自动发现脚本
│   ├── run_regression.sh              # 回归测试运行器
│   └── tests/
│       ├── COVERAGE.md                # 测试覆盖矩阵
│       ├── test_skill_contract.py     # 44 个合约测试
│       ├── test_golden_scenarios.py   # 17 个黄金场景测试
│       └── golden/                    # 8 个黄金场景 JSON
│           ├── 001_single_module_service.json
│           ├── ...
│           └── 008_service_containers_integration.json
└── references/
    ├── workflow-quality-guide.md       # 16 章节 CI 模式指南
    ├── golden-examples.md             # 4 个完整 workflow YAML
    ├── github-actions-advanced-patterns.md  # 9 章节高级模式
    ├── repository-shapes.md           # 6 种仓库形态建模
    ├── pr-checklist.md                # PR 审查清单
    └── fallback-and-scaffolding.md    # 降级策略

4.1 各目录的职责¶

4.2 脚本封装的价值¶

把确定性逻辑封装为脚本而非 prompt 指令，有三个好处：

1. 节省 token：脚本执行结果比脚本代码本身短得多
2. 确定性：同样的输入永远产出同样的结果，不依赖 LLM 推理
3. 可测试：脚本可以在 CI 中独立测试

脚本有两种典型用法，方向相反但道理相同：

收集输入：discover_ci_needs.sh 扫描仓库后输出结构化 TSV 数据，Claude 基于这个确定性结果做决策，而非自己猜测仓库结构。

生成输出：脚本直接生成最终产物——例如代码库可视化 skill 只需告诉 Claude 一条命令：

python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .

脚本运行后生成 codebase-map.html 并在浏览器中打开。Claude 无需理解任何 HTML/CSS/JS 实现细节，只需知道"运行什么命令"——这是约 10 个 token，而非自己生成 HTML 所需的 2000+ token。这正是渐进式披露的极致形态：把实现细节彻底委托给脚本，Claude 只保留指令层。

5. 渐进式披露：解决 AI 上下文瓶颈的优雅之道¶

5.1 核心原理¶

渐进式披露（Progressive Disclosure）是高质量 skill 最关键的设计模式。它把知识分为三层，按需逐层加载：

┌─────────────────────────────────────────┐
│ L1: 元数据（name + description）         │  ← 始终在上下文中（~50 词）
├─────────────────────────────────────────┤
│ L2: SKILL.md 正文                       │  ← skill 触发时加载（<500 行）
├─────────────────────────────────────────┤
│ L3: references/ + scripts/              │  ← 按需加载（无限制）
└─────────────────────────────────────────┘

关键约束：SKILL.md 正文不超过 500 行。超出的内容必须拆到 references/ 目录。

5.2 选择性加载表¶

高质量 skill 在 SKILL.md 中为每个 reference 文件写明加载条件，而非简单列出文件名：

## Load References Selectively

- `references/workflow-quality-guide.md`
  Baseline job templates and Go/GitHub Actions patterns.
- `references/repository-shapes.md`
  Use for monorepo, multi-module, library decisions.
- `references/github-actions-advanced-patterns.md`
  Use for permissions, fork PR security, service containers.

这样，处理单模块服务时只加载 workflow-quality-guide.md；处理 monorepo 时额外加载 repository-shapes.md——每次对话只加载必要的知识。

5.3 长文件加 Table of Contents¶

超过 100 行的 reference 文件应在顶部添加目录，帮助 Claude 快速定位目标段落：

# Go CI Workflow Quality Guide

## Table of Contents

1. [Job Set](#1-job-set)
2. [Trigger Strategy](#2-trigger-strategy)
...
16. [Validation Checklist](#16-validation-checklist)

5.4 主文件三原则：Quick Reference、80/20 分层与契约式引用¶

前三节描述了知识的三层分载结构（L1/L2/L3）和选择性加载的基本形式。但实践中，一个 SKILL.md 即使控制在 500 行以内，Claude 仍可能需要逐行扫描才能找到所需内容。以下三条协同作用的原则让主文件本身具备导航能力。

原则一：Quick Reference 路由表——入口层¶

在 ## Core Rules 之后放置一张路由表，每行对应一类用户意图，直接指向处理该意图的章节或引用文件：

## Quick Reference

| 当你需要… | 跳转到 |
|---|---|
| 从零生成 README | §Pre-Generation Gates → §Project Type Routing |
| 更新已有 README | §README Update Triggers + 加载 `references/checklist.md` |
| 中文 / 双语输出 | §Chinese Guidelines + 加载 `references/bilingual-guidelines.md` |
| Monorepo 项目 | §Monorepo Rules + 加载 `references/monorepo-rules.md` |
| 检查输出质量 | §README Quality Scorecard |

Quick Reference 的作用是在第一屏内终止扫描：Claude 读完这张表，就能以 O(1) 而非 O(n) 的方式定位所需内容，不必再逐行扫描主文件。

原则二：高频内联，低频外链（80/20 法则）¶

SKILL.md 的内容应按使用频率分层，而非按逻辑完整性堆砌：

判断标准：80% 的请求只需要 20% 的内容。某段内容只在特定场景下才会用到（"当用户要求 CI 集成时"、"当重构现有文档时"），它就属于 L3，应该外链而非内联。

原则三：契约式引用——三要素缺一不可¶

5.2 节展示了选择性加载的基本形式。契约式引用是它的升级版：引用不是一个路径，而是一份合约，让 Claude 清楚地知道何时该加载、加载后能得到什么：

# ❌ 弱引用（Claude 不知道何时该加载）
See `reference/revenue.md` for more details.
# ✅ 契约式引用（Claude 清楚加载条件和预期内容）
## Revenue Analysis 
When the user asks about revenue growth, ARPU, or revenue composition:
→ Load `reference/revenue.md` for calculation formulas and industry benchmarks

契约式引用三要素：

1. 触发条件：什么情况下应该加载（"当用户问到 X 时"、"当检测到 Y 信号时"）
2. 文件路径：去哪里找内容（references/xxx.md）
3. 预期内容：加载后能得到什么（"覆盖 6 类场景的 BAD/GOOD 对照"）

三条原则形成完整的渐进式披露链：Quick Reference 把用户意图路由到正确的章节或引用文件；80/20 法则决定哪些内容留在主文件、哪些移出；契约式引用确保移出的内容在正确时机被精准加载。三者缺一，渐进式披露就会出现断层。

5.5 内容拆分决策树：五大原则¶

前四节回答了"如何加载内容"——本节来解决一个更根本的问题：如何做内容拆分，哪些应该放 SKILL.md、哪些放到引用文件里、哪些放到脚本里？ 请看下面的知识拆分决策树。

决策树背后是五条互补的原则：

核心洞察：SKILL.md 应该是路由器，而不是百科全书。它告诉 Claude "遇到 X 情况，去 Y 文件找答案"，而不是把所有答案都内联在主文件里。

超过 500 行时的重构信号¶

官方建议 SKILL.md 控制在 500 行以内。为什么是 500 行？ - 500 行 ≈ 2000-3000 tokens，是一个 Skill 激活后的合理上下文开销。 - 加上 Claude 自身的系统提示和对话上下文，总 token 数保持在可控范围。 - 超过 500 行意味着你可能把“参考资料”混进了“路由指令”。

当 SKILL.md 超过 500 行，通常是某条原则被违反的结果：

把内容放在正确的层级，是 §5.1–5.4 所描述的加载策略能够精准生效的前提。

6. 工具隔离与安全设计¶

前五章描述了 Skill 是什么、放在哪里、怎么组织内容。有一个问题始终隐藏在背后：当 Skill 的能力越来越强，谁来保证它不越界？

allowed-tools 字段在 §2.4 里只作为一个可选 frontmatter 字段被提及。但它的本质远不止于此——它是把安全约束前置为结构约束的机制，解决的是越权风险，而不只是功能限制。

6.1 allowed-tools 的设计哲学：从功能配置到安全约束¶

allowed-tools 的正确理解方式是：明确"不能做什么"，而不是列举"能做什么"。

一个没有 allowed-tools 的 Skill 默认继承完整的工具集——包括 Write、Edit、Bash 等所有能力。这对简单的个人用 Skill 无妨，但对共享 Skill 或高风险场景，这意味着"执行一个审查 Skill 时也能意外修改文件"。

按 Skill 的典型职责，可以划分四类标准工具集：

Bash(python:*) 和 Bash(npm test:*) 这类精细粒度约束是 allowed-tools 的关键能力——它允许特定工具模式，同时屏蔽其他路径。审计类 Skill 绝不应该拥有 Write 或 Bash，不是因为它"用不到"，而是因为拥有就意味着风险。

与 CLAUDE.md permissions 的分层关系

allowed-tools 是 Skill 级约束，与全局 CLAUDE.md 中的 permissions 形成两层结构：

全局 permissions（settings.json / CLAUDE.md）
    └── 项目级 permissions（项目 CLAUDE.md）
            └── Skill 级 allowed-tools（SKILL.md frontmatter）

Skill 级约束只能收紧，不能放开：如果全局 permissions 已经禁止了 Bash(rm:*)，Skill 里写 allowed-tools: [Bash] 也无法绕过。Skill 级约束是在全局权限范围内的进一步细化，而不是替换。

6.2 Skill 权限三问框架¶

设计一个 Skill 的权限边界，只需回答三个问题：

问题一：这个 Skill 能做什么？（工具边界）

allowed-tools 直接回答这个问题。设计原则：最小化必要权限。审查类 Skill 只需读文件；提交类 Skill 需要 Bash(git:*)，但不需要 Write。

问题二：什么时候能被触发？（触发控制）

这里有两个机制：

• disable-model-invocation: true：阻止 Claude 根据 description 自动加载，要求用户主动用 /skill-name 显式调用。适合有副作用的操作（git commit、文件删除、部署发布）。
• description 的精确度：description 写得过宽，Claude 会在不该触发的场景下自动加载。"帮我格式化代码"和"帮我检查代码格式"是两种不同的意图，description 需要精确区分。

问题三：在什么边界内运行？（运行边界）

Skill 的部署位置决定其影响范围：企业级 Skill 面向全组织，项目级 Skill 只对当前项目生效，个人级 Skill 只影响自己的工作流。高风险 Skill（涉及生产数据、付款、权限变更）应该只部署到有明确授权的层级，而不是默认推给所有人。

以 git-commit Skill 为例，三问的答案是：

6.3 三层权限体系：能力越强，治理越前置¶

Skill 的复杂度不是静止的，它随使用深度逐级演进：

第一级：SOP 阶段

Skill 执行固定步骤，风险极低。allowed-tools 管控一两个工具即可，触发控制用 description 精确度就够。这个阶段的安全风险主要是"做了不该做的文件操作"。

第二级：专家系统阶段

Skill 可以调用多种工具、加载大量 references、基于分析结果做复杂判断。此时需要明确三问的答案：工具集是否最小化？触发条件是否精确？部署层级是否匹配风险？

第三级：组织智能阶段

多个 Skill 协作运行，通过 SubAgent、pipeline 自动编排，触发链路可能跨越多个 Skill。如果没有清晰的权限分层，一个权限宽泛的 Skill 可能成为权限提升的跳板——低权限 Skill A 调用高权限 Skill B，绕过了本应存在的约束。

这就是"能力越强，治理越前置"的含义：不是等出了问题再收权，而是在设计阶段就把约束建进结构里。

6.4 生产级 Skill 安全设计清单¶

在把 Skill 分发给团队或部署到企业级之前，按以下清单逐项检查：

使用说明：前 8 项在 Skill 设计阶段检查，第 9 项在 CI 中自动运行，第 10 项在团队流程中执行。任何一项"高风险"检查未通过，视为阻塞项，发布前必须修复。

更多关于 allowed-tools 误用案例和安全反模式，参见进阶篇 §7.5。