Agent Skills实战：从原理到代码审查技能编写

先给结论：如果你过去一年还在靠“把规则写进 system prompt”来驯服 Agent，那么 2026 年这个阶段，你应该认真补上 Agent Skills 这一课。它不是给 Agent 新增一个“角色设定”，而是把可复用的能力沉淀成文件，让 Agent 在运行时按需加载、按步骤执行。这件事的难度并不高，但它改变的是你组织 Agent 工程的方式。本文会从原理讲到实战，手把手带你写一个真正能用的技能文件，并绕过那些最容易踩的坑。

很多人第一次听说 Agent Skills，第一反应是“这不就是给 Agent 写说明书吗”。这个理解不算错，但严重低估了它的价值。真正重要的变化是：Agent 的能力从“写死在对话上下文里”变成了“按需发现、按需加载”。这就像你不再把全部工作手册打印出来贴在桌上，而是在工作台旁边放一个书架，Agent 接到任务时自己去找对应那一本。本文要解决三个问题：第一，Agent Skills 到底是什么、和 MCP 有什么区别；第二，怎样从零写一个合格的技能文件；第三，怎样验证技能真的生效，而不是看着它加载了却没发挥作用。

1. 这篇文章真正要解决的问题

先回到一个最常见的开发场景。假设你维护着一个 Python 项目，团队要求每次代码提交前做一轮代码审查，审查点包括：函数是否过长、异常是否被吞掉、是否直接操作了数据库连接、日志是否写得够清晰。过去的做法是，你在提给 Agent 的 Prompt 里把这几条规则写一遍，每次都要写；后来你发现 Prompt 越来越长，模型反而记不住重点，甚至会在中间丢掉某条规则。再后来，你把这些规则放到项目里的 AGENTS.md 或者 CLAUDE.md 文档里，让模型每次对话前自动读取。这已经比手写 Prompt 前进了一大步，但还是有问题：文档会变得越来越大，模型注入上下文要消耗大量 token，而且无论这次任务是写测试、修 Bug 还是做 Code Review，所有规则都会被一次性塞进去。

Agent Skills 改变的就是这个环节。你不再把所有规则塞进上下文，而是把“代码审查”这件事做成一个技能目录，目录里有一个 SKILL.md 文件。当 Agent 收到的任务和代码审查相关时，它会先读取这个技能文件，只把这一份指令加载进来，然后按里面的步骤执行。上下文没被无关规则挤占，规则本身也能被精细维护。

所以这篇文章适合谁？首先是正在用 Claude Code、Claude Agent SDK 或类似 Agent 工具的开发者，你已经跑通过基本流程，但觉得 Agent 的表现不够稳定，想找到一种更可控的能力注入方式。其次是刚接触 Agent 开发、想建立一个正确心智模型的新手：与其一开始就去搞复杂的多 Agent 编排，不如先学会把单个 Agent 的技能写好，这是性价比最高的起点。如果你目前只是用 ChatGPT 或 Claude 网页版做问答，本文也有用，因为“技能”这种组织方式正在成为 Agent 生态的标准配置，提前理解它能让你少走很多弯路。

2. Agent Skills 的核心概念与适用场景

2.1 它到底是什么

Agent Skills 可以理解为：一个包含 SKILL.md 主文件和相关附属资源的目录。SKILL.md 采用 Markdown 格式，文件开头有一段 YAML 元信息，写明技能的 name 和 description；正文部分用自然语言和步骤清单描述“这个技能应该怎么用”。当 Agent 认为某个任务和技能的 description 匹配时，就会读取这个目录里的内容，并按照里面的指令执行。

这个机制的关键点有两个。第一，技能是按需加载的，而不是常驻上下文。这直接解决了 Prompt 越来越长、模型注意力被稀释的问题。第二，技能是可以版本化、可复用、可共享的资产。一个写好的技能文件放进 Git 仓库，团队所有人都可以用，也可以像代码一样做 Review 和迭代。

2.2 和 Prompt、MCP 的区别

