智能体 Skill 教程
从入门到精通

什么是 Skill？它如何工作？

一份带 frontmatter 的 Markdown 指令文件 —— 告诉智能体“在什么场景下、怎么做、不能做什么”。

Skill = 触发条件 + 指令 + 可选工具 + 示例

它不是代码、不是 API、不是 Prompt 字符串，而是一份可被智能体加载、解析、注入上下文的“行为说明书”。如果说 Prompt 是“对话里的一句话”，那 Skill 就是“岗位说明书”——可独立存储、可版本化、可分发。

你的第一个 Skill

30 行以内，一个能跑起来的极简示例 —— 先看见它长什么样，再讲为什么。

---
name: hello-skill
description: 向用户友好地打招呼，并询问今天可以帮什么忙。
version: 1.0.0
triggers:
  - "你好"
  - "hi"
  - "在吗"
---

# 行为
当用户开启对话时：
1. 用 1-2 句中文打招呼，不夸张、不用表情包。
2. 主动列出 3 个我能帮忙的方向（代码 / 文档 / 答疑）。
3. 询问用户："今天想先做哪一件？"

# 风格
- 称呼：用"你"，不用"您"
- 长度：整段回复 ≤ 80 字
- 语气：平和、具体、像同事

# 禁止
- 不假装记得上次对话
- 不主动推荐未询问的功能
- 不输出 emoji

frontmatter 告诉系统：叫什么、什么时候用、版本号；行为段告诉模型：要做的三步；风格段约束表达方式；禁止段划出红线。

从磁盘到执行：四步加载

1. 加载 · DISCOVER运行时扫描 SKILL.md / .yaml 文件，建立元数据索引（name + description）。触发方式包括触发词匹配、语义相似度、显式调用。
2. 解析 · PARSE拆分 frontmatter（YAML）与 Markdown body，校验字段、注入默认值：name / description、version、allowed-tools、triggers。
3. 注入上下文 · INJECT把 body 内容作为系统提示的一部分送入 LLM，工具声明进入 function schema，并注入 Few-shot 示例。
4. 调用与执行 · EXECUTE模型按 Skill 指令响应用户；如需工具，调用声明中的工具并把结果回传：LLM 推理、工具执行、结果回填。

五个核心字段，五条稳定性原则

剥开一份完整的 SKILL.md，看清每个字段的位置和作用。

---
name: skill-template                 # ①
description: 一句话说清"什么时候用我"  # ②
version: 1.0.0                       # ③
triggers:
  - "写文档"
  - "整理笔记"
allowed-tools: [search_files]        # ④
model: sonnet
---

# 角色
你是一位擅长把技术笔记改成可读文档的作者。

# 步骤
1. 阅读用户提供的原始笔记
2. 按"问题 → 方案 → 示例"结构重写
3. 输出 Markdown 文档

# 示例
输入：一段混乱的会议记录
输出：结构清晰、含 TL;DR 的会议纪要

编写 Skill 的五原则

让模型“做对”比“做得多”更重要 —— 五条来自实战的稳定性法则。

1. 明确指令动词具体、范围清晰。避免“写得好一点”，改用“开头用一句话点出读者痛点”。bad: “优化一下”；good: “把第一段从陈述句改成问句”。
2. 上下文充分给齐输入样例、约束条件、预期输出。模型不是人，不知道你的“显然”。必含：输入 / 输出 / 字数 / 受众。
3. Few-shot2-3 个真实示例胜过 100 字描述。展示“目标风格”和“反例修正”各一。ex1: ✅ 标准输出；ex2: ❌→✅ 改写。
4. 错误兜底工具失败、输入缺失、模型犹豫 —— 提前定义“如果 X 怎么办”。例如：“若 fetch 失败，改用本地资料”。
5. 最小依赖工具能不加就不加。少一个工具 = 少一个失败点 = 少一份文档。默认 allowed-tools: []。

为什么 Skill 改变了 AI 应用开发？

把“AI 怎么用”从代码里剥离出来，变成可独立管理的资产。

• 可复用 · REUSE同一个 Skill 在 Claude Code、Cursor、企业内 ChatOps 中可被多次加载，无需复制粘贴 Prompt。一次编写，跨平台部署。
• 可测试 · TEST有明确的输入输出场景，可以建立回归集、跑 A/B、追踪版本间效果衰减。像代码一样有 CI。
• 可分享 · SHARE团队成员、上下游合作方可以基于同一份 Skill 协作；企业内部能积累领域知识。Git 化的知识资产。
• 可进化 · EVOLVE发现新的反例 → 写进禁止段；用户反馈好 → 沉淀为 Few-shot。Skill 越用越好。数据驱动的迭代。

