基础篇

目录¶

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

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 基于这个确定性输出做决策，而非自己猜测仓库结构。

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)