这是一个最容易混淆的地方。很多人把 Agent Skills 和 MCP 当成同一种东西，实际上它们的定位完全不同，前者是“让 Agent 知道怎么做一件事”，后者是“让 Agent 能连接到某个外部系统”。

用一个场景来理解这个分工：你让 Agent 去“检查订单服务的日志并分析异常”。MCP 负责的是“连接到日志系统、拉取日志、查询数据”；Agent Skills 负责的是“检查日志之前先确认时间范围、分析异常的标准步骤、输出报告应该包含哪几个板块”。MCP 解决连接问题，Skills 解决方法问题。实际项目中两者经常配合使用，但心智上不要混为一谈。

2.3 哪些场景最适合用 Agent Skills

从目前的实践看，最适合技能化的任务有三类。

第一类是流程固定、规则明确的任务，比如代码审查、发布检查、日志分析、SQL 审核。这类任务的特点是“每一步做什么”很清楚，但细节多，人反复执行容易遗漏，非常适合沉淀成技能。

第二类是需要专业知识的任务，比如某个内部框架的安全检查规范、某种业务报表的统计口径。知识本身复杂，把它们写进 Prompt 会让上下文爆炸，做成技能后按需加载是最好的选择。

第三类是需要多次执行的重复性任务，比如生成周报、创建新模块的脚手架、整理接口文档。技能让 Agent 每次都按统一标准执行，不会这次漏一个字段、下次换个格式。

反过来，不适合做成技能的有两类。一是极其简单、一句话就能说清的任务，做成技能属于过度设计；二是需要强实时性、强交互的任务——技能本质上是静态文件，它不能替你调用实时接口，这部分应该交给 MCP 或普通工具函数。

3. Agent Skills 运行环境与前置条件

写技能之前，先确认你的运行环境。目前和 Agent Skills 直接相关的工具主要是 Anthropic 的 Claude Code 和 Claude Agent SDK，同一个生态里的其他 Agent 框架也在快速跟进类似机制。本文的讲解以通用机制为主，具体命令和细节请以你使用的版本为准。

需要准备的环境如下：

• 一个能运行 Claude Code 的环境，通常是 macOS、Linux 或 Windows 下的命令行环境。
• Claude Code 已安装并完成登录，能正常发起 Agent 对话。安装方式一般是 npm 全局安装，也可以用官方脚本，具体以官方文档为准。
• 一个用于测试的代码项目仓库。建议新建一个空的测试项目，不要直接在正式项目里做实验。
• Git 已经初始化，因为技能目录最终要纳入版本管理。

你不需要额外安装复杂的依赖，Agent Skills 本身不是一个软件包，而是一套文件组织约定。这意味着它的学习曲线很平缓：只要你写过 Markdown，就已经具备 50% 的基础了。这也是它比 MCP 更容易上手的原因——MCP 要写服务、配协议、管鉴权，而 Skills 的门槛只是会写文件。

4. Agent Skills 目录结构与编写规则

4.1 一个技能目录长什么样

一个典型的技能目录如下：

code复制my-skill/
├── SKILL.md
├── checklist.md
├── scan.py
└── reference/
    └── style-guide.md

SKILL.md 是唯一必需的入口文件。其余文件都是辅助资源：checklist.md 可以是审查清单，scan.py 是一个辅助脚本，reference/ 目录里可以放参考手册。Agent 读取技能时，会先读 SKILL.md，正文里可以指示它去读取同目录下的其他文件，甚至运行同目录下的脚本。

4.2 SKILL.md 的内部结构

SKILL.md 的核心结构分两块：YAML 元信息和 Markdown 正文。YAML 元信息是最容易出错的地方，因为它的内容直接决定了技能会不会被触发。以 Claude Code 生态的实现为例，元信息至少需要 name 和 description 两个字段，description 是 Agent 判断是否加载该技能的“触发条件”，写得越具体、越贴近真实任务描述，技能被正确触发的概率越高。

