本篇章节目录：

1. 为什么需要 Skill
3. Skill 的基本结构：SKILL.md 与可选目录
4. Skill 应该放在哪里
5. 什么内容适合做成 Skill
6. 如何创建一个 Skill
7. Skill 怎么被调用的
8. Skill 的两种内容类型：参考型内容与任务型内容
9. 如何组织复杂 Skill：让 SKILL.md 保持简洁
10. Skill、Prompt、MCP 和 AGENTS.md 怎么选
11. 如何判断一个 Skill 写得好不好
12. 小结的观点是。把经验变成可调用的能力

为什么需要 Skill

痛点：团队内部的规范、经验和文档散落在各处，AI 需要一次性加载全部信息导致响应慢，且关键规则常被无关信息淹没。

一个团队里会有很多规范、经验和文档：编程规范、接口规范、合规规范、文档模板、历史踩坑记录等。

如果希望 AI 了解这些信息。最直接的做法，是把它们写进 AGENTS.md。这类比如文件会在对话开始时进入上下文，用来放项目结构。还有编码风格，再有建立命令，另外长期约定这类全局规则。

痛点：把所有内容塞进全局文件会导致上下文膨胀。查询效率下降，而且真正需要的规则不易被发现。

但如果什么都往里放，问题很快就会出现：慢是一面更麻烦的是真正相关的规则可能会被一大堆无关信息淹没。

*“每次都要重复解释相同流程”*——这正是 Skill 要解决的主要痛点。

Skill 面向的是专项能力。让 Agent 在合适的时机调用. 它把某个场景需要的流程、参考资料、模板和脚本打包成能力包：流程告诉 Agent 怎么做，参考资料和模板提供参照，脚本负责那些更适合自动化的步骤。不过，

*“经验只能一次性提示。无法复用或版本管理”*——Skill 将经验保存为可复用单元，支持维护与迁移。

*“普通文档只能人读，Agent 无法直接利用”*——Skill 把知识转化为机器可调用的格式。话说回来，

Skill 的基本结构：SKILL.md 与可选目录

A. 一个 Skill 长什么样

A Skill 是一个文件夹。必需文件只有 SKILL.md;其余目录如 /scripts/、/references/、/assets/。示例结构的观点是，

my-skill/
└── SKILL.md

my-skill/
├── SKILL.md
├── scripts/
├── references/
├── assets/
└── …怎么说呢，

B. SKILL.md 的两部分 1️⃣ Frontmatter

---
从name来看。invoice-processing
description: 用于整理发票信息、校验金额和报销规则，并生成报销材料草稿。当使用者需要处理发票或准备报销材料时使用这个 Skill。---

A 开头只需填写 name 与 description，即可快速启动。

C. 正文应该包含哪些要点

• - 分步骤操作说明；
• - 输入输出要求；
• - 常见边界情况；
• - 注意事项或禁忌；
• - 何时读取参考资料；
• - 何时调用脚本。

D. 可选目录：/scripts/ 、 /references/ 、 /assets/

