SKILL.md模式：如何编写真正有效的AI Agent技能

如果你的技能没有触发，问题几乎从不在于指令本身，而在于描述。这是大多数人在经历一小时挫折后才领悟的关键点。本文将深入解析SKILL.md的工作原理，揭示常见错误，并通过4个从简单到复杂的技能构建实例，让你彻底掌握模式精髓。

1. 理解SKILL.md的本质

技能不是插件，也不是连接到API的脚本。把它想象成是为新团队成员编写的工作指南。你不需要在每次对话中重复解释工作流程和偏好，只需打包一次，当用户请求匹配时，Agent会自动调用。

技能的核心结构是一个文件夹：

your-skill-name/
├── SKILL.md          # 必需：指令 + 元数据
├── scripts/          # 可选：Agent执行的代码
├── references/       # 可选：按需加载的文档
└── assets/           # 可选：模板、图片、字体

唯一必需的文件是 SKILL.md。其他都是可选的，但随着技能复杂度增加，它们会变得重要。

SKILL.md格式是一个开放标准，由Anthropic于2025年12月在agentskills.io发布。它适用于Claude Code、OpenAI Codex和OpenClaw。虽然格式标准化，但每个平台的实现略有不同。技能在Claude Code上运行后，在Codex上也很可能运行，但会话快照、工具权限和调用模式等运行时行为在平台间存在差异。

2. 技能的存储位置

在编写任何内容之前，你需要知道把它放在哪里。每个平台从特定位置加载技能，位置决定了作用域。

Claude Code：

~/.claude/skills/ - 个人级别，适用于所有项目
.claude/skills/ - 项目级别，通过git与团队共享

OpenAI Codex：

~/.codex/skills/ - 用户级别，适用于任何仓库
.codex/skills/ - 仓库级别，提交到git

OpenClaw：

~/.openclaw/skills/ - 全局级别，适用于所有配置的Agent
每个Agent工作区 - 仅限特定Agent

当两个技能同名时，更高优先级的位置获胜。项目级技能会覆盖同名的个人级技能。这允许团队定义默认设置，个人可以根据自己的需求覆盖。

3. 三级加载系统的工作原理

这是大多数人忽略的部分，它解释了技能不触发或消耗过多上下文的几乎所有问题。

技能使用渐进式披露：一个三级加载系统，内容只在需要时才被拉入上下文。

第1级：元数据（始终加载，每个技能约100个token）

启动时，Agent只读取每个已安装技能的YAML前言中的 name 和 description。没有其他内容。这个紧凑的列表会进入系统提示，让Agent知道有哪些技能以及何时使用它们。实际意义是：你可以安装许多技能而不会带来上下文惩罚。

第2级：指令（触发时加载，不超过5000个token）

当Agent决定某个技能相关时，它会使用bash调用读取 SKILL.md 的完整主体。只有在这时，你的实际指令才会被加载。

第3级：引用文件和脚本（按需加载，实际上无限制）

如果技能主体引用了其他文件，Agent只在需要时才读取它们。脚本可以在不被读入上下文的情况下执行。这使技能具有可扩展性：无论你捆绑多少内容，空闲时的token成本为零。

以下是一个真实请求的顺序示例：

1. 会话启动
   --> Agent加载：每个技能的name + description（约100个token）

2. 用户问："你能为这个项目写一个README吗？"
   --> Agent读取：readme-writer/SKILL.md完整主体（第2级）

3. SKILL.md引用了一个样式指南文件
   --> Agent读取：readme-writer/references/style.md（第3级）

4. SKILL.md包含一个验证脚本
   --> Agent执行：scripts/validate.sh（运行但不读入上下文）

4. 技能与斜杠命令的区别

Claude Code和Codex都支持两种调用模式。Agent可以在你的请求匹配描述时自动激活技能（隐式调用），或者你可以直接调用它（显式调用）。

在Claude Code中，技能默认出现在斜杠命令菜单中。你可以用 /skill-name 直接调用，或者只描述你想要的内容，Claude会自动激活相关技能：

# Claude Code中的直接调用
/readme-writer

# 或者只描述任务，Claude会自动激活
你能为这个项目写一个README吗？

在Codex CLI中，你可以用 $ 前缀提及技能或使用 /skills 选择器：

# Codex CLI中的显式调用
$readme-writer document this project

# 或使用技能选择器
/skills

