用 AI 写代码、写文档久了，你大概会遇到这样的烦恼：

  • 每次让它写提交信息，都要重新交代一遍团队的格式规范；
  • 每次让它处理 PDF、生成周报、做代码审查，都要把同一套步骤再粘贴一次；
  • 把这些规范全塞进系统提示词，提示词越来越长，模型反而“抓不住重点”。

Skill（技能） 就是为解决这个问题而生的。它把“怎么做某件事”的经验打包成一个文件夹，Agent 平时只记住它的名字和用途，真正需要时才把完整说明读进来。

本文从定义、结构、工作原理、与 Prompt / MCP 的区别，到动手写一个 Skill，带你完整认识它。

一、一句话定义

Skill 是一个包含 SKILL.md 文件的文件夹，用来给 AI Agent 提供某项任务的专业知识和操作流程，Agent 在任务匹配时按需加载。

它最初由 Anthropic 为 Claude 设计，2025 年 12 月以 Agent Skills 的名字作为开放标准发布（规范见 agentskills.io）。目前 Claude Code、OpenAI Codex、GitHub Copilot、Cursor、Gemini CLI 等主流 AI 编程工具都已支持这一格式，同一个 Skill 写一次，可以在多个 Agent 里复用。

可以把它类比成：

  • 给新同事的一份岗位操作手册：平时放在书架上，遇到对应的活儿再翻开；
  • 或者游戏里的技能书：装备上之后，角色就“学会”了一项本领。

二、一个 Skill 长什么样

最小的 Skill 只需要一个文件：

my-skill/
└── SKILL.md

完整一点的 Skill 可以带上脚本、参考文档和资源文件：

pdf-processing/
├── SKILL.md          # 必需：元数据 + 操作说明
├── scripts/          # 可选：可执行脚本（Python、Bash 等）
├── references/       # 可选：详细参考文档，按需读取
└── assets/           # 可选：模板、图片、数据文件

SKILL.md 的格式

SKILL.md 由两部分组成：开头的 YAML 元数据（frontmatter），和后面的 Markdown 正文。

---
name: pdf-processing
description: 提取 PDF 中的文字和表格、填写 PDF 表单、合并多个 PDF。当用户处理 PDF 文件，或提到表单、文档提取时使用。
---

# PDF 处理

## 提取文字
1. 用 scripts/extract.py 提取全文：`python scripts/extract.py input.pdf`
2. 如果是扫描件（提取结果为空），改用 OCR，见 [OCR 说明](references/OCR.md)

## 填写表单
……

元数据里有两个必填字段：

字段规则作用
name1–64 个字符，只能用小写字母、数字和连字符；不能以连字符开头或结尾，不能出现连续的 --；必须和文件夹同名Skill 的唯一标识
description1–1024 个字符说明它做什么、什么时候用，Agent 靠它判断要不要启用这个 Skill

还有几个可选字段：license（许可证）、compatibility（环境要求，如“需要 git 和 docker”）、metadata（自定义键值对，如作者、版本）、allowed-tools（预先授权的工具，目前是实验性字段，各家支持程度不一）。

正文没有格式限制，写任何能帮 Agent 把事做好的内容即可，通常包括：分步操作说明、输入输出示例、常见的边界情况。

三、核心机制：渐进式披露

Skill 最巧妙的设计是 渐进式披露（Progressive Disclosure）：不是一次性把所有内容塞给模型，而是分三层、按需加载。

层级内容何时加载体量
第 1 层：元数据name + descriptionAgent 启动时，所有 Skill 都加载每个约 100 tokens
第 2 层：说明SKILL.md 正文任务和 description 匹配、Skill 被启用时建议少于 5000 tokens
第 3 层：资源scripts/、references/、assets/ 里的文件正文里引用到、确实需要时按需

