AI Agent Skills 从入门到精通：用 SKILL.md 把提示词升级成可复用工作流

如果你最近关注 Codex、Claude Code、MCP、AI Agent，就会频繁看到一个词：Skill。

很多人第一次听到 Skill，会把它理解成“提示词模板”。这个理解只对了一半。更准确地说，Skill 是一种把经验、流程、代码脚本、参考资料和约束条件打包起来的能力模块。它让 AI Agent 不必每次都从零理解任务，也不必把所有背景一次性塞进上下文，而是在需要时按需加载相关能力。

本文基于 OpenAI Codex 文档、Anthropic Claude Agent Skills 文档、Agent Skills 开放规范、Microsoft Agent Framework 文档和相关工程文章，系统讲清楚 Skill 是什么、为什么重要、怎么写、怎么测试，以及怎样从一个简单的 SKILL.md 走到团队级可复用工作流。

一、Skill 到底是什么

一句话定义：

Skill 是给 AI Agent 使用的可复用能力包，通常由 SKILL.md、可选脚本、参考资料和静态资产组成，用来稳定完成某一类重复任务。

从公开资料看，不同厂商的叫法略有差异，但核心形态高度一致：

• OpenAI Codex 文档把 Skills 描述为用于重复工作流的可复用能力，支持更丰富的说明、脚本和参考资料，并通过渐进式披露减少上下文占用。
• Anthropic Claude 文档把 Agent Skills 定义为扩展 Claude 能力的模块化能力包，包含说明、元数据和可选资源。
• Agent Skills 开放规范把 Skill 抽象为一个目录，核心文件是 SKILL.md，可选目录包括 scripts/、references/、assets/。
• Microsoft Agent Framework 文档强调 Agent Skills 是可移植的指令、脚本和资源包，用于给 Agent 提供专业能力和领域知识。

也就是说，Skill 不是模型训练，不是插件本身，也不是单次提示词。它更像一个轻量级“工作流组件”：让 Agent 知道什么时候该用、该读哪些说明、该运行哪些脚本、该如何验证结果。

二、为什么 Skill 会出现

没有 Skill 时，团队通常靠这几种方式约束 AI：

这些方式短期可用，长期会遇到几个问题。

首先是上下文浪费。一个复杂流程可能包含几十条规则、示例、异常处理和脚本说明，但并不是每个任务都需要全部读取。如果每次都塞进系统提示，会占用宝贵上下文。

其次是触发不稳定。人类说“发版”“修 CI”“整理文档”时，背后可能有固定步骤，但普通提示词很难稳定绑定到这些步骤。

第三是团队知识难沉淀。一个资深工程师知道 PR 审查顺序、灰度发布检查项、文档规范和数据脱敏规则，但这些经验如果只存在聊天记录里，下次仍然要重新解释。

Skill 的价值就是把这些重复经验从“临时提示词”变成“可发现、可加载、可迭代、可复用”的工程资产。

三、Skill 和提示词、工具、MCP、插件有什么区别

一个实用判断是：

• 只用一次：写提示词。
• 每个项目都要遵守：写项目说明或配置。
• 需要访问外部系统：接 MCP。
• 需要把一套流程反复复用：写 Skill。
• 需要把多个 Skill、连接器和资源分发给别人：做 Plugin。

四、Skill 的核心机制：渐进式披露

Skill 最重要的机制不是目录结构，而是“渐进式披露”。

通俗讲，就是 Agent 不会一开始读完所有 Skill 的全部内容，而是分阶段加载：

这带来两个好处。

第一，省上下文。几十个 Skill 可以同时存在，但只有命中的 Skill 会展开。

第二，降低干扰。一个 PDF 处理 Skill 不应该影响代码审查；一个 CSDN 发布 Skill 不应该影响数据库优化。Skill 的描述越清晰，触发越稳定。

五、一个 Skill 的标准目录结构

典型结构如下：

