Agent Skills 技能机制详解与实践指南

ObraSuperpowers 是一个较为活跃的社区驱动项目，其定位偏向于工程实践场景，提供的 Skill 多与开发工作流、项目管理和自动化任务相关。该社区维护了相对完善的工具链支持，方便用户对 Skill 进行本地调试和版本管理。

awesome-claude-skills 遵循 GitHub 上经典的 awesome-list 模式，本身并不直接托管 Skill 文件，而是充当策展与索引的角色。维护者按照领域和用途对优质 Skill 进行分类整理，并提供指向源仓库的链接。这种聚合方式降低了开发者的搜索成本，适合在选型阶段快速浏览可用资源。

skillsmp 则采用了更接近传统应用市场的运营模式，提供 Skill 的检索、评分和安装功能。用户可以根据关键词、使用场景或社区评价筛选合适的 Skill，一定程度上弥补了纯 GitHub 生态中缺乏统一发现机制的不足。

Skills 工作原理

Skills 的运行依赖于 Claude 所处的虚拟机环境。与纯文本形式的 Prompt 不同，Claude 在该环境中具备文件系统的访问能力，因此 Skill 可以作为一个目录结构存在，其中包含指令文件、可执行脚本和参考资料。这种组织方式类似于为新成员准备的入职指南——将所需的知识、流程和工具集中放置在一个可导航的文件体系中，由模型在运行时按需读取。

这种基于文件系统的架构带来了一个关键设计优势：渐进式信息披露（Progressive Disclosure）。传统 Prompt 模式下，所有上下文信息必须在对话开始时一次性注入，这会大量消耗有限的上下文窗口。而 Skills 机制允许 Claude 分阶段按需加载信息，仅在实际需要时才读取对应的内容，从而显著提升了上下文的利用效率。

Skill 的内容按照加载时机的不同，划分为三个层级，每个层级承担不同的职责：

Level 1 — Metadata，此层级的内容始终被加载。每个 Skill 在 SKILL.md 文件头部通过 YAML frontmatter 声明元数据，包括名称、描述、触发条件等发现信息。Claude 在会话初始化时会扫描所有可用 Skill 的元数据，以判断当前对话场景是否与某个 Skill 相关。由于仅加载轻量的描述字段，这一阶段对上下文窗口的占用极小。一个典型的元数据声明如下：

---
name: code-review
description: Performs structured code review following team standards
trigger: When user asks for code review or submits a PR
tools: bash, read_file
---

Level 2 — Instructions，当元数据匹配成功后，Claude 会进一步加载 SKILL.md 的主体部分。这部分包含过程性知识，即具体的工作流步骤、最佳实践准则和行为指导。其内容本质上是结构化的 Markdown 文本，描述模型在该场景下'应该如何思考和行动'。这一层级的设计使得 Skill 的核心逻辑与触发条件解耦，便于独立维护和更新。

Level 3 — Resources and Code，这是最细粒度的加载层级，仅在执行过程中按需引入。其包含三类资源：附加的 Markdown 指令文件（如 FORMS.md、REFERENCE.md），用于提供更专业的子流程指导；可执行脚本（如 fill_form.py、validate.py），Claude 通过 bash 工具调用这些脚本来完成确定性操作，避免将计算逻辑交由模型推理从而消耗上下文；以及静态参考资料，包括数据库 Schema、API 文档、模板文件等。

Skills 结构

Skills 遵循开放的 Agent Skills Standard 规范。该标准定义了一套通用的 Skill 描述与组织格式，旨在使不同平台和工具链之间的 Skill 资源能够互相兼容。其核心思想是以文件系统目录作为 Skill 的封装边界，通过约定的文件命名和元数据格式实现自描述能力。遵循该标准编写的 Skill，不仅可以在 Claude Code 中使用，也具备向其他兼容 Agent 框架迁移的潜力。

每个 Skill 的入口文件是 SKILL.md，其结构由两部分组成：头部的 YAML frontmatter 和主体的 Markdown 正文。YAML frontmatter 用于声明元数据，对应前文所述的 Level 1 层级；Markdown 正文则承载具体的指令内容，对应 Level 2 层级。一个最小可用的 SKILL.md 文件结构如下：

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---
# Your Skill Name
## Instructions
[Clear, step-by-step guidance for Claude to follow]
## Examples
[Concrete examples of using this Skill]