正文部分建议按“背景 → 执行步骤 → 输出要求”三段组织。背景说明这个技能解决什么问题、在什么条件下使用；执行步骤给出编号清单，每一步尽量可操作；输出要求说明最终交付物的格式。正文要写步骤、写标准、写边界，而不是写一篇知识科普文。

4.3 编写技能文件的四个核心原则

第一，description 是触发器的灵魂。不要写“用于代码审查”这种泛泛的描述，要写“当用户要求审查 Python 代码、检查代码风格、发现潜在 Bug 或提出改进建议时使用”。关键词覆盖得越全，触发越准。

第二，正文写“怎么做”而不是“是什么”。技能文件不是培训教材，而是操作手册。你要告诉 Agent 先做什么、再做什么、遇到什么情况怎么处理。

第三，控制单次加载的体量。一个技能文件的正文尽量控制在一屏到两屏能读完的体量。如果内容太长，可以拆成多个子文件，在正文里按需引用。

第四，不要在技能文件里写机密信息。技能文件通常放进代码仓库，会被所有有仓库权限的人看到，而且会被 Agent 自动读取。密钥、Token、内部敏感策略都不适合放在这里。

5. 完整实战：从零手写一个 Python 代码审查技能

下面我用一个最常见的例子走完整流程：做一个“Python 代码审查技能”。需求是，当用户要求 Agent 审查 Python 代码时，它应该加载这个技能，按标准步骤检查代码，并输出一份结构化审查报告。

5.1 创建技能目录

先在你的测试项目里建目录。如果你用 Claude Code，技能目录通常放在项目根目录的 .claude/skills/ 下面：

bash复制mkdir -p .claude/skills/python-review/scripts
cd .claude/skills/python-review

如果你的 Agent 工具支持自定义技能目录，路径以你的工具配置为准，但目录内结构是一致的。

5.2 编写 SKILL.md 主文件

在 .claude/skills/python-review/SKILL.md 中写入以下内容：

markdown复制---
name: python-code-review
description: 当用户要求审查 Python 代码、检查代码质量、发现潜在 Bug、
    检查代码风格或提出代码改进建议时，使用此技能。
    不适用于其他语言的代码审查。
---

# Python 代码审查

本技能用于对 Python 代码文件进行结构化审查。目标不是重写代码，
而是发现可执行的风险点，并给出可操作的改进建议。

## 执行步骤

1. 确认审查对象。如果用户没有明确指定文件，询问需要审查的
   具体文件路径或代码片段。
2. 读取目标文件，先了解代码的整体结构，包括函数划分、类设计、
   模块依赖关系。
3. 按以下清单逐项检查：
   - 函数或方法是否过长（建议不超过 50 行，超长应提示拆分）。
   - 是否存在被静默吞掉的异常，只写 `except Exception: pass` 的
     代码需要标记为高风险。
   - 是否直接操作了全局可变状态，函数是否隐含了额外副作用。
   - 是否对每类异常给出了有区分度的处理，而不是统一兜底。
   - 是否有明显的资源泄漏风险，比如文件、网络连接、数据库连接
     未关闭。
   - 是否存在重复代码片段，是否值得抽取公共方法。
   - 是否有明显的可读性问题，比如命名含义模糊、魔法数字未命名。
4. 如果目标目录下有 `checklist.md`，读取并合并其中的检查项。
5. 如果发现文件存在复杂度较高的函数，运行 `scripts/calculate_complexity.py`
   辅助分析，脚本会输出每个函数的圈复杂度估算值。
6. 汇总所有发现项，按严重程度分类输出。

这段指令的要害在于：它把“审查”从模糊要求变成了可执行的编号步骤。当 Agent 加载这个技能时，它会按照这些步骤走，而不是凭印象随便列几条建议。

5.3 添加辅助检查清单

创建 .claude/skills/python-review/checklist.md：

markdown复制# Python 代码审查补充清单