尽管两个平台都支持显式调用，但编写良好的描述仍然非常重要。它驱动着自动激活，这种行为让技能感觉像是你工作方式的自然延伸，而不是你必须记住输入的命令。

5. 最常见的错误

YAML前言中的 description 字段不是给人看的。它是Agent在决定是否激活你的技能时使用的触发条件。

有效的结构是：

[技能做什么] + [何时使用，包含具体触发短语]

糟糕的描述：

description: 帮助处理文档。

也很糟糕，因为它描述了做什么但没有说明何时用：

description: 创建具有高级格式的复杂多页文档。

好的描述：

description: 为软件项目创建和编写专业的README.md文件。当用户要求"写README"、"创建readme"、"记录这个项目"、"生成项目文档"或"帮我写README.md"时使用。

agentskills.io规范定义了这些约束：

name：仅限小写字母、数字和连字符，最多64个字符，不能以连字符开头或结尾，不能有连续连字符
description：最多1024个字符，必须描述技能做什么以及何时使用
文件必须精确命名为 SKILL.md，区分大小写
在前言中避免使用XML尖括号（< 或 >），因为它们可能会将意外指令注入系统提示

一些平台在这些基础上添加了自己的约定。如有疑问，请查看平台特定文档以及agentskills.io/specification的基础规范。

6. 技能实例1：README写入器

这是一个实用的入门技能。几乎每个开发者都写过README，通常是手动完成，而且不一致。这个技能教Agent你的首选结构，并自动将文件写入磁盘。

设置

mkdir -p ~/.claude/skills/readme-writer

SKILL.md内容

---
name: readme-writer
description: 为软件项目创建和编写专业的README.md文件。当用户要求"写README"、"创建readme"、"记录这个项目"、"生成项目文档"或"帮我写README.md"时使用。基于项目描述、现有代码或两者兼有。
---

# README写入器

## 概述
生成一个完整的、专业的README.md文件并写入磁盘。输出应该清晰到足以让第一次贡献者理解项目、本地设置并开始贡献。

## 第1步：收集项目上下文
在询问用户之前，先查看代码库中的上下文：
```bash
ls -la
cat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || \
  cat go.mod 2>/dev/null || echo "No manifest found"
ls .env.example .env.sample 2>/dev/null || echo "No env example found"

收集：

这个项目做什么？（1-2句话总结）
使用什么语言和主要框架？
如何安装和运行？
需要环境变量吗？
有LICENSE文件吗？

第2步：编写README

使用这个结构。只包含相关的章节。不要添加空章节。

# 项目名称
一句话清晰描述这个项目做什么以及为谁服务。

## 功能特性
- 功能一（具体说明）
- 功能二

## 前提条件
列出需要安装的内容。如果重要，包含版本要求。

## 安装
分步设置。每个命令都必须可复制粘贴。
```bash
git clone https://github.com/username/project
cd project
npm install

配置

如果项目需要环境变量，显示示例：

cp .env.example .env

然后解释用户需要手动设置的每个变量。

使用

首先展示最常见的用例。

npm run dev

许可证

MIT


## 第3步：将文件写入磁盘
内容准备好后，写入文件：
```bash
cat > README.md << 'EOF'
[完整的README内容]
EOF

确认已写入：

echo "README.md written: $(wc -l < README.md) lines"

第4步：质量检查

完成前验证：

[ ] 没有遗留像"[your description here]"这样的占位符文本
[ ] 安装部分的每个命令对此项目都是准确的
[ ] 前提条件与项目实际需要的相符
[ ] 许可证部分与LICENSE文件匹配（如果存在）


### 测试
进入任何项目文件夹并问：

你能为这个项目写一个README吗？

Agent会检查代码库、写入README、保存为 `README.md`，并用行数确认。无需复制粘贴。

---

## 7. 技能实例2：Git提交消息生成器

这个技能展示了如何编写覆盖开发者可能以不同方式询问相同事物的触发短语。

### 设置
```bash
mkdir -p ~/.claude/skills/git-commit-writer

SKILL.md内容

---
name: git-commit-writer
description: 生成遵循常规提交规范的标准化git提交消息。当用户要求"写提交消息"、"帮我提交"、"总结我的更改"、"我的提交应该说什么"或"起草提交"时使用。分析暂存的差异和更改描述，生成type(scope): description格式的消息。
---

# Git提交消息写入器

## 格式

type(scope): 简短描述

[可选正文]