my-skill/
├── SKILL.md
├── scripts/
│ └── validate.py
├── references/
│ └── style-guide.md
├── assets/
│ └── template.md
└── agents/
└── openai.yaml

最小可用版本只需要一个 SKILL.md。

scripts/ 用来放可执行脚本，比如校验、生成、转换、部署前检查。
references/ 用来放长文档、规范、错误手册、字段说明。
assets/ 用来放模板、图片、样例数据、配置样板。
agents/openai.yaml 这类文件可用于声明界面元信息、依赖工具或是否允许隐式触发，具体支持程度取决于宿主产品。

六、SKILL.md 怎么写

一个基础 SKILL.md 通常由两部分组成：YAML frontmatter 和 Markdown 正文。

—
name: api-contract-review
description: Review OpenAPI contracts for breaking changes, naming consistency, missing examples, and mock-case coverage. Use when the user asks to review API specs, OpenAPI files, or interface design.
—

# API Contract Review

## Workflow

1. Read the OpenAPI file and identify changed endpoints.
2. Check request and response schemas for breaking changes.
3. Verify naming consistency, examples, error codes, and pagination rules.
4. Generate a short risk report with blocking issues first.

## Output

– Findings ordered by severity.
– File and line references when available.
– Suggested fixes with minimal schema changes.

这里最关键的是 description。它不是广告文案，而是触发条件。写得太泛，Agent 容易误触发；写得太窄，Agent 又想不到要用它。

好的描述通常包含三类信息：

• 这个 Skill 做什么。
• 用户说什么时应该触发。
• 什么情况不应该触发。

例如：

description: Publish a Markdown article to CSDN through the CSDN editor. Use when the user asks to post, publish, send, or upload a CSDN blog article. Do not use for CSDN resource package uploads.

这个描述比“CSDN helper”稳定得多，因为它明确了用途和边界。

七、从入门到进阶：四种 Skill 写法

1. 入门级：纯说明型 Skill

适合没有脚本、没有外部系统、只需要稳定流程的任务。

例子：

• 代码审查清单。
• 周报格式。
• 技术文章写作风格。
• SQL 优化报告模板。
• PR 描述生成规范。

这类 Skill 的重点是步骤清楚、输出格式固定、边界明确。

2. 进阶级：参考资料型 Skill

当主流程不复杂，但资料很多时，把长内容移到 references/。

例如一个“公司数据看板分析 Skill”：

dashboard-analysis/
├── SKILL.md
└── references/
├── metrics-dictionary.md
├── dashboard-rules.md
└── common-anomalies.md

SKILL.md 只写主流程，细节文档按需读取。这样既不浪费上下文，也能保留足够专业知识。

3. 工程级：脚本增强型 Skill

当任务需要确定性结果时，就该引入 scripts/。

例如：

• 发布前运行检查脚本。
• 自动解析日志并生成报告。
• 校验 Excel 表头和字段类型。
• 根据模板生成项目骨架。
• 扫描 zip 包是否包含隐私文件。

脚本的作用不是取代 Agent，而是把容易出错、需要确定性、可自动验证的部分固定下来。Agent 负责判断和组织，脚本负责执行和校验。

4. 专家级：Skill + MCP + Plugin

当 Skill 需要外部系统时，可以配合 MCP。

例如：

• Skill 规定 GitHub Issue triage 流程，MCP 负责读取 issue、评论、打标签。
• Skill 规定 Notion 知识库写作格式，MCP 负责创建页面。
• Skill 规定发布流程，浏览器或平台连接器负责实际发布。

当这套能力要分发给团队或客户时，再把 Skill、MCP 配置、图标、模板打包成 Plugin。一个判断标准是：自己本地用，Skill 足够；多人安装，Plugin 更合适。

八、如何设计一个好 Skill

我建议按下面 7 步设计。

第一步：明确一个单一任务

不要写“万能研发助手 Skill”。Skill 越大，越容易触发混乱。

更好的命名方式是：