Skill vs Function vs Agent

Agent 在运行时可以加载多个 Skill，Skill 可以声明自己需要哪些 Function。真实系统通常是 Agent 调度多个 Skill，Skill 调用 Function 的三层结构。

公众号文章 Skill：把个人风格沉淀为资产

一个面向中文技术作者的内容生产 Skill：结构化模板 + 风格约束 + Few-shot。

---
name: tech-wechat-writer
description: 撰写中文技术公众号文章。当用户要求"写一篇关于 X 的技术文章"时加载。
version: 1.2.0
triggers:
  - "写一篇技术文章"
  - "公众号"
  - "技术分享"
allowed-tools: [fetch_web]
---

# 角色
你是一位 10 年经验的中文技术作者，
擅长把复杂概念讲给一线工程师听。

# 文章结构（必须遵循）
1. 标题：数字 + 反差 + 悬念（≤ 20 字）
2. 引入：1 段真实场景痛点（≤ 150 字）
3. 核心：3-5 个小节，每节配 1 个代码或图示
4. 总结：1 段金句 + 行动建议

# 风格约束
- 段落 ≤ 4 行，多用短句
- 关键概念加粗，避免堆砌术语
- 字数 1500-2500 字
- 关键转折用"但是"、"其实"、"想象一下"

# 配图建议（写到正文里）
- 每节至少 1 个 [图：xxx] 占位
- 配图类型：架构图 / 时序图 / 截图 / 类比

# Few-shot 示例
## 示例 1（正面）
输入：写一篇关于 React Server Components 的文章
输出：
  标题：《RSC 让我每天少写 200 行代码》
  引入：上周重构项目，我删掉了 12 个 useState...
  核心：3 节，分别讲"为什么是组件"、"数据流变了"、"实战迁移"
  总结：把"该用什么"留给读者

## 示例 2（反面 → 修正）
错误：通篇讲 RSC 原理，无具体代码
修正：每节配 1 段真实代码，3-15 行

# 禁止
- 不编造不存在的库或 API
- 不输出 emoji
- 不用"小伙伴们"、"家人们"等口水化称呼
- 不出现"作为 AI"、"我无法"等元叙述

• 把“个人风格”沉淀成可复用资产
• 用结构模板代替反复解释
• 通过Few-shot校准语气
• 用禁止段划出红线

字段拆解与设计意图

• description用“当用户要求...时加载”句式，让 LLM 准确判断触发。
• triggers列出常见表达，避免漏触发。
• allowed-tools只声明真正用得到的（fetch_web）。
• version 1.2.0从 1.0 → 1.2 经过两轮 Few-shot 校准。

Few-shot 有两个用法：示例 1（正面）展示“理想输出”长什么样 —— 含标题、引入、核心、总结四个段落；示例 2（反面→修正）把常见的失败模式写出来，再给出修正方向。这是 Few-shot 最高级的用法。

红线必须具体。“不要写得差”是无效约束；“不出现‘家人们’”才是 LLM 能遵守的规则。

小技巧：把自己最讨厌的 5 个表达写进禁止段，比“鼓励好表达”更有效。

前端开发 Skill：工具声明 + 流程固化

用 React + Tailwind 做项目时的“规范守门员”：工具声明 + 文件结构 + 性能/a11y 检查。

---
name: react-tailwind-dev
description: 用 React + Tailwind CSS 开发前端项目。当用户请求"做一个 XX 页面/组件"时加载。
version: 2.0.0
triggers:
  - "用 React 写"
  - "前端组件"
  - "做一个 XX 页"
allowed-tools:
  - search_files
  - file_write
  - run_command
---

# 框架选型决策
- 纯前端 → Vite + React 18 + TS
- 含 SSR/SEO → Next.js 14 (App Router)
- 状态管理：默认 Zustand，复杂业务用 Redux Toolkit
- 样式：Tailwind CSS，禁用内联 style
- 包管理：pnpm

# 文件结构（强制）
src/
  components/{Name}/
    index.tsx        # 主组件，≤ 200 行
    styles.css       # 局部样式（必要时）
    types.ts         # Props 类型
    test.tsx         # 单元测试
  hooks/
  pages/ 或 app/

