【Agent工坊】SKILL.md 完全实战指南：一套技能文件，驾驭所有AI编程Agent

490,000+ 技能生态、Claude Code / Codex / Gemini CLI / Cursor 全兼容——写好一次，到处运行。

为什么你需要关心 SKILL.md

2026 年，AI 编程 Agent 的战场已经尘埃落定。Claude Code、OpenAI Codex CLI、Gemini CLI、GitHub Copilot、Cursor、Windsurf——六大主力工具各有千秋，但它们共享一个关键能力：SKILL.md 技能文件。

这意味着什么？你花一个小时写好一个技能文件，它能在所有这些工具里运行。不是"迁移"，不是"适配"，是直接复用。

但问题来了：大多数开发者写的 SKILL.md 根本不会被 Agent 触发。要么 description 太模糊，要么内容太啰嗦把上下文窗口撑爆，要么指令含糊到 Agent 直接跳过关键步骤。

这篇文章，我从 Anthropic 官方最佳实践 + 社区 490K+ 技能库的实战经验出发，带你从零到一构建一套真正可用的 Agent 技能体系。

SKILL.md 是什么

一句话：SKILL.md 是 AI Agent 的"专项操作手册"。

它不是配置文件，不是 Prompt 模板，更不是给人类看的 README。它是一个包含 YAML 元数据 + 操作指令的 Markdown 文件，Agent 在需要时自动加载并执行。

skill-name/

├── SKILL.md # 必选：元数据 + 核心指令（<500行）

├── scripts/ # 可执行脚本（Python/Bash）

├── references/ # 补充上下文（Schema、速查表）

└── assets/ # 模板或静态文件

关键设计原则：渐进式加载。Agent 启动时只读取所有技能的 name 和 description（元数据）。只有当你的 description 匹配当前任务时，Agent 才加载 SKILL.md 正文。references/ 和 scripts/ 目录下的文件，只在实际被引用时才读取。

六大工具的技能路径速查表

技能文件跨工具兼容，但存放位置因工具而异：

工具	全局技能路径	项目技能路径
Claude Code	`~/.claude/skills/`	`.claude/skills/`
Codex CLI	`~/.codex/skills/`	`.codex/skills/`
Gemini CLI	`~/.gemini/skills/`	`.gemini/skills/`
OpenClaw	`~/.openclaw/skills/`	`.openclaw/skills/`
Cursor	通过 `.cursor/rules/`	同上
Copilot	通过 VS Code 插件	同上

一人公司实战技巧：把技能文件放在项目根目录的 .claude/skills/ 下，然后用符号链接同步到其他工具的路径：

# 以 Claude Code 为主仓库，同步到其他工具

mkdir -p .claude/skills/

ln -s $(pwd)/.claude/skills .codex/skills

ln -s $(pwd)/.claude/skills .gemini/skills

这样改一处，所有工具同步生效。

第一步：写好 Frontmatter——决定 Agent 会不会用你的技能

Agent 选择技能只看两样东西：name 和 description。如果这两个字段写得不好，你的 SKILL.md 写得再好也不会被触发。

name 命名规范

# ✅ 正确：动名词形式，全小写，连字符分隔

# ❌ 错误：太泛、太模糊

规则：小写字母 + 数字 + 连字符。用动名词（-ing）形式描述技能提供的能力，而非功能名。

description 怎么写——三个必须

description 是 Agent 判断是否加载技能的唯一依据。它必须同时包含：

做什么（技能的功能）
什么时候用（触发场景）
关键词（帮助 Agent 在 100+ 技能中精准匹配）

# ✅ 好的 description

description: >

Processes and extracts text from PDF documents. Use when the user asks to

read, parse, or extract content from PDF files, including scanned documents.

Supports text extraction, metadata reading, and form field detection.

# ❌ 坏的 description——太模糊，Agent 不知道何时触发

description: Helps with PDF files.

# ❌ 坏的 description——缺少触发场景

description: Extracts text from PDF documents using pdfplumber library.

铁律：description 必须用第三人称写。Agent 的系统提示里，技能描述是被注入的上下文，第一人称会让 Agent 困惑"这个'我'是谁"。

实测：如何验证 description 是否有效

把下面这段话贴给任何一个 LLM，看它能不能准确判断触发条件：

I am building an Agent Skill based on the agentskills.io spec. Agents will

decide whether to load this skill based entirely on the YAML metadata below.

<hr>

description: Processes and extracts text from PDF documents. Use when the user

asks to read, parse, or extract content from PDF files, including scanned

documents. Supports text extraction, metadata reading, and form field detection.

<hr>

Based strictly on this description, list 3 user requests that SHOULD trigger

this skill, and 3 that should NOT.

如果你的 description 能让 LLM 准确做出 6/6 判断，它大概率也能在 Agent 环境中被正确触发。

第二步：写核心指令——三条铁律

铁律一：简洁是美德，Claude 本来就很聪明

不要写 Claude 已经知道的东西。 这是最常见的错误——在 SKILL.md 里花 150 个 token 解释"PDF 是一种常见的文件格式，包含文本和图片"。