- [ ] 所有函数是否有清晰的 Docstring，公共函数是否说明参数和返回值
- [ ] 是否使用 f-string 代替 % 格式化或字符串拼接
- [ ] 是否直接导入了未被使用的模块
- [ ] 类型注解是否覆盖了主要函数签名（新代码建议强制）
- [ ] 循环内是否避免重复计算不变量
- [ ] 是否存在可变默认参数，如 `def f(items=[]):` 这种写法需标记
- [ ] 日志是否包含关键上下文，是否避免了 `logger.info` 拼大段字符串

5.4 添加复杂度分析脚本

辅助脚本的作用是给 Agent 一个“计算工具”，而不是让它凭感觉判断复杂度。创建 .claude/skills/python-review/scripts/calculate_complexity.py：

python复制#!/usr/bin/env python3
"""估算 Python 文件中函数的圈复杂度（简化版）。

用法：python3 calculate_complexity.py <target_file.py>
输出：每个函数的名称与复杂度估值，格式为 JSON，便于 Agent 读取后整理。
"""
import ast
import json
import sys
from pathlib import Path


def estimate_complexity(node: ast.AST, base: int = 1) -> int:
    """遍历 AST 节点，统计 if/for/while/and/or/except 等分支数量。"""
    complexity = base
    for child in ast.walk(node):
        if isinstance(child, (ast.If, ast.For, ast.While, ast.Try)):
            complexity += 1
        elif isinstance(child, ast.BooleanOp):
            complexity += len(child.values) - 1
        elif isinstance(child, (ast.ExceptHandler, ast.With)):
            complexity += 1
    return complexity


def analyze(file_path: Path) -> dict:
    source = file_path.read_text(encoding="utf-8")
    tree = ast.parse(source)
    results = []
    for node in ast.walk(tree):
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
            results.append({
                "name": node.name,
                "line": node.lineno,
                "complexity": estimate_complexity(node),
            })
    return {"file": str(file_path), "functions": results}


if __name__ == "__main__":
    if len(sys.argv) != 2:
        print(json.dumps({"error": "用法: python3 calculate_complexity.py <file>"}))
        sys.exit(1)
    target = Path(sys.argv[1])
    if not target.exists():
        print(json.dumps({"error": f"文件不存在: {target}"}))
        sys.exit(1)
    print(json.dumps(analyze(target), ensure_ascii=False, indent=2))

这段脚本用 AST 解析目标文件，统计 if、for、while、try、with 和 and/or 等分支数量，作为圈复杂度的简化估算。它的存在让技能不仅会读代码，还能给出一个量化的复杂度指标。Agent 读取 SKILL.md 后会知道，当需要分析复杂度时，去运行这个脚本，并把输出结果转述成报告。

6. 运行技能并验证效果

6.1 准备一个待审查的代码文件

创建 test_demo.py，故意放进几种常见问题：

python复制import os


def process(data):
    try:
        result = []
        for item in data:
            if item > 0:
                result.append(item * 2)
        return result
    except Exception:
        pass


def get_config():
    config = {"debug": True}
    # 魔法数字：超时时间写死
    timeout = 30
    return config, timeout

这个文件有两个函数：process 里 except Exception: pass 是典型的吞异常，get_config 里出现了魔法数字，而且函数名是 get 开头但内部逻辑更像配置读取，命名和职责不匹配。这些足够用来验证技能是否生效。

6.2 在 Claude Code 中触发技能

启动你的 Agent 工具，进入项目目录后输入类似这样的任务：

bash复制使用 python-code-review 技能审查当前目录下的 test_demo.py

如果 Agent 正确加载了技能，它应该先读取 SKILL.md，然后按步骤执行：先看整体结构，再逐项检查清单，最后运行复杂度脚本。你在对话中应该能看到它主动提到“根据 python-code-review 技能的检查清单”，并且输出中会包含异常处理风险、魔法数字问题、复杂度分析结果。

6.3 如何判断技能真的生效

判断标准有四个：

• Agent 是否在你的提示词没有展开详细要求的情况下，依然按固定步骤执行；
• 是否引用了 checklist.md 中的检查项，比如“检查到可变默认参数”“检查到循环内重复计算”；
• 是否运行了辅助脚本并给出了复杂度数值；
• 输出格式是否稳定统一，不再每次审查给出不同结构的报告。

