企业官网建设流程全解析

什么是 Agent Skill？一篇拆完 Anthropic 的"Agent 技能"规范（附实战案例）

你会写 Prompt，会用 MCP 给 Agent 接工具，可能还写过 Cursor 插件。

但如果有人问你：“Agent Skill 是什么？和它们有什么区别？”——你能一句话说清吗？

2025 年以来，Anthropic 推的 Agent Skills 正在快速成为"给 Agent 装能力"的主流形态之一：一个文件夹、一份 Markdown、一套触发规则，就能让任何兼容的 Agent 学会一项新技能。不需要写代码，不需要调 API，写文档就是写功能。

这篇用我拆解过的一个真实开源 Skill（前文评估过的 AI 私教项目）做案例，把 Agent Skill 的规范讲透：它是什么、解决什么问题、目录怎么组织、触发规则怎么设计、渐进式披露怎么玩。

📌TL;DR 速览

• 讲什么：Agent Skill 入门——Anthropic 规范三件套（frontmatter / SKILL.md / references）+ 一个 AI 私教实战案例
• 核心结论：Skill = 用文件工程替代提示词工程——frontmatter 管"何时触发"，渐进式披露管"上下文成本"
• 三个关键数字：3 层渐进式披露 ｜ 2 类边界测试（该触发/不该触发各测）｜ 10 分钟写出最小 Skill
• 适合谁：听说过 Agent Skill 但还没动手写过自己 SKILL.md 的人

目录

• 一、30 秒看懂：Skill 是给 Agent 的"说明书 + 工具箱"
• 二、为什么需要 Skill：系统提示词的三宗罪
• 三、规范三件套：frontmatter + 正文 + 目录结构
• 四、渐进式披露：Skill 的内存管理
• 五、触发的艺术：description 里的"排除条款"
• 六、Skill vs MCP vs 系统提示词 vs 插件
• 七、动手写一个最小 Skill
• 八、安装与使用
• 九、总结

一、30 秒看懂：Skill 是给 Agent 的"说明书 + 工具箱"

一个 Agent Skill 就是一个目录（不是一个文件、不是一个服务）：

my-skill/ ├── SKILL.md # 入口：我是谁、什么时候触发、核心规则 └── references/ # 按需加载的细节（协议、模板、范例） ├── xxx-protocol.md └── examples/

Agent 启动时只看到SKILL.md的 frontmatter（元信息）；当你的话命中触发条件，它才读正文；正文里让它读哪个细节文件，它才去读哪个。内容是 Markdown，行为是协议——这就是"Markdown as Protocol"。

案例项目 tech-stack-architect-coach：用户说"我想学 Redis"，Skill 触发，一位"大厂架构师私教"上岗。整个 Skill 没有一行可执行代码，全部能力都写在 11 份 Markdown 协议里，却让模型在 11 个测试剧本下零失守（详见专栏前几篇）。

二、为什么需要 Skill：系统提示词的三宗罪

你可能会问：把这些规则直接塞进系统提示词（system prompt）不行吗？

行，但你会同时得到三个问题：

Skill 形态一次性解决三个：

• 渐进式披露：默认只加载几百字的元信息，正文和细节按需读取——上下文成本随用随付；
• frontmatter 即触发器：一段 description 同时定义"什么时候激活我"和"什么时候别激活我"；
• 文件即边界：references/里的协议只有被引用时才进入上下文，能力可以无限扩展而不涨价。

一句话：Skill 把"Agent 的能力"从提示词工程变成了文件工程——可版本管理、可单测（evals/）、可分享安装。

三、规范三件套：frontmatter + 正文 + 目录结构

3.1 frontmatter：Skill 的"门牌号"

SKILL.md顶部的 YAML 元信息，核心是name和description两个字段。看案例项目的真实写法（节选）：

---name:tech-stack-architect-coachdescription:>-当用户表达系统性学习或续接学习某个软件开发技术栈的意图时触发， 例如"我想学 Redis""系统学 Kafka""MySQL 实战""ES 面试冲刺" "想学 Vue / React / Flutter / Nginx / Dubbo / Elasticsearch"…… 不触发的情况：用户只是询问某个命令/API 的具体用法； 只问一道孤立的面试题；排查一个具体的报错或环境问题； 学习目标不是软件开发技术（如设计工具、办公软件）； 纯"继续"二字且上下文无技术栈信息……---