举个例子：你装了 50 个 Skill，Agent 启动时只多读了大约 5000 tokens 的“目录”。当你说“帮我把这三个 PDF 合并”时，它从目录里认出 pdf-processing，才去读这个 Skill 的正文；正文里提到合并要用 scripts/merge.py，它再去运行这个脚本——而且脚本代码本身不必进入上下文，只有运行结果会。

这带来两个好处：

  1. 能装很多 Skill，却几乎不占上下文。系统提示词不用越写越长。
  2. 确定性的工作交给代码。排序、格式校验、文件转换这类事，让模型“想”既慢又容易出错，写成脚本让它执行，结果稳定得多。

四、Skill 和 Prompt、MCP、Function Calling 有什么区别

这几个概念经常被混在一起，其实它们解决的是不同层面的问题：

解决什么形式加载方式
系统提示词 / 规则文件（如 CLAUDE.md、AGENTS.md）项目里始终适用的约定一段文本每次对话都全量加载
Skill某类任务的专业知识和流程文件夹（说明 + 脚本 + 资料）任务匹配时按需加载
MCP连接外部系统（数据库、GitHub、Slack……）一个服务，对外暴露工具和资源作为工具接入
Function Calling / 工具让模型执行某个动作函数定义（名称 + 参数 schema）定义随请求发送

一个好记的说法：MCP 给 Agent 接上“手”，Skill 教 Agent“怎么用手干活”。

比如，MCP 让 Agent 能读写你的数据库；而一个“数据分析” Skill 告诉它：先看哪些表、指标口径怎么算、图表按什么规范画、结论按什么模板写。两者经常配合使用。

至于规则文件和 Skill 的分工：所有任务都要遵守的（代码风格、提交规范）放规则文件；只在特定任务中才需要的（发版流程、某类报告的写法）做成 Skill。

五、动手写一个 Skill

我们写一个“生成规范的 Git 提交信息”的 Skill。

1. 创建目录和 SKILL.md

git-commit-message/
├── SKILL.md
└── scripts/
    └── check_message.py

SKILL.md：

---
name: git-commit-message
description: 根据暂存区的改动生成符合 Conventional Commits 规范的提交信息。当用户要求提交代码、写 commit message 或整理提交记录时使用。
---

# 生成提交信息

## 步骤
1. 运行 `git diff --cached` 查看暂存区改动；如果暂存区为空，提醒用户先 `git add`。
2. 判断改动类型：feat（新功能）、fix（修复）、refactor（重构）、docs（文档）、test（测试）、chore（杂项）。
3. 按下面的格式写提交信息：
   - 第一行：`<类型>(<范围>): <简述>`，不超过 72 个字符，用祈使语气；
   - 空一行后写正文，说明**为什么**改，而不是逐行复述改了什么。
4. 运行 `python scripts/check_message.py "<提交信息>"` 校验格式，不通过就修改后重试。

## 示例
输入：修改了登录接口，令牌过期时返回 401 而不是 500。
输出：
    fix(auth): return 401 instead of 500 for expired tokens

    Expired tokens raised an unhandled error, so clients could not
    tell them apart from a server failure and never refreshed.

scripts/check_message.py：

import re
import sys

PATTERN = re.compile(r"^(feat|fix|refactor|docs|test|chore)(\([\w-]+\))?: .+")

first_line = sys.argv[1].splitlines()[0]
if not PATTERN.match(first_line):
    sys.exit("第一行格式应为：<类型>(<范围>): <简述>")
if len(first_line) > 72:
    sys.exit(f"第一行有 {len(first_line)} 个字符，超过 72 个")
print("格式正确")

注意这里的分工：“写得好不好”交给模型判断，“格式对不对”交给脚本检查。

2. 放到 Agent 能找到的位置

不同工具查找 Skill 的目录不同，以 Claude Code 为例：

  • 个人使用（所有项目可用）：~/.claude/skills/git-commit-message/
  • 项目共享（随代码提交，团队成员都能用）：项目根目录/.claude/skills/git-commit-message/