YAML frontmatter 中有两个必填字段：name 和 description。name 作为 Skill 的唯一标识符，在加载和引用时起到索引作用；description 则为模型提供语义层面的匹配依据，Claude 根据该字段判断当前任务是否应触发此 Skill。两个字段各自有明确的格式约束：

name 字段的命名约定值得注意。小写字母加连字符的格式（kebab-case）与常见的 npm 包名、Docker 镜像标签等命名规则保持一致，有利于在文件系统和命令行环境中无歧义地引用。禁止使用保留词的规则则确保用户自定义的 Skill 不会与 Anthropic 官方发布的资源产生标识冲突。

Markdown 正文部分通常包含 Instructions 和 Examples 两个核心章节。Instructions 提供清晰的分步指导，描述 Claude 在该 Skill 激活后应执行的具体流程；Examples 给出典型的使用场景和预期输出，帮助模型更准确地理解指令意图。在编写实践中，指令的表述应尽量具体且无歧义，避免使用模糊的修饰语。

当 Skill 涉及较复杂的功能时，单个 SKILL.md 文件可能不足以承载全部内容。此时可以将附加指令、脚本和参考资料组织为完整的目录结构：

pdf/
├── SKILL.md # 主指令文件（触发时加载）
├── FORMS.md # 表单填写指南（按需加载）
├── reference.md # API 参考文档（按需加载）
├── examples.md # 使用示例（按需加载）
└── scripts/
    ├── analyze_form.py # 工具脚本（通过 bash 执行，不注入上下文）
    ├── fill_form.py # 表单填写脚本
    └── validate.py # 校验脚本

在这个目录结构中，SKILL.md 是唯一的必需文件，其余均为可选资源。附加的 Markdown 文件（如 FORMS.md、reference.md）在 SKILL.md 的指令中通过文件路径引用，Claude 在执行过程中按需读取。scripts/ 目录下的脚本不会被注入到上下文窗口中，而是由 Claude 通过 bash 工具直接执行，其输出结果再回传给模型进行后续处理。

Skills 最佳实践

保持精简

上下文窗口是一种共享资源。Skill 的内容与对话历史、系统指令以及其他已加载的 Skill 共同竞争有限的上下文空间。虽然并非每个 token 都会立即产生开销——启动阶段仅预加载所有 Skill 的元数据（name 和 description），SKILL.md 正文仅在 Skill 被触发时才读取，附加文件更是按需加载——但一旦 SKILL.md 被加载，其中的每个 token 都在与对话上下文争夺空间。因此，精简性是 Skill 编写的首要原则。具体而言，应避免在指令中堆砌冗余的背景解释，将重点放在可操作的步骤和明确的约束条件上。

设定合理的自由度

Skill 指令的详细程度应当与任务本身的脆弱性和可变性相匹配。一个实用的类比是将 Claude 想象为一个在路径上探索的机器人。

窄桥场景（低自由度）：任务只有唯一正确的执行路径，偏离即会造成严重后果。此时应提供精确的操作步骤和严格的护栏约束。典型例子是数据库迁移脚本，必须按照严格顺序执行，任何步骤的遗漏或乱序都可能导致数据损坏。

开阔地带场景（高自由度）：多条路径都能通向正确的结果，限制过多反而会降低效率。此时只需给出大致方向，信任模型自行选择最优策略。代码审查就是典型案例，最佳的审查重点取决于具体的代码上下文，过于僵化的检查清单反而会忽略真正关键的问题。

错误地为高自由度任务设定过多约束，会导致 Skill 变得冗长且不灵活；而对低自由度任务放松约束，则可能引发严重的执行错误。在编写前，先判断任务落在这个光谱的哪个位置，是设计合理 Skill 的关键前置步骤。

跨模型测试