# 代码规范
- 组件文件 ≤ 200 行，超出要拆
- Props 必须显式 type，禁用 any
- 关键组件配 a11y 属性：aria-label / role / htmlFor
- 列表必须 key，禁用 index 作 key
- 副作用用 useEffect，依赖数组必须写全

# 工具使用顺序
1. search_files 确认现有结构，避免重复
2. file_write 写入新文件（先 types → 主组件 → test）
3. run_command 跑 pnpm test 和 pnpm lint

# 性能 / a11y 检查清单
- [ ] Lighthouse Performance ≥ 90
- [ ] 关键路径无 Layout Shift
- [ ] 键盘可访问（Tab 顺序合理）
- [ ] 屏幕阅读器朗读通顺

# 禁止
- 不用 var，统一 const / let
- 不用 ==，统一 ===
- 不在组件里写 fetch，统一放 hook
- 不提交 console.log 和 debugger

• search_files先探查后写代码。
• file_write写新文件。
• run_command跑测试和 lint。
• 选型决策树在指令里固化团队技术栈，避免每次争论。
• 文件结构强制让 AI 第一次输出就是规范的目录。
• 工具使用顺序把“先搜后写再测”流程化。
• a11y/性能清单让代码不只“能跑”还要“好用”。

与单纯 Prompt 的差异

工具声明的价值：把“思考”和“执行”分开。普通 Prompt：“帮我写个组件” → 模型编造代码；Skill + tools：模型能真去搜文件，真去写文件，真去跑测试。工具声明 = 能力边界。

文件结构强制的意义：把团队的“约定俗成”变成机器可读的规则。没有这层约束，AI 会输出各种风格：有的把所有逻辑塞一个文件；有的用 class 组件有的用 function；有的不写 test。结构强制 = 团队一致性。

a11y / 性能清单：让“质量”从“靠人 review”变成“AI 自检”。AI 写完代码后会主动按清单过一遍：“Lighthouse 分数够吗？”“键盘 Tab 顺序对吗？”“screen reader 朗读通顺吗？” Checklist = 质量门控。

AI 应用开发 Skill：阶段化的复杂工程

把“从需求到部署”的全流程装进一个 Skill：5 阶段指令 + 工具编排 + 质量门控。

---
name: ai-app-builder
description: 从零搭建 LLM 驱动的 AI 应用。当用户说"帮我做一个 AI 应用/助手/机器人"时加载。
version: 1.0.0
triggers:
  - "做一个 AI 应用"
  - "LLM 助手"
  - "智能客服/RAG/Agent"
allowed-tools:
  - search_files
  - file_write
  - run_command
  - fetch_web
---

# 5 阶段流程（严格按序）

## 阶段 1 · 需求澄清
提问用户 5 件事：
1. 目标用户是谁？解决什么场景？
2. 输入形态（文本/语音/文件）？
3. 性能预期（首响 < 2s，流式）
4. 月活 / QPS 量级？
5. 预算（元/月，含 API 成本）

## 阶段 2 · 架构选型
输出架构决策表，覆盖：
- LLM：GPT-4o / Claude Sonnet / Qwen-Long
- 向量库：pgvector / Milvus / Pinecone
- 后端：FastAPI (Python) / Hono (Node)
- 前端：Next.js / Streamlit
- 部署：Docker + 云函数 / K8s
每项给出"为什么选"的 1 句理由

## 阶段 3 · 数据流设计
画 ASCII 流程图：
用户输入 → 预处理 → 检索 → Prompt 拼装 → LLM → 后处理 → 流式输出
标注每个节点的输入/输出/超时

## 阶段 4 · 接口实现
- POST /api/chat（流式，SSE）
- POST /api/ingest（文档入库）
- GET  /api/health
- 中间件：限流 + Token 计数 + 错误兜底

## 阶段 5 · 部署监控
- Dockerfile + docker-compose.yml
- 日志：结构化 JSON，含 request_id / token 数
- 监控：首响延迟 / Token 成本 / 错误率
- 告警：成本超日预算 80% 时通知

# 工具编排顺序
1. fetch_web 调研最新 LLM / 库版本
2. search_files 确认项目结构
3. file_write 按阶段输出代码
4. run_command 跑测试 / 启服务

# 质量门控清单
- [ ] Prompt 版本可追溯（写入 git）
- [ ] 每个接口有错误路径 + 兜底文案
- [ ] Token 成本估算 < 用户预算
- [ ] 关键路径配单元测试
- [ ] 文档含本地启动 3 步

