Agent Skills 详解：从触发机制到生产级实践

Level 2 — Instructions：当元数据匹配上，Claude 继续加载 SKILL.md 的正文本体。这是过程性知识，包括工作流步骤、最佳实践和行为指导。用 Markdown 书写，描述模型这时该怎么思考、怎么做。

Level 3 — Resources and Code：执行中按需读取，包括附加的 Markdown 文件（更具体的子流程指南）、可执行脚本（像 fill_form.py，Claude 通过 bash 调用来完成确定性任务，避免浪费上下文推理）和静态参考（数据库 schema、API 文档等）。

Skills 的文件结构

Skills 遵循 Agent Skills Standard 开放规范，以目录为封装边界，通过标准化命名和元数据实现自描述。入口文件永远是 SKILL.md，结构分两部分：YAML frontmatter 和 Markdown 正文。

一个最小可用的 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 里 name 和 description 是必填的。name 作为唯一标识，限制小写字母、数字和连字符，最长 64 字符，不能用保留词 anthropic 或 claude。这种命名约定（kebab-case）和 npm 包名类似，避免文件系统引用的歧义。description 用于语义匹配，最长 1024 字符，也不能有 XML 标签。

正文通常包含 Instructions（分步指导）和 Examples（使用场景和预期输出）。指令要具体无歧义。如果功能复杂，可以扩展成目录：

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

SKILL.md 是唯一必需的文件。其他资源通过 SKILL.md 内的路径引用，按需读取。scripts/ 下的脚本不注入上下文，而是用 bash 工具执行，结果回传模型。

编写 Skills 的最佳实践

精简再精简

上下文窗口是共享资源。虽然启动时只预加载元数据，SKILL.md 正文按需读取，但一旦加载，每个 token 都在挤占对话空间。所以指令要精悍，去掉冗余的背景解释，只留可操作的步骤和明确约束。

控制自由度

指令的详细程度取决于任务的容错性。可以想象模型是一个在路径上探索的机器人：

• 窄桥场景（低自由度）：只有一条正确路径，偏离即出错。此时应给出精确步骤和严格护栏。例如数据库迁移脚本，顺序错一步就可能数据损坏。
• 开阔地带场景（高自由度）：多条路径都能达成目标，限制过多反而碍事。只需指明大方向，让模型自己选最优解。像代码审查，重点取决于具体上下文，僵化的检查清单反而可能漏掉真问题。

写 Skill 前先判断任务属于哪一类，这决定了指令的松紧程度。

跨模型测试

同一份 Skill 在不同模型上表现可能差异很大。有些模型能理解隐含指令，有些需要更明确拆分步骤。部署前用目标模型都跑一遍，确保稳定。

控制文件规模和引用深度

SKILL.md 扮演目录角色，像入职指南的索引页，提供全局概览并指引查阅细节。几个硬指标：

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

为什么限制一层引用？因为 Claude 遇到嵌套引用时（A 引用 B，B 又引用 C），可能只用 head -100 等命令预览部分内容，不会完整读取，导致信息缺漏。扁平引用确保需要时能读到完整文件。大文件顶部的目录也能让模型用预览命令时感知全部内容范围。

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

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

用工作流拆解复杂任务

复杂操作要拆成清晰的顺序步骤，每步说明输入、操作和产出，避免模糊依赖。另一种有效方式是提供可勾选的检查清单，模型可以将它复制到回复里逐项勾选。这对维持执行完整性和进度可视化都很管用。

## 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 内容。这样每条指令都有验证标准，避免文档膨胀却效果模糊。

评估驱动的开发流程

这和 TDD 思路类似：先明确什么是失败，再有针对性地解决。

1. 识别缺陷：不给任何 Skill，让 Claude 处理一组代表性任务，记录失败表现——遗漏步骤、工具调用方式错误、缺乏上下文等。
2. 创建评估场景：围绕每种失败模式至少构建三个评估场景，在无 Skill 条件下执行，记录基线质量。
3. 编写 Skill 指令：只写能解决已识别缺陷的最少内容，抵制'预防性文档化'。每条指令都要对应一个评估场景。完成后重新跑评估，与基线对比，未通过则调整。
4. 迭代通过：直到所有场景通过。

这种方式从根源上抑制了 Skill 膨胀。未经评估验证的指令很多是对需求的猜测，既占空间又可能引入意外干扰。

双 Claude 实例协作

最有效的开发模式是让两个 Claude 实例配合：一个（Claude A）和你一起设计优化 Skill 指令，另一个独立实例（Claude B）用真实任务测试这些指令。Claude A 扮演指令作者，Claude B 是执行者。Claude 对 Agent 指令的编写和解读具有双向理解，能预判怎样的表述最容易被执行实例准确理解，也能根据执行偏差快速定位指令中的歧义。这比独自反复修改测试高效得多。

Skills 中的脚本执行

Skills 里的脚本承担确定性计算，结果回传模型推理。所以脚本健壮性直接影响整个 Skill 的可靠性。一个核心原则：脚本应自己处理错误，别把异常抛给模型。未处理的异常会导致 Claude 收到一堆错误堆栈，它得消耗 token 去分析原因，这既浪费又增加不确定性。

以文件处理为例，良好的错误处理会在内部闭环，遇到可预见的异常提供降级方案，并通过标准输出告知 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，可以继续流程。同样道理，网络请求要处理超时和连接失败，数据解析处理格式异常，文件操作处理路径不存在和权限不足。

脚本中的配置常量也要避免'巫毒常数'（voodoo constants）。如果开发者自己都说不清某个常量的取值依据，Claude 在执行时更无法判断适用性。每个关键参数都应附带简明的取值理由：

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

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

两种风格的对比：

注释不但记录'是什么'，更说明'为什么选这个值'。当 Claude 在不同环境运行脚本时，这些注释可以帮助判断参数是否适用，例如遇到高延迟 API 时，根据注释可能会合理调大超时，而非盲目使用默认值。

一个 C++ 代码审查 Skill 实例

下面以一个实战的 cpp-code-review Skill 为例，展示完整的组织方式。

目录结构

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，不会让脚本崩溃；输出以 OK 或 FOUND 开头，结果按严重程度降序排列，便于模型优先处理复杂函数。

使用效果

当用户发出类似 'review the src/ directory for C++ issues' 的指令时，Claude 匹配到该 Skill，加载 SKILL.md，按工作流依次执行：先跑脚本做静态分析，再结合代码内容逐项检查清单，最后输出按严重等级排序的审查报告。脚本负责确定性度量，Claude 负责语义分析，各司其职。