Skills 本质上是对底层模型能力的增强层，其实际效果与所使用的模型密切相关。同一份 Skill 指令在不同模型上的表现可能存在显著差异——某些模型对隐含指令的理解更强，而另一些模型则需要更明确的步骤拆解。因此，在正式部署前，应使用所有计划适配的模型分别进行测试，确保 Skill 在各模型上都能稳定工作。

控制文件规模与引用深度

SKILL.md 应当充当'目录'的角色，像入职指南的目录页一样，为 Claude 提供全局概览并指引其在需要时查阅详细资料。在具体的规模控制上，需要遵循以下准则：

• SKILL.md 正文控制在 500 行以内，接近此限制时应将内容拆分到独立文件中
• 所有引用文件应从 SKILL.md 直接链接，保持引用深度为一层
• 超过 100 行的引用文件应在顶部添加目录索引

引用深度的限制源于 Claude 的实际读取行为。当遇到嵌套引用（即引用文件中又引用了其他文件）时，Claude 可能仅使用 head -100 等命令预览部分内容而非完整读取，导致信息缺失。将所有引用保持在一层深度，可以确保 Claude 在需要时能够读取完整的文件内容。对于超长的引用文件，顶部目录的作用在于即使 Claude 仅进行部分预览，也能感知到文件中全部可用信息的范围。

# 推荐：扁平引用结构
SKILL.md → FORMS.md ✅ 一层引用，完整读取
SKILL.md → reference.md ✅ 一层引用，完整读取

# 避免：嵌套引用结构
SKILL.md → FORMS.md → helpers.md ❌ 嵌套引用，可能部分读取

使用工作流拆解复杂任务

当 Skill 涉及多步骤的复杂操作时，应将其拆解为清晰的顺序工作流。每个步骤应明确描述输入、操作和预期产出，避免步骤之间存在模糊的依赖关系。对于特别复杂的工作流，一种有效的策略是在指令中提供可勾选的检查清单，Claude 可以将其复制到回复中并逐项标记完成状态，这既帮助模型维持执行的完整性，也使用户能够直观地追踪进度。

## Deployment Workflow
- [ ] Step 1: Run test suite and confirm all tests pass
- [ ] Step 2: Generate changelog from commit history
- [ ] Step 3: Update version number in package.json
- [ ] Step 4: Build production artifacts
- [ ] Step 5: Run validation script `./scripts/validate.py`
- [ ] Step 6: Deploy to staging and verify

这种检查清单模式在数据库迁移、发布流程、环境配置等对步骤完整性要求较高的场景中尤为适用。

Skills 评估与迭代

优先构建评估体系

一个常见的误区是在动手编写 Skill 之前，先投入大量精力撰写详尽的指令文档。这种做法的风险在于，开发者可能基于主观假设去描述'想象中的问题'，而非解决实际存在的缺陷。更合理的策略是先构建评估体系，再编写 Skill 内容。评估体系的存在确保每一条指令都有明确的验证标准，避免 Skill 陷入'文档膨胀而效果模糊'的状态。

评估驱动开发

评估驱动的 Skill 开发遵循一个从发现问题到验证解决方案的闭环流程，其核心思路与测试驱动开发（TDD）高度相似：先明确'什么是失败'，再有针对性地编写解决方案。

第一步是识别缺陷。在不提供任何 Skill 的情况下，让 Claude 处理一组具有代表性的真实任务，仔细记录其失败的具体表现——是遗漏了关键步骤、使用了错误的工具调用方式，还是缺乏特定领域的上下文知识。这些记录构成了 Skill 开发的需求来源。

第二步是围绕这些缺陷创建至少三个评估场景，每个场景对应一个已观察到的具体失败模式。随后在无 Skill 条件下执行这些场景，记录模型的输出质量作为性能基线。基线的存在使后续的改进具备可量化的对比依据。

在基线确立之后，开始编写 Skill 指令。此阶段的关键原则是最小化——仅编写足以解决已识别缺陷的内容，抵制'预防性文档化'的冲动。每一条新增的指令都应能追溯到某个具体的评估场景。编写完成后，重新执行评估并与基线对比，未达标则继续调整指令，直到所有场景均通过。