[可选页脚]


允许的类型：feat, fix, docs, style, refactor, test, chore, perf, ci, build

## 指令

### 第1步：获取差异
```bash
git diff --staged

如果没有暂存内容：

git diff HEAD

第2步：分析更改

查看：

哪些文件更改了以及它们属于什么类别
这是添加新功能（feat）、修复bug（fix）还是更新文档/配置/测试
范围：哪个模块、组件或区域受到影响

第3步：编写消息

主题行保持在72个字符以内
使用祈使语气："添加功能"而不是"添加了功能"
主题行末尾不要加句号
如果更改需要比主题允许的更多上下文，添加正文

质量检查

[ ] 类型是允许的类型之一
[ ] 主题行在72个字符以内
[ ] 使用了祈使语气
[ ] 范围足够具体以有用

示例

feat(auth): 添加Google OAuth2登录

使用现有的会话管理系统实现Google OAuth2流程。用户现在可以使用他们的Google账户登录。

Closes #142

fix(api): 处理支付提供商的空响应

docs(readme): 更新Node 22的本地设置说明


---

## 8. 技能实例3：代码审查器（多文件）

这个技能展示了何时将内容拆分到多个文件中。流程保留在 `SKILL.md` 中。详细标准保存在仅在实际审查期间加载的引用文件中。这是构建复杂技能的正确方式。

### 设置
```bash
mkdir -p ~/.claude/skills/code-reviewer/references

SKILL.md内容

---
name: code-reviewer
description: 进行结构化代码审查，提供分类反馈。当用户要求"审查此代码"、"检查我的PR"、"看看这个函数"或"给我关于这个实现的反馈"时使用。生成结构化输出，将阻塞性问题与建议分开。
---

# 代码审查器

## 审查流程

### 第1步：理解上下文
审查前确定：
- 这段代码应该做什么？
- 使用什么语言和框架？
- 这是新功能、bug修复还是重构？

### 第2步：运行审查
有关按类别的详细审查标准，请参阅 [references/criteria.md](references/criteria.md)。

按顺序处理每个类别。即使某些类别看起来不太可能有问题，也不要跳过。

### 第3步：构建输出
```markdown
## 总结
[2-3句话概述和整体评估]

## 阻塞性问题
[必须修复的问题：安全漏洞、逻辑错误、数据丢失风险。如果没有，写"未发现"。]

## 建议
[非阻塞性改进建议，编号列出。包含位置、原因和修复方法。]

## 正面评价
[代码做得好的地方。始终至少包含一点。]


### references/criteria.md内容

```markdown
# 审查标准

## 安全性（首先检查）
- SQL注入：用户输入是否参数化？
- XSS：输出在渲染前是否正确转义？
- 认证检查：受保护的路由是否真的受到保护？
- 密钥：API密钥或凭据是否硬编码在任何地方？
- 输入验证：验证是否在服务器端进行？

## 正确性
- 逻辑是否符合既定意图？
- 边缘情况是否处理：空数组、null值、零、负数？
- 错误状态是否正确呈现？
- 异步操作是否正确等待？

## 可读性
- 新团队成员能否在5分钟内理解？
- 变量和函数名是否描述性？
- 函数是做一件事还是多件事？

## 性能
- 是否有明显的N+1查询模式？
- 昂贵的操作是否在循环内（可以移到循环外）？

## 测试
- 是否有针对新行为的测试？
- 是否测试了边缘情况，而不仅仅是快乐路径？

SKILL.md 主体保持在40行以内。详细标准保存在 references/criteria.md 中，仅在审查运行时加载。这保持第2级精简，同时Agent仍然可以在第3级访问它需要的一切。

9. 技能实例4：带有MCP的Sprint规划器

这是第3类技能：MCP增强。MCP服务器让Agent访问Linear的API。技能让Agent知道如何可靠且一致地使用该访问权限。没有技能时，用户连接MCP但仍需弄清楚每一步。有了技能，整个工作流可以从一句话运行。

设置

mkdir -p ~/.claude/skills/linear-sprint-planner/references

SKILL.md内容

---
name: linear-sprint-planner
description: 自动化Linear sprint规划，包括周期创建、待办事项分类和容量规划。当用户要求"规划sprint"、"创建sprint"、"规划周期"或"整理待办事项"时使用。需要Linear MCP服务器。
allowed-tools: mcp_linear_create_cycle, mcp_linear_create_issue, mcp_linear_update_issue, mcp_linear_search_issues, mcp_linear_list_teams
---