• release-note-writer
• api-contract-review
• pdf-form-filler
• csdn-article-publisher
• weekly-metrics-analysis

一个 Skill 只服务一个高频任务。

第二步：写触发描述

描述要像路由规则，不要像介绍文案。

差的写法：

description: Help with documents.

好的写法：

description: Create and verify Word documents from structured notes. Use when the user asks for a .docx report, contract draft, redline, or formatted Word deliverable.

第三步：把流程写成动作

Skill 正文应该多用动词：

• Read
• Validate
• Generate
• Compare
• Verify
• Publish
• Record

不要只写原则，要写操作顺序。

第四步：定义输入和输出

Agent 最怕模糊目标。Skill 应明确：

• 输入来自哪里。
• 输出是什么格式。
• 是否要保存文件。
• 是否要运行测试。
• 失败时怎么报告。

第五步：把长资料拆出去

如果 SKILL.md 超过几百行，就考虑拆到 references/。主文件只保留触发、流程和关键约束。

第六步：把确定性检查写成脚本

比如：

scripts/
├── validate_metadata.py
├── render_preview.py
└── pre_publish_check.py

脚本要有清晰错误信息，失败时不要静默退出。否则 Agent 看不懂，也难以自动恢复。

第七步：记录失败路径

成熟 Skill 不只写成功路径，还要写错误手册：

references/
└── error-playbook.md

里面记录：

• 页面变了怎么办。
• 校验失败怎么办。
• 登录或权限阻断怎么办。
• 哪些操作不能绕过。
• 哪些现象表示必须交给人处理。

这会显著提升长期稳定性。

九、Skill 的测试方法

写 Skill 不能只看“它能不能用”，还要测试“它会不会乱用”。

1. 触发测试

准备 5 个应该触发的提示：

• “帮我发布一篇 CSDN 文章”
• “把这个接口规范做一次审查”
• “生成一份 Word 格式合同”

再准备 5 个不应该触发的提示：

• “解释一下 CSDN 是什么”
• “只帮我润色标题，不要发布”
• “这个接口规范的业务背景是什么”

如果 Skill 经常误触发，先改 description。

2. 行为测试

检查 Agent 是否按流程执行：

• 是否先读必要资料。
• 是否运行校验脚本。
• 是否在失败时停止。
• 是否按约定输出结果。

3. 回归测试

每次修改 Skill 后，用同一批提示重新跑一遍，看行为是否变坏。

4. 安全测试

尤其要检查：

• 是否包含密钥、Cookie、Token、个人路径。
• 是否会把私有数据发到外部站点。
• 是否会运行来历不明脚本。
• 是否会越权读取文件。
• 是否把危险操作写成默认行为。

Anthropic 的工程文章也特别提醒：Skill 因为包含说明和代码，所以第三方 Skill 可能带来环境漏洞、数据外泄或非预期动作。安装前应该审计文件内容、依赖和外部网络访问。

十、常见反模式

1. 一个 Skill 包打天下

如果一个 Skill 同时负责写文章、发资源、修代码、查日志、做图表，触发逻辑一定混乱。拆成多个小 Skill。

2. description 写得像广告

“让你更高效地完成各种任务”没有触发价值。Agent 需要的是任务边界和关键词。

3. 把所有资料塞进 SKILL.md

这样会浪费上下文，也会让 Agent 迷失重点。主流程放 SKILL.md，长资料放 references/。

4. 脚本没有校验和错误信息

脚本失败只返回一堆堆栈，对 Agent 不友好。应该输出明确原因和修复方向。

5. 把凭据写进 Skill

Skill 里不能放密码、Token、Cookie、私钥。需要访问外部系统时，用宿主环境的授权机制、连接器或 MCP。

6. 忽略人工验证边界

涉及验证码、支付、实名、安全确认、外部发布、权限变更时，Skill 应明确哪些步骤可以自动做，哪些必须交给人确认。

十一、一个可直接套用的 Skill 模板