# ✅ 简洁版（~50 tokens）

## 提取 PDF 文本

使用 pdfplumber 提取文本：

import pdfplumber

with pdfplumber.open("file.pdf") as pdf: text = pdf.pages[0].extract_text()

# ❌ 啰嗦版（~150 tokens）

## 提取 PDF 文本

PDF（Portable Document Format）是一种常见的文件格式，包含文本、图片和

其他内容。要提取文本，你需要使用一个库。有很多 PDF 处理库可供选择，

但推荐 pdfplumber，因为它易于使用且能处理大多数情况。首先需要用 pip

安装它。然后可以使用以下代码……

Agent 已经知道什么是 PDF、pip 和 Python 库。你的 SKILL.md 只应该包含 Agent 不知道的东西——你项目的具体约定、你偏好的工具链、你踩过的坑。

铁律二：匹配自由度到任务脆弱性

Anthropic 官方把指令自由度分为三级：

自由度	形式	适用场景	示例
高	纯文本步骤	灵活决策（代码审查、设计建议）	"检查代码结构和组织，寻找潜在 bug"
中	伪代码 + 参数	有模板但需要适配（生成报告）	`def generate_report(data, format="md")`
低	精确脚本，无参数	精密操作不可偏离（数据库迁移）	`python scripts/migrate.py --verify --backup`

想象 Agent 是一个走路的机器人：

高自由度 = "往北走，找到餐厅"
中自由度 = "沿主街走 500 米，左转"
低自由度 = "踩在这条黄色标记线上，一步一步走"

什么时候用低自由度：涉及生产数据库操作、支付流程、安全配置——任何"错一步就炸"的操作。

铁律三：把重复操作写成脚本，别让 Agent 每次重写

Agent 擅长决策和编排，但不擅长每次都写一模一样的解析逻辑。如果你的技能里需要重复处理某种数据格式，把它写成脚本放在 scripts/ 目录下，让 Agent 直接调用：

# scripts/extract_errors.py

"""从构建日志中提取错误信息的标准脚本"""

import sys, re, json

log = sys.stdin.read()

errors = []

for line in log.split('\n'):

m = re.match(r'ERROR: (.+?) at (.+?):(\d+)', line)

if m:

errors.append({

"message": m.group(1),

"file": m.group(2),

"line": int(m.group(3))

})

print(json.dumps(errors, indent=2))

在 SKILL.md 里只需要写：

## 分析构建错误

运行 `python scripts/extract_errors.py < build.log` 提取结构化错误列表。

第三步：从零写一个实战技能——代码审查员

让我们把理论变成实践。假设你是独立开发者，维护一个 Python 项目，希望 Agent 帮你做代码审查时遵循你的偏好。

目录结构

code-reviewing/

├── SKILL.md

├── references/

│ └── style-guide.md

└── scripts/

└── check_complexity.py

SKILL.md

<hr>

description: >

Reviews Python code changes with a focus on readability, performance,

and security. Use when the user asks for a code review, PR review,

or wants to check code quality. Enforces project-specific conventions

for type hints, docstrings, and error handling.

<hr>

## 审查流程

1. 先读 `references/style-guide.md` 了解项目约定

2. 按以下顺序检查：

- 类型标注是否完整（所有公开函数必须有类型标注）

- 文档字符串是否遵循 Google 风格

- 异常处理是否具体（禁止裸 `except:`）

- 是否有 N+1 查询或循环内的 I/O 操作

3. 运行 `python scripts/check_complexity.py <file>` 检查圈复杂度

4. 输出格式：

代码审查结果

文件： path/to/file.py

评分： X/10

🔴 必须修改

[具体问题 + 行号 + 修复建议]

🟡 建议优化

[具体建议]

🟢 做得好的地方

[值得保留的做法]

references/style-guide.md

# 项目代码风格约定

## 类型标注

- 所有公开函数必须包含完整的参数和返回值类型标注

- 使用 `from __future__ import annotations` 延迟求值

## 文档字符串

- 使用 Google 风格

- 必须包含：简短描述、Args、Returns、Raises（如适用）

## 异常处理

- 禁止裸 `except:` 或 `except Exception:`

- 始终捕获具体异常类型

- 在日志中记录完整的 traceback

## 性能要求

- 禁止在循环内执行数据库查询或 HTTP 请求

- 大列表（>1000 元素）使用生成器而非列表推导

scripts/check_complexity.py

"""检查 Python 文件的圈复杂度"""

import ast, sys, json

def complexity_of(node):

"""计算单个函数的圈复杂度"""

count = 1

for child in ast.walk(node):

if isinstance(child, (ast.If, ast.While, ast.For, ast.And, ast.Or)):

count += 1

elif isinstance(child, ast.ExceptHandler):

count += 1

return count

def analyze_file(path):

with open(path) as f:

tree = ast.parse(f.read())

results = []

for node in ast.walk(tree):

if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):

c = complexity_of(node)

results.append({

"name": node.name,

"line": node.lineno,

"complexity": c,

"warning": c > 10

})

return results