这种方法从根本上约束了 Skill 的膨胀趋势。未经评估验证的指令往往是对需求的猜测，它们不仅增加上下文开销，还可能在某些场景下引入意外的干扰。

借助 Claude 迭代开发

Skill 开发中最高效的实践模式涉及两个 Claude 实例的协作。开发者与一个实例（称为 Claude A）合作设计和优化 Skill 的指令内容，然后由另一个独立实例（Claude B）在真实任务中测试这些指令。Claude A 扮演'指令作者'的角色，Claude B 则扮演'指令执行者'的角色。

这种双实例模式之所以有效，是因为 Claude 模型本身对 Agent 指令的编写和解读具有双向理解能力——Claude A 能够预判什么样的表述方式最易于另一个 Agent 实例准确执行，同时能够根据 Claude B 的实际执行偏差快速定位指令中的歧义或遗漏。相比开发者独自反复修改和测试，这种协作方式显著缩短了迭代周期。

Skills 代码执行

Skills 中的脚本承担着确定性计算任务，其执行结果会直接回传给 Claude 用于后续推理。因此，脚本的健壮性直接影响整个 Skill 的可靠性。一个核心设计原则是：脚本应自行处理错误条件，而非将异常抛回给模型。当脚本抛出未处理的异常时，Claude 收到的是一段错误堆栈信息，它需要消耗上下文去分析错误原因并决定下一步操作，这既浪费了上下文空间，也引入了不确定性。

良好的错误处理应当在脚本内部完成闭环——遇到可预见的异常时，提供合理的降级方案或默认行为，并通过标准输出告知 Claude 实际发生了什么。以文件处理为例：