这段 description 是全文最贵的一百来个字，同时完成三件事：

1. 正向触发：列出"系统性学习 XX""续接学习 XX"等触发句式，覆盖后端/前端/移动端等载体；
2. 反向排除：明确写"不触发的情况"——孤立命令用法、孤立面试题、报错排查、非软件领域、无技术栈的纯"继续"；
3. 身份预告：一句话说清这个 Skill 是干嘛的，让模型触发时知道该进入什么角色。

3.2 正文：常驻层只放"角色 + 硬约束 + 入口流程"

案例项目的SKILL.md正文结构非常克制：

• 身份与教学信条：角色设定 + 核心信条（“一切脱离生产环境的命令都是纸上谈兵”）；
• 6 条硬约束（§1.1–1.6）：源码红线、术语前置、执行留痕、一轮一问、环境双红线、讲解确认——标注"不可被任何后续规则覆盖"；
• 入口流程图：诊断→模块池→协商→教学→会话管理五阶段 + 三道门禁；
• 加载地图：什么时候去读哪个协议文件（下一节细讲）；
• 开头一句醒目提示：“禁止在本文件展开教学内容”。

这个克制就是设计：常驻层是"宪法"，细节法律都在references/里按需加载。

3.3 目录结构：一个成熟 Skill 长什么样

案例项目的完整目录（略有简化）：

tech-stack-architect-coach/ ├── README.md # 给人看的项目说明 ├── skills/ │ └── tech-stack-architect-coach/ # ← 安装的就是这一层 │ ├── SKILL.md # 入口（常驻） │ └── references/ │ ├── diagnosis-protocol.md # 诊断协议 │ ├── module-pool-generation.md # ★动态模块池协议 │ ├── curriculum-negotiation-protocol.md │ ├── session-management.md # 冷启动+收尾 │ ├── teaching-confirmation-protocol.md │ ├── teaching-preferences.md │ ├── context-template.md / trace-template.md │ └── examples/ # 已填写的范例 │ ├── context-example-redis.md │ ├── trace-example-redis.md │ └── route-example-kafka.md └── evals/ ├── eval-cases.md # 评估基准：E1-E11 场景 + R1-R7 量规 └── test-report.md # 实测报告：全量 Trace 与评分

注意两点：

• SKILL.md与references/必须同级（安装时复制的是skills/<name>/这一层，不是仓库根目录——README 里专门加粗提醒）；
• 顶级带evals/：把测试基准和报告当作仓库的一等公民，这在前几篇已经证明不是形式主义。

四、渐进式披露：Skill 的内存管理

这是 Skill 规范里最核心的一条设计思想，直接看案例项目的"加载地图"：

三个层次，层层递进：

这和操作系统的按需分页是同一个思想：物理内存（上下文窗口）有限，把不马上用的页（协议细节）留在磁盘（文件系统）里，用缺页中断（加载地图）换入。一个 2 万字的 Skill，常驻成本只有几百字。

五、触发的艺术：description 里的"排除条款"

入门教程通常只教你"怎么让 Skill 被触发"，但真实世界里**"什么时候不该触发"更重要**——误触发比不触发更伤体验（用户问个命令用法，你突然启动一套教学流程？）。

案例项目把排除条款写进了 frontmatter，并且用测试守住了边界（E6/E7 两个边界场景，不触发率 100%）：

E6：孤立命令查询。学员输入"SETNX 怎么用？"

✅ 不触发。精确命中排除条款"用户只是询问某个命令/API 的具体用法"。Skill 未加载任何协议，以通用助手身份直接回答 SETNX 语法、典型用途（分布式锁）、生产注意事项（裸 SETNX 无过期有死锁风险，推荐SET key value NX EX）。

E7：非软件领域。学员输入"我想学 Photoshop 修图"

✅ 不触发。Photoshop 属"设计工具"，命中排除条款。拒答话术也很讲究：礼貌说明边界 + 一句不展开的通用建议（“从图层+蒙版+选区三件套啃起”）+ 留下回转入口（“想学前端随时来找我”）。