if __name__ == "__main__":

for path in sys.argv[1:]:

print(json.dumps(analyze_file(path), indent=2))

使用效果

把技能文件放到 .claude/skills/code-reviewing/ 后，在任何 AI 编程 Agent 中说：

审查一下 src/api/handlers.py 的代码质量

Agent 会自动：

加载你的 code-reviewing 技能
先读取 style-guide.md 了解项目约定
运行 check_complexity.py 获取数据
按你定义的格式输出审查报告
跳过 lint 类问题（交给 ruff 处理）

踩坑清单

坑一：description 触发不了

症状：技能文件写得没问题，但 Agent 就是不加载。

排查：检查 description 是否包含触发场景关键词。Agent 靠关键词匹配判断，不是语义理解。一个好的测试方法：把 description 单独拿出来，问 LLM"什么情况下你会加载这个技能"，看它是否理解正确。

坑二：SKILL.md 太长撑爆上下文

症状：Agent 加载技能后，对话几轮就开始忘事、输出质量下降。

根因：SKILL.md 正文的每个 token 都在和对话历史竞争上下文窗口。Anthropic 官方建议 SKILL.md 控制在 500 行以内。把细节放到 references/ 目录里按需加载。

坑三：不同模型对技能的"理解力"不同

症状：技能在 Claude Opus 上工作完美，在 Haiku 或 Gemini 上表现退步。

根因：较弱模型需要更具体的指令。如果你的技能偏抽象（"检查代码质量"），小型模型可能不知道从哪下手。测试策略：用你计划使用的所有模型测试一遍技能，找到"最大公约数"的指令粒度。

坑四：在技能目录里放了 README.md

Agent 技能目录是给 Agent 读的，不是给人类读的。不要创建：README.md、CHANGELOG.md、INSTALLATION_GUIDE.md——这些都会在 Agent 探索目录时被误加载，白白浪费 token。

坑五：混淆 Skill、Command 和 Agent

Skill：Agent 根据上下文自动判断是否加载（被动触发）
Command：用户显式调用的快捷指令（主动触发，如 /review）
Agent：能独立完成多步任务的自主实体（有自己的工具和循环）

不要把三者混在一起。Skill 不应该设计成"用户每次都要手动激活"的模式——那是 Command 的职责。

一人公司效率翻倍：我的技能套件推荐

作为独立开发者，以下 5 个技能几乎覆盖了我 80% 的 Agent 使用场景：

技能	用途	核心指令
`writing-commit-messages`	自动生成规范的 commit	Conventional Commits 格式，自动检测 breaking change
`testing-with-pytest`	编写和维护测试	自动检测项目测试框架，匹配已有测试风格
`reviewing-prs`	自动代码审查	按项目约定做深度审查，跳过 lint 类噪音
`writing-documentation`	生成和更新文档	Google 风格 docstring + README 模板
`deploying-to-vercel`	一键部署	预检 + 构建 + 部署 + 健康检查

这些技能都放在项目 .claude/skills/ 下，用符号链接同步到 Codex 和 Gemini。我的 Claude Code、Codex CLI 和 Gemini CLI 共享完全相同的技能文件，零重复维护。

进阶：技能验证与持续优化

用 LLM 验证技能

每个技能写好之后，做三轮验证：

发现验证：把 frontmatter 喂给 LLM，检查触发精度
逻辑验证：把完整 SKILL.md 喂给 LLM，让它执行一次模拟任务，看是否缺失步骤
边界测试：给出一个不应该触发技能的任务，确认 Agent 不会误加载

用 Skillgrade 做回归测试

社区工具 Skillgrade（由 Google Angular 负责人 Minko Gechev 开发）提供技能基准测试框架，能检测你的技能修改是否有回归。推荐在技能文件提交到团队仓库前跑一遍。

团队协作：把技能纳入 Code Review

如果团队共用技能文件，把技能目录加到 Code Review 的要求里。每次有人修改技能，其他人 review 的不仅是代码，还有"Agent 行为是否被意外改变"。

总结

SKILL.md 是 2026 年 AI 编程 Agent 生态最大的"复利资产"。投入一小时写好一个技能，它会在你未来每一次和 Agent 对话中反复产生价值——而且跨工具复用。

三个核心原则记住：

Description 决定一切——Agent 选技能只看这两行，必须包含"做什么 + 何时用 + 关键词"
简洁到极致——Claude 本来就很聪明，只写它不知道的东西
把重复工作写成脚本——Agent 擅长编排，不擅长每次都写一样的解析逻辑

花 30 分钟把你的第一个技能写出来，放到 .claude/skills/ 下，然后告诉你的 Agent "用这个技能审查代码"。你会立刻感受到差距。

#AI创业 #Agent工坊 #SKILL.md #Claude Code #一人公司

*本文由AI辅助创作，经人工审核编辑发布。技能规范参考自 Anthropic 官方文档、mgechev/skills-best-practices、OpenAI Codex 开发者文档。具体工具行为可能随版本更新变化，请以官方最新文档为准。*

本文由AI辅助创作，经人工审核编辑发布