def process_file(path):
    """Process a file, creating it if it doesn't exist."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # 文件不存在时主动创建，而非让调用方处理异常
        print(f"File {path} not found, creating default")
        with open(path, "w") as f:
            f.write("")
        return ""
    except PermissionError:
        # 权限不足时返回默认值，避免流程中断
        print(f"Cannot access {path}, using default")
        return ""

这段代码对 FileNotFoundError 和 PermissionError 两种常见异常分别提供了降级策略。Claude 接收到的是清晰的状态描述（如 "File not found, creating default"）而非 Python 的 traceback 输出，从而可以直接基于该信息继续执行工作流。这种模式应推广到所有 Skill 脚本中：网络请求应处理超时和连接失败，数据解析应处理格式异常，文件操作应处理路径不存在和权限不足等情况。

脚本中的配置参数同样需要审慎对待。John Ousterhout 在其软件设计理论中提出的 'voodoo constants' 问题在 Skill 场景下尤为突出——如果开发者自己都无法解释某个常量的取值依据，Claude 在执行时更无从判断该值是否适用于当前场景。每个配置参数都应附带简明的取值理由：

# HTTP 请求通常在 30 秒内完成
# 较长的超时时间用于兼容慢速网络连接
REQUEST_TIMEOUT = 30

# 3 次重试在可靠性与速度之间取得平衡
# 大多数间歇性故障在第 2 次重试时即可恢复
MAX_RETRIES = 3

对比两种风格的差异可以更直观地理解这一原则：

注释中记录的不仅是'值是什么'，更是'为什么选择这个值'。当 Claude 在不同的执行环境中运行脚本时，这些注释为其提供了评估参数适用性的依据。例如，如果任务涉及已知的高延迟 API，Claude 可以根据注释中'慢速连接'的说明合理判断是否需要调大超时值，而非盲目沿用默认配置。

Skills 实践

目录结构

整个 Skill 的文件组织如下，遵循前文所述的扁平引用原则，所有资源文件均从 SKILL.md 直接引用：

cpp-code-review/
├── SKILL.md # 主指令文件
├── checklist.md # 审查检查清单
├── common-issues.md # 常见问题参考手册
└── scripts/
    ├── check_includes.py # 头文件依赖分析
    └── count_complexity.py # 圈复杂度统计

SKILL.md 编写

SKILL.md 作为入口文件，控制在 500 行以内，聚焦于工作流的整体编排：

---
name: cpp-code-review
description: >
  Performs structured C/C++ code review focusing on memory safety,
  coding standards, and performance.
  Trigger when asked to review C or C++ source files, pull requests,
  or code changes.
---
# C/C++ Code Review

## Instructions
When asked to review C/C++ code, follow these steps in order.
Copy the checklist from `checklist.md` into your response and check off items as you complete them.

### Step 1: Static Analysis
Run the include dependency check and complexity analysis:
```bash
python3 scripts/check_includes.py <target_directory>
python3 scripts/count_complexity.py <target_files>

Report any findings before proceeding.

Step 2: Memory Safety Review

Examine the code for memory-related issues:

• Unmatched malloc/free or new/delete pairs
• Buffer overflows from unchecked array indexing or strcpy
• Use-after-free and dangling pointer risks
• Missing null checks after allocation Refer to common-issues.md Section 1 for detailed patterns.

Step 3: Coding Standards Check

Adherence to project conventions:

• Naming consistency (variables, functions, types)
• Header guard correctness (#pragma once or #ifndef pattern)
• Const correctness for function parameters and member functions

Step 4: Performance Considerations

Identify potential performance issues:

• Unnecessary copies in loops (prefer references or std::move)
• Repeated allocations that could be hoisted
• Algorithm complexity mismatches for data scale

Step 5: Summary

Provide a severity-ranked list of all findings. Each finding must include: file path, line number, severity (critical/warning/info), and a concrete fix suggestion.

References

• checklist.md — Copy into response and track progress
• common-issues.md — Detailed patterns for common C/C++ defects

### 检查清单

checklist.md 提供可复制的工作流追踪模板，Claude 在审查过程中逐项标记：

```markdown
# Code Review Checklist
- [ ] Static analysis scripts executed
- [ ] Include dependencies verified (no circular includes)
- [ ] Cyclomatic complexity within threshold (≤15 per function)
- [ ] Memory allocation/deallocation paired
- [ ] Buffer access bounds checked
- [ ] Null pointer checks present after allocation
- [ ] Naming conventions consistent
- [ ] Header guards present and correct
- [ ] Const correctness verified
- [ ] Unnecessary copies identified
- [ ] Algorithm complexity appropriate
- [ ] Summary with severity ranking produced

辅助脚本

辅助脚本遵循'自行处理错误'和'自文档化常量'的原则。以圈复杂度统计脚本为例：

all_findings = []
for arg in sys.argv[1:]:
    path = Path(arg)
    if path.is_file():
        all_findings.extend(analyze_file(path))
    elif path.is_dir():
        for ext in ('*.c', '*.cpp', '*.cc', '*.h', '*.hpp'):
            for f in path.rglob(ext):
                all_findings.extend(analyze_file(f))
    else:
        print(f"SKIP: {arg} is not a valid file or directory")

if not all_findings:
    print("OK: All functions are within complexity threshold "
          f"({COMPLEXITY_THRESHOLD})")
else:
    print(f"FOUND: {len(all_findings)} function(s) exceed "
          f"complexity threshold ({COMPLEXITY_THRESHOLD}):\n")
    for f in sorted(all_findings, key=lambda x: -x['complexity']):
        print(f" {f['file']}:{f['line']} — "
              f"{f['function']}() complexity={f['complexity']}")

if __name__ == '__main__':
    main()

该脚本的设计体现了几个关键实践：COMPLEXITY_THRESHOLD 和 BRANCH_KEYWORDS 两个常量均附带了取值依据的注释；FileNotFoundError 和 UnicodeDecodeError 在函数内部被捕获并输出 SKIP 标记，不会导致脚本崩溃；输出格式对 Claude 友好，以 OK 或 FOUND 开头明确传递分析结论，后续的条目按严重程度降序排列，便于模型优先处理高复杂度函数。

使用效果

当用户在 Claude Code 中发出类似 "review the src/ directory for C++ issues" 的指令时，Claude 根据 description 字段匹配到该 Skill，加载 SKILL.md 后按照工作流依次执行：先运行辅助脚本获取静态分析数据，再结合代码内容逐项完成检查清单，最终输出按严重等级排序的审查报告。整个过程中，脚本负责确定性的度量计算，Claude 负责需要语义理解的代码分析，两者各自发挥所长。