设计要点总结：

1. 排除条款要具体到形态（“孤立命令”“孤立面试题”“报错排查”），不要写"无关问题不触发"这种废话；
2. 排除场景也要有测试——这个项目的 E6/E7 是 11 个剧本里的 2 个，且有 pass/fail 硬性指标；
3. 边界上的拒绝话术也是 Skill 体验的一部分，值得像写功能一样写它。

六、Skill vs MCP vs 系统提示词 vs 插件

四者不是替代关系而是分层协作：系统提示词定人设，MCP 给手脚，Skill 给脑子里的方法论，插件给人的操作界面。案例项目的 Skill 甚至还规定了"什么时候不用自己"——纯查询命令让通用助手答。

七、动手写一个最小 Skill

看完规范，写一个自己的 Skill 其实 10 分钟就够。最小骨架：

code-reviewer-skill/ └── SKILL.md

--- name: code-reviewer-skill description: >- 当用户要求"帮我 review 这段代码""看看这段代码有什么问题"时触发。 不触发：用户只是询问某个 API 的用法；与代码审查无关的通用对话。 --- # 代码审查官 ## 角色 你是一位注重可维护性的资深 reviewer，只提值得提的问题，不做风格警察。 ## 硬约束 1. 每条意见必须给出：问题位置 → 为什么是问题 → 建议改法（三要素缺一不可）。 2. 禁止只写"建议优化"这类没有改法的意见。 3. 每份审查最多 5 条意见，按严重程度排序；没有 5 条就不写 5 条。 ## 流程 ① 通读代码，列出风险点 → ② 按硬约束逐条输出 → ③ 最后给一句总体判断。

把它复制到对应平台的 skills 目录（Claude Code 是.claude/skills/，Codex 是~/.codex/skills/），说一句"帮我 review 这段代码"就能触发。复杂能力再按"常驻层放硬约束，细节放 references/"的方式扩展——案例项目的 11 份协议，就是从这个骨架一路长出来的。

八、安装与使用

案例项目支持一键安装（skills.sh 生态）：

npx skillsaddJiaqiChen3518/tech-stack-architect-coach

或者手动复制到目标平台的 skills 目录：

# Claude Code 项目级 / 用户级cp-rtech-stack-architect-coach/skills/tech-stack-architect-coach /path/to/project/.claude/skills/cp-rtech-stack-architect-coach/skills/tech-stack-architect-coach ~/.claude/skills/# Codex / Cursor / 其他支持 SKILL.md 的平台cp-rtech-stack-architect-coach/skills/tech-stack-architect-coach ~/.codex/skills/

跨平台兼容性上的设计也值得抄：有文件工具的 Agent（Claude Code / Codex / Cursor）自动读写项目根目录的交接文件，学员零操作；纯对话平台自动降级为"请学员粘贴交接文档"；任何支持 system prompt 的 Agent 手动提供协议文件也能跑。核心判断：Skill 的运行时依赖只是"一个会读 Markdown 协议的 LLM Agent"——这是它相比 MCP/插件的最大传播优势。

九、总结

一句话总结：Agent Skill = 用文件工程替代提示词工程——frontmatter 解决"何时触发"，渐进式披露解决"上下文成本"，目录结构解决"能力扩展"，而质量，由你写进去的协议和配套测试决定。

📌 系列导航：AI Agent 工程实践专栏

• 第 1 篇：如何科学地评估一个 AI Agent（Skill Lift +275% 全记录）
• 第 2 篇：协议化 Prompt 设计（Markdown 硬约束）
• 第 3 篇：Agent 跨窗口状态续接（CONTEXT.md + TRACE.md 双文档模式）
• 第 4 篇：如何设计"通用型"Agent Skill（动态模块池 vs 预置内容）
• 本篇：什么是 Agent Skill？Anthropic Skills 规范拆解（入门）

你用过 Agent Skill 吗？写过自己的 SKILL.md 吗？卡在哪个环节了，评论区问我 👇 入门篇到此收工，下一篇是产品向复盘引流篇——我用第一人称复盘这个 Skill 从无到有的全过程，从"想做个私教"到"Skill Lift +275%"。欢迎点赞 + 收藏 + 关注专栏，别走丢。