# Linear Sprint规划器

## 概述
自动化sprint规划流程。创建周期、对问题进行分类、分配容量，并提供清晰的规划总结。

## 第1步：收集上下文
```bash
# 获取团队和当前周期信息
mcp_linear_list_teams
mcp_linear_search_issues(query:"assignee:me status:backlog")

收集：

团队名称和ID
当前活跃周期（如果有）
待办事项列表及其优先级

第2步：创建周期（如果需要）

如果用户请求新sprint：

mcp_linear_create_cycle({
  teamId: "team_id_here",
  name: "Sprint 2026-Q1-W7",
  startsAt: "2026-02-16",
  endsAt: "2026-03-01"
})

第3步：对问题进行分类

根据优先级和类型对待办事项进行分组：

高优先级：关键bug、安全问题、生产问题
中优先级：功能开发、性能改进
低优先级：文档、小改进、技术债务

第4步：分配容量

为每个问题分配故事点：

1点：简单任务，几小时工作量
2-3点：中等任务，1-2天工作量
5点：复杂任务，3-5天工作量
8点：非常复杂，需要拆分

第5步：更新问题

// 将问题分配到周期
mcp_linear_update_issue({
  issueId: "issue_id_here",
  cycleId: "cycle_id_here",
  estimate: 3,
  priority: 2
})

第6步：生成规划报告

# Sprint规划报告

## 周期：Sprint 2026-Q1-W7
- **开始日期**：2026-02-16
- **结束日期**：2026-03-01
- **总容量**：40点

## 问题分配

### 高优先级（15点）
1. 修复登录超时问题 - 5点
2. 更新支付API集成 - 8点
3. 解决数据同步错误 - 2点

### 中优先级（20点）
4. 实现用户个人资料编辑 - 8点
5. 优化搜索性能 - 5点
6. 添加导出功能 - 5点

### 低优先级（5点）
7. 更新API文档 - 2点
8. 清理未使用的依赖 - 3点

## 建议
- 考虑将问题#2拆分为更小的任务
- 问题#4可能需要设计评审
- 预留20%容量用于意外工作


### 测试
在Linear项目中问：

帮我规划下一个sprint

Agent会连接到Linear MCP，获取待办事项，创建周期，对问题进行分类，分配容量，并生成详细的规划报告。

---

## 常见问题解答

### 何时应该将技能拆分为多个文件？
当SKILL.md主体接近500行时。将详细标准、示例或参考资料放入单独的文件中，让Agent按需加载。

### 描述应该多具体？
非常具体。包含用户可能说的实际短语。"写README"、"创建readme"、"记录这个项目"都是好的触发短语。

### 如何测试技能是否有效？
使用不同的方式描述同一任务，看技能是否激活。测试显式调用（`/skill-name`）和隐式调用（描述任务）。

### 技能应该有多复杂？
从简单开始。一个清晰的指令集比复杂的嵌套结构更有效。随着需求增长再添加复杂性。

### 如何处理技能冲突？
项目级技能优先于个人级技能。更具体的描述优先于通用描述。测试并根据需要调整。

SKILL.md模式：如何编写真正有效的AI Agent技能

SKILL.md模式：如何编写真正有效的AI Agent技能

目录

1. 理解SKILL.md的本质

2. 技能的存储位置

3. 三级加载系统的工作原理

4. 技能与斜杠命令的区别

5. 最常见的错误

6. 技能实例1：README写入器

设置

SKILL.md内容

第2步：编写README

配置

使用

许可证

第4步：质量检查

SKILL.md内容

第2步：分析更改

第3步：编写消息

质量检查

示例

SKILL.md内容

9. 技能实例4：带有MCP的Sprint规划器

设置

SKILL.md内容

第2步：创建周期（如果需要）

第3步：对问题进行分类

第4步：分配容量

第5步：更新问题

第6步：生成规划报告

延伸阅读

为什么我的 iOS 构建在上传到 App Store 之前总是失败？

你的应用准备好部署到 Azure 了吗？如何在部署前发现阻碍

为什么我的 SwiftUI 布局在数据量大时会卡顿或崩溃？

如何自动化运行代码实验而不至于手忙脚乱

2026年研究型Agent技能全景评测：7款工具深度解析

5个日常高频使用的Agent技能实战指南