—
name: task-name
description: Do one specific task. Use when the user asks for X, Y, or Z. Do not use when the task is only asking for explanation or brainstorming.
—

# Task Name

## Goal

State the concrete outcome this skill should produce.

## Inputs

– Required input:
– Optional input:
– Assumptions:

## Workflow

1. Inspect the current context.
2. Read only the needed reference files.
3. Run deterministic scripts when validation matters.
4. Produce the requested output.
5. Verify the result.
6. Report status, links, and blockers.

## Safety Rules

– Do not read or expose credentials.
– Do not submit external side effects unless the user requested that action.
– Stop and report if authentication, CAPTCHA, payment, or security verification appears.

## Output Format

– Summary:
– Files changed:
– Verification:
– Next step:

## Recovery

– If validation fails:
– If external service blocks:
– If required input is missing:

这个模板不追求华丽，但稳定。真正好用的 Skill 通常就是这种风格：目标明确、步骤具体、失败可恢复。

十二、从个人效率到团队资产

Skill 的成熟路线可以分成四层。

第一层，个人效率。把自己经常重复的提示词整理成 Skill，比如周报、代码审查、文章发布、数据分析。

第二层，项目规范。把某个仓库特有的测试命令、目录约定、发布流程放到 repo 级 Skill。

第三层，团队标准。把多人共享的审查规范、文档规范、合规检查做成可复用 Skill，并配套测试用例。

第四层，平台化分发。把多个 Skill、MCP 连接器、模板和图标做成 Plugin，让团队成员安装即用。

这时 Skill 已经不只是“提示词技巧”，而是 Agent 工作流工程的一部分。

十三、我的实践建议

如果你第一次写 Skill，建议不要从复杂平台开始。选一个你每周至少重复 3 次的任务。

比如：

• 每次 PR 都要按同一套顺序审查。
• 每次写 CSDN 文章都要查资料、写标题、填标签、发到固定专栏。
• 每次上传资源都要生成 README、运行测试、打包、扫描隐私。
• 每次分析日志都要提取错误类型、影响范围、复现步骤和修复建议。

然后只做三件事：

很多团队一开始想做“全自动专家系统”，结果 Skill 过大、触发混乱、难以维护。更好的路线是从小流程开始，让 Skill 像代码一样逐步演进。

十四、结语

Skill 的本质，是把“我希望 AI 这么做”的临时表达，沉淀成“Agent 可以稳定复用的工作流资产”。

它解决的不是模型聪不聪明的问题，而是工程系统里更实际的问题：如何复用经验、如何控制上下文、如何减少重复提示、如何让团队知识可执行、如何让 Agent 在复杂任务里更稳定。

未来的 AI Agent 不会只靠一个超长系统提示运行。更可能的形态是：基础模型负责理解和推理，工具负责行动，MCP 负责连接外部系统，Skill 负责封装专业流程，Plugin 负责分发组合能力。

对开发者来说，学会写 Skill，就像过去学会写脚本、写 CI、写 Makefile 一样，是把个人经验变成工程能力的一步。

参考资料

• OpenAI Codex / ChatGPT 文档：Build skills
  https://learn.chatgpt.com/docs/build-skills
• OpenAI Codex / ChatGPT 文档：Customization – Skills
  https://learn.chatgpt.com/docs/customization/overview#skills
• Anthropic Claude Platform 文档：Agent Skills
  https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
• Anthropic Engineering：Equipping agents for the real world with Agent Skills
  https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
• Agent Skills 开放规范
  https://agentskills.io/specification
• Microsoft Learn：Agent Skills
  https://learn.microsoft.com/en-us/agent-framework/agents/skills
• arXiv：Authoring Agent Skills: A Software-Engineering Approach
  https://arxiv.org/abs/2607.25032
• arXiv：Agent Skills: A Data-Driven Analysis of Claude Skills for Extending Large Language Model Functionality
  https://arxiv.org/abs/2602.08004