Claude Code(六)AgentSkills：构建可靠的 AI 技能系统

在上一章中，我介绍了由用户主动触发的 Slash Commands（斜杠命令）。但在更高级的自动化场景中，我们需要 AI 能够根据上下文自动判断何时介入并提供专业能力。

这就是 Agent Skills（技能） 的核心价值。

随着 2025 年底 Anthropic 正式将 Agent Skills 发布为开放标准 (agentskills.io)，这套机制已不仅仅是 Claude 的独有功能，正逐渐成为 Cursor、OpenCode 等 AI 编程工具通用的扩展机制。

本文将基于行业标准与实战经验，深入探讨如何构建可靠的 Agent Skills。

Background / Problem

为什么我们需要 Agent Skills？

在使用通用 LLM 进行软件开发时，我经常遇到三个痛点：

1. 领域知识缺失：AI 不知道团队特定的代码规范、架构模式或数据库设计。
2. 上下文过载：如果把所有规范都塞进 System Prompt，Token 消耗巨大且容易造成 AI 注意力分散。
3. 执行不可靠：AI 生成的复杂操作指令容易出错，缺乏自我验证机制。

Agent Skills 通过模块化设计解决了这些问题。它允许我们定义特定的能力包，AI 只有在识别到相关意图时才会加载，并能严格遵循预定义的工具链和验证逻辑。

Agent Skills 正在像 LSP (Language Server Protocol) 一样标准化。掌握这套定义方法，意味着构建的技能包未来可以在不同的 AI 宿主环境中通用。

---

Core Principles

核心原理与设计哲学

技能生态位：Prompt vs Skill vs MCP

在构建 AI 辅助系统时，很多开发者容易混淆 Skill 与 Prompt 或 MCP 工具的区别。我们可以用一个形象的比喻来厘清三者的生态位：

概念	比喻	定义与作用
Prompt	口令	一次性的、临时的交互指令。解决“当下做什么”。
Agent Skill	大脑/内功	“怎么做”的知识与流程。它包含最佳实践、规范文档、检查清单。它运行在 AI 的上下文中，指导 AI 如何思考和规划。
MCP	双手/工具	“用什么做”的能力。它负责连接外部世界（读数据库、操作 Git、调 API）。Skills 经常会调用 MCP 工具来执行具体操作。

协同工作流：

flowchart LR
    User(["User Prompt"]) -->|Trigger| Claude{"Intent Analysis"}
    Claude -->|Load| Skill["Agent Skill<br/>(Protocol & Knowledge)"]
    Skill -->|Execute| MCP["MCP Tools<br/>(Git/FS/API)"]
    MCP -->|Result| Claude
    Claude -->|Response| User

用户发出指令 (Prompt) -> AI 激活内功 (Skill) 规划路径 -> 驱动双手 (MCP) 完成任务。

Model-Invoked vs. User-Invoked

与 Slash Command 不同，Skill 是 Model-Invoked（模型调用） 的。

• Slash Command: 用户输入 /fix -> 触发命令。显式、可控。
• Agent Skill: 用户输入 “帮我重构这个模块” -> Claude 分析意图 -> 检索 Skill 库 -> 发现匹配的 Refactor Skill -> 自动挂载并执行。

这种机制要求 Skill 的描述（Description）必须精准，采用第三人称视角编写（如 “当用户请求重构代码时使用…“），以便语义检索引擎能正确匹配。

渐进式披露 (Progressive Disclosure)

这是 Skill 设计的核心模式。Claude 的上下文窗口是宝贵资源。

flowchart TD
    subgraph Context[Context Window]
        L1[L1: SKILL.md Index]
    end
    
    subgraph Storage[File System]
        L2[L2: Knowledge Docs]
        L3[L3: Execution Scripts]
    end

    User[User Query] -->|Match| L1
    L1 -.->|Lazy Load| L2
    L1 -.->|Execute| L3
    
    style L1 fill:#f9f,stroke:#333
    style L2 fill:#bbf,stroke:#333
    style L3 fill:#bfb,stroke:#333