如果 Agent 完全没有提到技能内容，最可能的原因不是它能力不行，而是技能的 description 与实际输入不匹配，或者技能目录放错了位置。这个问题在下一节展开。

7. 常见问题与排查方法

第一次调试技能时，建议把“是否触发”和“是否按步骤执行”分开排查。触发问题的根因几乎都在 description，执行问题的根因几乎都在正文质量。先花十分钟把 description 打磨到“用户看到就会这么描述任务”的程度，再花时间把正文改成可执行的步骤，大部分问题都能在一轮内解决。

8. 最佳实践与工程建议

8.1 description 要像写搜索关键词一样去写

技能触发不是靠模型“理解它的意思”，而是靠 description 和任务文本的匹配。所以 description 里应该用真实用户会说的话来写，覆盖同义表达和常见场景。写完可以自测：准备五条不同的用户输入，看看哪些能触发、哪些没有。没有触发的输入如果本该命中，说明描述还缺关键词。

8.2 SKILL.md 的正文要写步骤，而不是写知识

一个常见的失败模式是：开发者在 SKILL.md 里写了很多“背景知识”，但 Agent 看完还是不知道该怎么做。正确做法是，把知识和步骤分离：知识放 reference/ 子目录，需要时让 Agent 去读；步骤留在 SKILL.md 正文里，作为主流程。这样既控制了单次加载的 token 消耗，也避免了正文冗长。

8.3 技能要纳入版本管理

技能文件和代码一样，需要被 Review、需要回溯历史。团队协作时，把技能目录放在共享仓库里，然后规定修改技能必须走 Merge Request。否则过一段时间，不同成员电脑上的技能版本不一致，Agent 行为也会变得不可复现。

8.4 技能与 MCP 的边界要提前定义

团队里如果同时有技能和 MCP 工具，写 SKILL.md 时要写明边界：什么情况用技能内部的脚本，什么情况调用 MCP。比如“检查日志”这种任务，技能文件里只写检查步骤，具体查询日志的能力留给 MCP 去接。如果技能文件里混入了一堆“调用外部系统的指令”，会让技能变得难以维护，也和 MCP 的职责重叠。

8.5 为技能设计验收清单

每次新建或修改技能，先想清楚怎么证明它有效。可以给每个技能配套一段验收 Prompt 和一份预期输出。比如上面这个 Python 审查技能，就该约定：面对 except Exception: pass 时必报；面对魔法数字时必报；复杂度超过阈值时给出建议。有了这些“断言式”的约定，技能才不会越改越偏。

8.6 从“一个人的技巧”变成“团队的资产”

技能最大的价值在于沉淀。单个开发者写 Prompt 只能改善自己的使用体验，但一个被维护得很好的技能目录，能让团队里每个人接手的 Agent 都具备同样的最佳实践。这也意味着，技能文件的写作标准应该比普通文档更高：结构清晰、步骤明确、边界清楚、不依赖特定人的口头习惯。

9. 总结与后续学习方向

这篇内容把 Agent Skills 从概念到实战完整走了一遍。可以记住三句话：技能是按需加载的能力文件，不再让上下文被无关知识挤占；技能和 MCP 是互补关系，一个管方法、一个管连接；技能的核心成败在于 description 写得好不好、正文是不是可执行的步骤。

下一步的实践建议是，不要一上来就写一个“万能技能”，而是从你自己每周都会重复的某个任务开始。比如每天提交代码前的自检、每周整理发布的 Checklist，把它写成技能文件，放进仓库，用两周时间持续迭代。当你发现 Agent 在这项任务上的表现从“时好时坏”变成“稳定一致”时，你就真正理解了 Agent Skills 的价值所在。

再往后，值得深入的方向有两个：一是研究在团队范围内如何组织多个技能，以及技能之间的依赖关系；二是关注 Agent 生态里 Skill 与 MCP 的协同模式发展，它们的边界已经在快速演化。掌握好这个基础，等下一个新概念出现时，你已经有足够的心智模型去快速吸收它了。