1. 概述：什么是 Claude Skills？
在构建 AI Agent 的过程中，我们常面临一个痛点：LLM 虽然具备强大的通用推理能力，但在处理特定领域任务时，往往缺乏上下文稳定性和流程规范性。
Claude Skills 应运而生。它是一种轻量级、开放的标准格式，旨在为 Agent 提供可插拔的专用知识、可复用的工作流以及可执行的工具能力。
从工程视角来看：
- 非模型微调：它不需要训练模型。
- 非临时 Prompt：它不是一次性的对话指令。
- 定义：Skill 是将人类经验、SOP（标准作业程序）和工具调用封装成结构化文件包的工程化方案，使 Agent 能够以确定性的方式交付任务。
2. 核心价值：为什么我们需要工程化的 Skills？
传统的 Prompt Engineering 难以满足企业级应用对稳定性与协作的需求。Skills 通过“代码化”的方式解决了以下问题：
2.1 上下文治理与确定性
- 现状：Agent 容易产生幻觉，缺乏对组织流程的认知。
- Skill 方案：将隐性的 SOP 显性化。通过预定义的步骤，强制 Agent 在特定任务中遵循规范，降低熵增。
2.2 可复用性与协作 (Prompt vs. Skill)
| 特性 | Prompt (临时指令) | Skill (工程封装) |
| 复用性 | 低 (Copy-Paste) | 高 (模块化) |
| 版本管理 | 困难 | Git Friendly (纯文本) |
| 审计能力 | 差 | 强 (Code Review) |
| 运行时 | 依赖当前 Session | 环境无关，可复现 |
2.3 “一次构建，随处运行”
Skill 本质上是文件系统中的资源。这意味着它可以像代码库一样被管理：
-
支持语义化版本控制 (SemVer)。
-
跨 Agent、跨平台复用（不绑定特定厂商）。
-
便于团队内部沉淀领域知识库。
3. 能力边界：Skill 能做什么？
Skill 的功能主要覆盖四个象限：
- 领域知识注入 (Domain Expertise) ：封装法律条款、数据分析规范、业务审批流。
- 能力扩展 (Capability Extension) ：集成 MCP Server、自动化脚本执行、项目脚手架生成。
- 工作流固化 (Workflow Standardization) ：将复杂的多步骤任务（如 Code Review）标准化，减少人为差异。
- 生态复用 (Ecosystem) ：构建公共 Skill 库，供多个 Agent 实例共享。
4. 架构规范：Skill 的物理结构
Skill 遵循“约定优于配置”的原则，采用目录式结构。
4.1 目录树示例
my-awesome-skill/
├── SKILL.md # [Core] 核心清单文件：定义元数据与指令
├── scripts/ # [Optional] 可执行代码 (Python/Bash/JS)
├── references/ # [Optional] 长文本知识库、详细文档
└── assets/ # [Optional] 静态资源、模板文件
4.2 核心规范：SKILL.md
这是 Skill 的入口文件，必须包含 YAML Frontmatter 和 Markdown Instructions。
A. YAML Frontmatter (元数据层)
这是 Agent 决定“是否调用此 Skill”的关键依据。
---
name: frontend-code-review # 必须匹配目录名，仅限小写字母、数字、连字符
description: Review frontend code for performance and React best practices. Use when reviewing PRs.
metadata:
version: "1.0.0"
---
工程最佳实践：
description 字段至关重要。它不仅要描述“是什么”，还要描述“何时用”（Trigger Condition）。Agent 的路由机制依赖于此字段的语义匹配。
B. Markdown Instructions (逻辑层)
建议采用结构化的伪代码或 SOP 格式编写：
## When to use
(定义触发场景，辅助 Agent 决策)
## Steps
1. Step 1 logic...
2. Step 2 logic...
## Inputs
(定义参数)
## Outputs
(定义交付物格式)
## Edge Cases
(异常处理逻辑)
5. 运行时机制 (Runtime Lifecycle)
为了优化 Token 消耗，Agent 对 Skill 的加载采用了 渐进式披露 (Progressive Disclosure) 策略。
- Discovery (服务发现) ：
- 扫描指定路径，识别所有包含
SKILL.md的目录。
- 扫描指定路径，识别所有包含
- Metadata Loading (索引构建) ：
- 仅读取 YAML Frontmatter 中的
name和description。 - 此阶段 Token 占用极低。
- 仅读取 YAML Frontmatter 中的
- Injection (上下文注入) ：
- 将 Skill 摘要列表注入 System Prompt。
- Activation (按需激活) ：
- 当用户 Intent 命中某 Skill 的 description 时，Agent 读取完整的
SKILL.md内容。
- 当用户 Intent 命中某 Skill 的 description 时，Agent 读取完整的
- Execution (执行) ：
- Agent 根据 Markdown 指令执行任务，并按需加载
scripts/或references/中的内容。
- Agent 根据 Markdown 指令执行任务，并按需加载
6. 集成模式
根据宿主环境的不同，Skill 主要有两种集成方式：
- Native Mode (基于文件系统) ：
- 适用于 Claude Code, Cursor 等具备本地 Shell 访问权限的 Agent。
- 能力最强，支持直接
cat文件、执行python/bash脚本。
- Tool Mode (基于 API) ：
- 适用于云端或沙箱环境。
- Skill 被封装为 Tool/Function Call，通过 API 触发，安全性更高但灵活性受限。
7. 安全与最佳实践
由于 Skill 可能包含可执行代码 (scripts/)，在工程落地时需注意：
- 沙箱隔离：脚本应在受限环境（如 Docker 容器）中运行。
- Human-in-the-loop：对于高风险操作（删除文件、部署服务），必须要求用户确认。
- Context Control：保持 SKILL.md 精简（建议 < 500 行）。长文档应放入 references/ 目录，通过文件名引用，避免污染上下文窗口。
8. 示例：最小可行性 Skill
以下是一个生产环境可用的 Frontend Code Review Skill 示例：
File: frontend-code-review/SKILL.md
---
name: frontend-code-review
description: Review frontend code for readability, performance, and common bugs. Use when reviewing pull requests or frontend changes.
metadata:
author: engineering-team
version: "0.1.0"
---
# Frontend Code Review SOP
## When to use
Use this skill when the user asks to review a Pull Request or specific frontend source files (React/Vue/TS).
## Steps
1. **Static Analysis**: Check specifically for:
- Hardcoded strings (i18n violation)
- `console.log` leftovers
- Complex `useEffect` dependencies
2. **Performance Check**: Identify potential re-renders or large bundle imports.
3. **Refactoring**: Suggest clearer naming for variables/functions if ambiguous.
## Output Format
Return the review in a structured Markdown table with columns: [File], [Line], [Severity], [Suggestion].
总结
Skills 是 AI Agent 从“聊天机器人”向“数字员工”进化的关键基础设施。通过文件 + 规范的形式，它实现了能力的解耦与工程化，让 Agent 不再是临场发挥的演员，而是严格遵循手册的工程师。