# 禁止
- 不在代码里 hardcode API key
- 不跳过需求澄清直接写代码
- 不在生产用 gpt-3.5-turbo（质量不可控）
- 不输出"完整可运行代码"占位

五阶段对应软件工程的需求 → 设计 → 实现 → 测试 → 部署。每阶段输出可验证的产物，用户能逐阶段 review。公众号 Skill 是单次调用完成；前端 Skill 是多工具协作；AI 应用 Skill 是长链路、有阶段、可暂停。这是 Skill 的最复杂形态 —— 把项目管理方法论装进指令。

阶段化设计的精髓

1. 可中断用户可在任一阶段叫停、改需求，不至于“已经写了一堆再返工”。
2. 可验证每阶段产物独立可 review，需求不跑偏。
3. 可降级用户只想做阶段 1 的需求澄清也能用。

工具顺序 fetch_web → search_files → file_write → run_command 不是随便定的：fetch_web 拿最新文档（避免用过时 API）；search_files 摸清现有项目（避免重写轮子）；file_write 才动手（基于上面两条信息）；run_command 最后验证（写完跑测试）。

安全、测试、性能：从能用到可上线

安全沙箱与权限边界

从 Skill 能写一行 fetch_web 开始，就要想清楚“它能去哪里、能改什么”。

1. L1 · 工具白名单只声明能调的工具：allowed-tools。
2. L2 · 路径白名单文件操作限定目录：fs.root。
3. L3 · 网络出站控制限制可访问的域名/IP：network.egress。
4. L4 · 运行时隔离容器 / VM / 进程级沙箱：docker / gVisor。

sandbox:
  allowed-tools: [search_files, file_write]
  fs:
    read: ["src/**", "docs/**"]
    write: ["src/**"]
  network:
    egress: ["api.github.com", "*.openai.com"]
  runtime: docker
  resource:
    cpu: 0.5
    memory: 512MB
    timeout: 30s

测试与评估体系

Skill 是文本，但文本也要有 CI —— 让“质量”从“靠感觉”变成“靠数据”。

• 单元用例单输入 → 单输出，断言关键字段。
• 回归集30-50 条历史真实请求，每版本必跑。
• LLM-as-Judge用更强的模型打分（1-5）。
• A/B 灰度线上新旧版本各 5% 流量对比。

# regression/wechat-writer.yml
cases:
  - input: "写一篇关于 RSC 的文章"
    expect:
      structure: [标题, 引入, 核心, 总结]
      length: "1500-2500 字"
      forbidden: ["家人们", "作为 AI"]
  - input: "写一篇关于 PostgreSQL 索引的文章"
    expect:
      has_code: true
      has_diagram: true

三个核心指标：通过率 ≥ 95% · 回归集命中关键断言；平均分 ≥ 4.2 · LLM-as-Judge 5 分制；Token 成本 ≤ 上版本 110% · 不显著变贵。

性能优化 · Token 经济性 · 版本管理

Skill 是会“膨胀”的资产 —— 控制好大小、版本可追溯，是企业级落地的最后一公里。SKILL.md 每次调用都会被加载到上下文，body 每 1000 字 ≈ $0.01/次。

• 精简指令去掉所有“显然”的话。
• 动态加载分主 Skill + 子 Skill，按需。
• Few-shot 压缩长示例改为短引用。
• 禁止段去重合并相似规则。

语义化版本：MAJOR · 破坏性变更（如换工具）；MINOR · 加新功能/示例；PATCH · 文案/禁止段调整。

## 1.2.0 · 2026-05-20
+ 新增 React 19 支持
~ Few-shot 示例重写

三个案例横向对比

从“会写”到“会攒”

单个 Skill 是工具，Skill 库是组织能力。

下一步：建仓 → 写 README → 接入 CI → 团队复用。

学习路径

1. 跑通第一个示例读完本文，复制 hello-skill 跑一遍。
2. 进入自己的领域改写一个自己领域的 Skill。
3. 建立评估基础建立 10 条回归集。
4. 纳入工程体系接入 git + CI。
5. 团队内灰度用真实请求检验并持续迭代。

推荐资源

• Anthropic DocsSkill 官方定义与样例
• Prompt Library50+ 公开 Skill
• Claude Code真实运行环境
• Prompt Engineering Guide方法论
• awesome-claude-skills开源集合

下一步行动

• 复制三个示例 Skill 到本地
• 写你自己的 my-skill.md
• 建 5-10 条回归集
• 配 git 仓库 + 版本号
• 分享给一个同事试用

从看见，到写出来。