• 错误做法：在 SKILL.md 中写下几千行的详细规范。一旦加载，这些 Token 会一直占据上下文。
• 最佳实践：
  1. L1 索引层 (SKILL.md)：只包含元数据和导航目录。Token 占用极低。
  2. L2 知识层 (resources/*.md)：按领域拆分的详细文档（补充文档）。
  3. L3 执行层 (scripts/*.py)：具体的执行脚本。

AI 就像查字典一样，先看目录，再按需读取特定章节。这种架构实现了按需加载和释放，有效降低了 Token 消耗和幻觉概率。

---

Deep Analysis

技能系统的解剖学

一个生产级的 Skill 结构通常如下（参考我的后端开发规范技能）：

backend-dev-guidelines/
├── SKILL.md                  # 入口与元数据
├── resources/                # [L2] 按需加载的知识库
│   ├── architecture.md       # 架构概览
│   ├── database-patterns.md  # 数据库设计模式
│   └── error-handling.md     # 错误处理规范
└── scripts/                  # [L3] 确定性执行脚本
    ├── validate_schema.py
    └── generate_scaffold.py

SKILL.md：关键的入口

SKILL.md 的 YAML Frontmatter 中的 description 决定了技能的可见性。

---
name: backend-guidelines
description: 当用户涉及后端架构设计、数据库迁移或 API 开发任务时激活。提供架构模式和代码规范指导。
allowed-tools: [Read, Grep, Bash]  # 权限沙箱
---

# Backend Development Guidelines

## 知识索引
- **架构设计**：查看 [resources/architecture.md]
- **数据库规范**：查看 [resources/database-patterns.md]
- **错误处理**：查看 [resources/error-handling.md]

## 常用工具
- 验证 Schema：运行 `python scripts/validate_schema.py`

注意 allowed-tools 字段。对于只读性质的技能（如代码审查），我会限制它只能使用 Read 和 Grep，通过权限沙箱防止 AI 意外修改代码。

资源文件的按需加载

当 Claude 决定查阅数据库规范时，它会执行 Read resources/database-patterns.md。这个动作是动态的。如果用户只问了 API 接口，Claude 就永远不会去读数据库规范，从而保持上下文纯净。

---

Practical Implementation

实战：构建”确定性”的代码审查技能

单纯让 AI “Review 代码” 往往得到泛泛而谈的建议。为了保证质量，我构建了一个基于 “计划-验证-执行” (Plan-Verify-Execute) 闭环的 Review Skill。

步骤 1：定义技能结构

mkdir -p .claude/skills/code-reviewer
touch .claude/skills/code-reviewer/SKILL.md
mkdir .claude/skills/code-reviewer/scripts

步骤 2：编写脚本 (scripts/check_style.sh)

我不仅依赖 AI 的分析，更依赖脚本的确定性。

#!/bin/bash
# 检查是否存在 console.log 或 TODO
grep -r "console.log" $1 && echo "Error: Found console.log"
grep -r "TODO" $1 && echo "Warning: Found TODOs"
# 运行项目的 linter
npm run lint --silent

步骤 3：编写 SKILL.md

将脚本集成到 AI 的工作流中。为了保证执行的严谨性，可以设计如下的状态流转：

stateDiagram-v2
    [*] --> StaticAnalysis
    StaticAnalysis --> LogicReview : Pass
    StaticAnalysis --> ReportError : Fail
    LogicReview --> GenerateReport
    ReportError --> GenerateReport
    GenerateReport --> [*]

---
name: strict-code-reviewer
description: 在用户请求审查代码或提交 PR 前使用。执行严格的代码质量检查。
---

# Code Review Protocol

## 工作流 (Workflow)

请严格遵循以下步骤进行审查：

1.  **静态分析 (Static Analysis)**
    运行验证脚本获取客观数据：
    ```bash
    ./scripts/check_style.sh src/
    ```

2.  **逻辑审查 (Reasoning)**
    在通过静态分析后，重点关注脚本无法检测的逻辑问题：
    - 变量命名是否具有语义？
    - 函数是否过于复杂（超过 50 行）？
    - 错误处理是否完善？

3.  **生成报告**
    基于上述两步，输出 Markdown 格式的审查报告。如果脚本报错，**必须**在报告首部用红色标记。

高级技巧：本地知识库集成

在我的 backend-dev-guidelines 实践中，我发现将团队的 Wiki 导出为 Markdown 并放入 resources/ 目录极其有效。

例如，当 AI 需要写一个新的 API Controller 时：

1. 自动激活 backend-guidelines 技能。
2. 读取 resources/routing-and-controllers.md 了解 URL 命名规范。
3. 读取 resources/validation-patterns.md 了解参数校验写法。
4. 生成符合团队风格的高质量代码。

这比在 Prompt 中反复强调 “请使用 RESTful 风格” 更可靠。

---

Advanced Topics

最佳实践与避坑指南

脚本优先 (Scripts over Reasoning)

原则：凡是能用代码解决的，绝不让 AI “思考”。

Bad: “请检查 JSON 是否有效。” (AI 可能看走眼，导致幻觉)

Good: “运行 python -m json.tool file.json 验证。” (更加可靠)

“Claude A / Claude B” 迭代法

开发复杂 Skill 时，我通常采用双模型迭代：

• Claude A (Architect)：负责编写 Skill 定义和脚本。
• Claude B (Tester)：加载新 Skill，在真实场景中模拟用户操作。
• 反馈循环：观察 Claude B 的失败路径（例如找不到文件、误解指令），将 Log 反馈给 Claude A 进行修正。

避免深层嵌套

Claude 在读取文件时，如果发现嵌套引用（文件 A 引用文件 B，文件 B 引用文件 C），可能会因为懒加载策略而导致上下文丢失。 建议：保持扁平化结构。所有核心引用最好在 SKILL.md 或一级子目录中直接可达。

路径规范

始终使用正斜杠 / (Unix Style) 编写路径，即使在 Windows 上也是如此。这能保证跨平台兼容性，避免 AI 混淆转义字符。

总结

Agent Skills 是 Claude Code 从对话工具发展为专业助手的关键，也代表了 AI 开发工具标准化的发展方向。通过渐进式披露架构，我们解决了上下文限制；通过Skill + MCP 的组合，我们实现了思考与行动的有效协同。

当我们将团队的知识显性化为标准化的 Skills，AI 就不再是临时帮手，而是一个熟悉团队规范、可复用的协作成员。

---

下一篇预告：Claude Code(七)Subagents：构建多智能体协作系统