其他工具请查阅各自文档中的 skills 目录说明。由于格式是统一的，迁移时一般只需要把文件夹复制过去。

3. 校验格式

官方提供了参考校验工具 skills-ref，可以检查元数据是否合规：

skills-ref validate ./git-commit-message

之后你只要说一句“帮我提交一下”，Agent 就会自动认出这个 Skill 并按流程执行。

六、写好 Skill 的几条经验

  1. description 是重中之重。 Agent 只凭它决定要不要启用 Skill。要同时写清“做什么”和“什么时候用”，并带上用户可能说的关键词。
    • 差：description: 处理 PDF。
    • 好：description: 提取 PDF 文字和表格、填写表单、合并文件。当用户处理 PDF，或提到表单、文档提取时使用。
  2. SKILL.md 保持精简。 官方建议正文不超过 500 行、5000 tokens 以内；详细的参考资料拆到 references/ 里，在正文中用相对路径引用。
  3. 引用只嵌套一层。 从 SKILL.md 直接链接到参考文件即可，不要让参考文件再链接一串文件。
  4. 能用脚本的就别让模型“想”。 校验、转换、计算这些确定性工作写成脚本，脚本要有清晰的报错信息。
  5. 给出示例。 一个具体的输入输出例子，往往比三段抽象描述更管用。
  6. 一个 Skill 只做一件事。 “PDF 处理”和“周报生成”应该拆成两个 Skill，description 才写得准，也不会误触发。

七、安全提醒

Skill 可以包含可执行脚本，也可以通过说明文字引导 Agent 做任何事。安装一个 Skill，相当于让 Agent 按别人写的手册干活。 所以：

  • 只安装来源可信的 Skill，安装前通读 SKILL.md 和脚本；
  • 留意说明里有没有要求访问网络、读取敏感文件、执行破坏性命令；
  • 团队共享的 Skill 和代码一样走 Code Review。

总结

  • 是什么：一个带 SKILL.md 的文件夹，把某类任务的知识和流程打包给 AI Agent。
  • 怎么工作：渐进式披露——启动时只读名字和用途，用到时读说明，需要时再读资料、跑脚本。
  • 好在哪：可以装很多却几乎不占上下文；确定性的工作交给脚本；一次编写，多个 Agent 通用。
  • 和 MCP 的关系：MCP 接通外部系统，Skill 传授做事方法，两者互补。

如果你发现自己总在对 AI 重复同一套交代，不妨把它写成一个 Skill。

参考资料

  • Agent Skills 官方规范：https://agentskills.io/specification
  • Agent Skills 概览：https://agentskills.io
  • 规范与校验工具仓库：https://github.com/agentskills/agentskills
# AI # 人工智能
Logo
北京朝阳AI社区

更多推荐

上下文逼近限制时 JSON 解析突然崩塌（JSON 解析实测）

我测了 500 个 JSON 样本，上下文留 500 token 余量时只有 0.8% 解析失败；留 200 token 时失败率跳到 13%；留 100 token 时超过三成解析失败。大模型的 JSON 解析能力在上下文逼近限制时会突然崩塌，安全余量到底该留多少？

avatar 北京朝阳AI社区

你的 Agent 通过了测试，为什么一上线还是翻车？

内测里任务能跑完、工具调得对、回答也像样。但接上真实工单、真实权限、真实用户后，失败却换了形态：同样的输入这次成功下次失败，日志里没有异常堆栈，重试一遍又好了，复盘时没人能复现。团队最常做的动作是改提示词、补一句「请仔细检查」，观察两天宣布恢复，几天后换一种形式再出现。冲突不在「模型不够强」，而在：你证明的是「某个被固定住的环境里某一次任务成功」，而生产环境需要证明的是「模型、提示词、工具和上下文

avatar 北京朝阳AI社区
cover

瑞芯微RK3562核心板规格书，详细参数配置，B2B板对板连接器封装兼容树莓派CM4/CM5，SOM6208-B1

avatar 北京朝阳AI社区