• /SCRIPTS/: 存放可执行代码。
• /REFERENCES/: 存放长文本资料，如 API 文档或公司规范。说起来，
• /ASSETS/: 存放模板与静态资源。例如报告模板或表格样例，\ 这些目录不强制，仅在任务复杂度提高时逐步加入。

  Skill 应该放在哪里  💡 痛点 ：统一管理分散技能导致维护成本高 

  项目级 Skills  – 接口规范检查·数据库字段说明·发布流程·业务规则校验…使用者级 Skills  – 发票整理·会议纪要·固定写作风格·CSV 数据清洗…实现方式 : .agents/skills//SKILL .md → 客户端扫描 或者软链至各自默认目录。text project/.agents/skills//SKILL.md ~/.agents/skills//SKILL.md **Claude Code 特殊方法** text project/.claude/skills//SKILL.md ~/.claude/skills//SKILL.md **软链接示例** bash mkdir -p .claude/skills ln -s ../../.agents/skills/invoice-processing .claude/skills/invoice-processing 这样。同一套 Skill 能在多个 Agent 中复用，只维护一次。

  什么内容适合做成 Skills?⚠️ 痛点 ：滥用导致碎片化 

  ​ ​ **判断标准** ：

  * **反复出现** – 多次对话中重复解释相同规则
  * **场景明确** – 能清晰描述适用情境
  * **专属知识** – 涉及内部规范、领域术语或特定 API
  * **流程稳定** – 步骤相对固定
  * **易出错** – Agent 常犯同类错误。
  需要统一校验
  * **输出固定** – 固定结构输出
  

  * **适合自动化** – 可通过脚本完成的校验或转换 ​ ​ **不建议做成 Skills 的情形**

  * **全局规则** – 所有任务均需遵守，应放 AGENTS.md
  * **一次性需求** – 临时任务直接在对话中说明即可
  * **宽泛目标** – “写得更好”“更专业”缺乏具体场景
  

  ⚡️ 小结：只有“经常复用且场景明确”的知识才值得封装为 Skills。​ ​ ​ ​ ​ ​ ​ ​

  如何创建一个 Skills?🚀 痛点 ：从零到可用缺少步骤指引 

  *先建立最小可行版*。围绕单一明确任务，仅保留必要信息。

  手动创建步骤

  1️⃣ **确定名称** yaml 说到name，invoice-processing # 文件夹同名。短小直观 2️⃣ **撰写 Description** yaml description: 用于整理发票信息、校验金额和报销规则，并生成报销材料草稿。话说回来，当使用者需要处理发票或准备报销材料时使用这个 Skill。*描述必须回答：“它做什么？” + “何时使用，按理说，”* 3️⃣ **编写正文** 说到包括。- 必要字段列表 - 校验规则 - 异常处理策略 - 输出格式示例 markdown
  1. 确认使用者提供了哪些发票信息。
  2. 提取发票号、日期、金额等关键字段。
  3. 检查金额与日期是否异常。
  4. 如提供报销规则，则比对是否符合。其实，
  5. 输出整理后的信息 + 问题列表 + 补充需求。
  4️⃣ **试运行并迭代** 在真实对话中测试：“帮我整理这几张发票”。若未触发或结果不符，回到第 2 步调整 description 或正文。5️⃣ **逐步补充资源**
  • 常用校验脚本 → scripts/check_amount.py
  • 报销细则 → references/reimbursement-rules.md
  • 报表模板 → assets/report-template.xlsx

  使用 skill‑creator 自动搭建

  bash npx skills add https://github.com/anthropics/skills --skill skill-creator 此工具仅生成骨架，主要仍需手工完善。

  Skill 怎么被调用的  🔍 痛点 ：手动记忆触发方式繁琐 

  自动触发

  1️⃣ 发现阶段 — 客户端仅读取每个 Skill 的 name 与 description 建立轻量列表。按理说，

  2️⃣ 激活阶段 — 当使用者提出任务时大模型依据 description 判断匹配度并拉取完整 SKILL.md。

  3️⃣ 执行阶段 — Agent 按 SKILL.md 指示执行。如需参考资料则读取 references/*，若涉及脚本则调用 scripts/*。

  优势: 即使安装百个 Skills，也只占极少上下文。

  手动触发

  部分客户端提供快捷指令，例如：

  • Claude Code → /invoice-processing
  • Codex → $invoice-processing

  用于已知需要特定 Skill 时快速召唤。

  Skill 的两种内容类型：参考型 vs 任务型  📚 痛点 ：混淆背景知识与操作步骤 

  类型	解决的问题	示例	对应目录	注意事项
  参考型 内容	”、背景信息 /references/* 保存长文档	/references/reimbursement-rules.pdf …	/references/	/references/* 为纯阅读材料，不应包含执行指令
  任务型 内容	Agent 必须执行“一系列步骤”。 /scripts/* 用于自动化子任务	/scripts/check_amount.py …	/scripts/	/scripts/* 应保持幂等且易调试

  如何组织复杂 Skills —— 保持 SKILL.md 简洁  🧩 痛点 ：单文件过长导致上下文浪费 

  Main Rule: 仅在 `S K I L L . md` 中保留主要概念与关键流程，其余详尽资料拆分至对应子目录。
  官方建议控制 `S K I L L . md` 在约200行以内，一旦超限即考虑拆分。怎么说呢，

  主要内容

  • 简要用途 & 描述
  • 主执行流程
  • 调用外部资源的「何时」&「为何」说明

  长文本 → /references/

  至于例如。

  invoice-processing/ ├─ SKILL.md ← 主要原因 └─ references/ ├─ reimbursement-rules.md ← 报销细则全文 ├─ invoice-fields.pdf ← 字段解释表 └─ edge-cases.md ← 边缘案例集合

  引用方式这方面，

  步骤 3 – 校验报销规则

  请阅读 references/reimbursement-rules.md 中第 2‑5 条，以确认当前费用符合公司政策。话说回来，

  模板 & 示例 → /assets/

  invoice-processing/ └─ assets/ ├─ report-template.docx ← 最终报告格式 └─ sample-table.xlsx ← 表格样例

  自动化代码 → /scripts/

  text invoice-processing/ └─ scripts/ └─ check_amount.py ← 金额校验脚本

  使用示例

  markdown

  步骤 5 – 自动校验金额

  运行 scripts/check_amount.py 并将返回值用于后续判断。其实，

  ---

  Skill 、 Prompt 、 MCP 与 AGENTS . md 怎么选  🔧 痛点 ：概念混淆导致错误存放位置 

  AGENTS.MD全局永久配置.exampleproject 项目结构。编码风格,所有对话均生效。\ n Skill专项能力只在特定任务下激活。\ n MCP外部工具桥接当需要实时获取外部数据。\ n < tbody < table < ：将“一次性要求”="" 实现桥接。不过，<="" 放入口文件；将“重复出现且具备边界”的专属流程封装为="" 放入对话首句；将“不变全局约束”="">

  ="" ”="">
  Prompt	当前一次性需求	临时指令 — 如：“只给三条建议”。

  • \t触发准确度——是否能在正确情境下被自动召唤？• \t结果提高——输出是否更完整、更一致？• \t边界覆盖——缺失字段／异常输入能否优雅处理？• \t成本收益——额外 token 消耗是否值得质量提高？<\/ul>

  针对不同问题进行迭代：

  • \t触发不准→改 Description。• \t步骤不清→细化 SKILL.MD 正文。• \t资料冗长→搬至 References。• \t输出波动→补充示例／格式要求。• \t重复手工→抽象为 Scripts。<\/ul>

  \u201CIteration is key\u201D<\/b>\u30001.\u30009\u300B  \u300CTest in real tasks and refine continuously.\u300D<\/i>

  ---

  ---