你的 SKILL.md，格式对了内容废了：5 种 Skill 模式实战拆解

作者：超级猛 | 2026年5月28日 17:38 山东

---

最近在折腾 Google ADK 的 Skill 系统，发现一个很有意思的现象。 很多人已经把 SKILL.md 的格式搞清楚了——YAML frontmatter 怎么写，references/、assets/、scripts/ 三个目录怎么放。但一到真正动手写内容，就卡住了。 指令应该写成 checklist 还是 workflow？参考文件放什么？模板怎么跟指令配合？ 格式告诉你怎么打包一个 Skill，但没告诉你内容怎么设计。这是两个完全不同的问题。 这篇文章要解决的，就是第二个问题。

背景

ADK 的 SkillToolset 通过三层渐进式披露来控制 token 消耗： - L1：list_skills 只展示 Skill 名称和描述，每个约 100 token - L2：load_skill 拉取完整 SKILL.md 指令 - L3：load_skill_resource 按需加载 references/ 和 assets/ 里的文件

一个 Agent 同时挂 5 个 Skill，启动时只吃几百 token，用到哪个才加载哪个。

问题是：L2 里的内容到底该怎么写？

翻了 Claude Code 的 bundled skills、skills.sh 上的社区仓库、Vercel 和 Supabase 的官方 Skill，以及一篇 arXiv 论文（2026年2月，系统性梳理了 7 种 Skill 设计模式），发现真正在实战中反复出现的，只有这 5 种。

---

模式一：Tool Wrapper——让 Agent 秒变某个库的专家

最简单、被用得最多的模式。把某个库或框架的编码规范、最佳实践打包成一个 Skill，Agent 加载后相当于有了这个领域的专家知识。

目录结构：只用 references/，没有模板，没有脚本。

# skills/api-expert/SKILL.md
---
name: api-expert
description: FastAPI development best practices and conventions.
  Use when building, reviewing, or debugging FastAPI applications,
  REST APIs, or Pydantic models.
metadata:
  pattern: tool-wrapper
  domain: fastapi
---
You are an expert in FastAPI development.
Apply these conventions to the user's code or question.

## Core Conventions
Load 'references/conventions.md' for the complete list.

## When Reviewing Code
1. Load the conventions reference
2. Check the user's code against each convention
3. For each violation, cite the specific rule and suggest the fix

关键点： - description 字段是整个 Skill 最重要的东西——相当于 Agent 的搜索引擎索引。"Helps with APIs"几乎不会触发，"FastAPI, REST APIs, Pydantic models"匹配率就高得多。 - references/conventions.md 放具体规则（命名规范、路由定义、错误处理、async vs sync 选用指南）。

大厂实例： - Vercel 的 react-best-practices：40+ 条 React/Next.js 性能规则，按 CRITICAL → LOW 分级 - Supabase 的 supabase-postgres-best-practices：8 大类 Postgres 优化指南 - Google 的 gemini-api-dev：Gemini API 最佳实践 - Google ADK 官方的 6 个 Core Skills

什么时候用：当需要 Agent 自动遵循某个库、SDK 或内部系统的编码规范时。

---

模式二：Generator——让输出永远长一个样

Tool Wrapper 解决"输入规范"，Generator 解决"输出规范"。

核心：模板 + 风格指南。assets/ 放输出模板（结构），references/ 放风格指南（质量规则），指令层负责编排流程。

# skills/report-generator/SKILL.md
---
name: report-generator
description: Generates structured technical reports in Markdown.
  Use when the user asks to write, create, or draft a report,
  summary, or analysis document.
metadata:
  pattern: generator
  output-format: markdown
---
You are a technical report generator.
Follow these steps exactly:
Step 1: Load 'references/style-guide.md' for tone and formatting rules.
Step 2: Load 'assets/report-template.md' for the required output structure.
Step 3: Ask the user for any missing information needed to fill the template.
Step 4: Fill the template following the style guide rules.
Step 5: Return the completed report as a single Markdown document.

适用场景： - 技术报告：不管什么主题，结构永远一样 - API 文档：每个接口按同一套模板输出 - Commit 信息：强制遵循 Conventional Commits 格式 - ADK Agent 脚手架：从模板生成标准 agent.py + init.py + .env

什么时候用：当输出必须遵循固定结构、一致性比创造力更重要的时候。

---

模式三：Reviewer——让 Agent 当你的代码审查员

设计思路：把"检查什么"和"怎么检查"分开。检查清单放 references/，审查协议写进指令。换一个 checklist 文件，同一个 Skill 结构就能做完全不同的事情。

# skills/code-reviewer/SKILL.md
---
name: code-reviewer
description: Reviews Python code for quality, style, and common bugs.
  Use when the user submits code for review, asks for feedback,
  or wants a code audit.
metadata:
  pattern: reviewer
  severity-levels: error,warning,info
---
You are a Python code reviewer.
Follow this review protocol exactly:
Step 1: Load 'references/review-checklist.md' for the complete review criteria.
Step 2: Read the user's code carefully.
Step 3: Apply each rule from the checklist. For every violation:
  - Note the line number
  - Classify severity: error (must fix), warning (should fix), info (consider)
  - Explain WHY it's a problem
  - Suggest a specific fix with corrected code
Step 4: Produce structured review with Summary, Findings (grouped by severity),
       Score (1-10), and Top 3 Recommendations.

实测：写一个故意带三个 bug 的函数——PascalCase 命名、可变默认参数、裸 except: ——Agent 加载 Skill 后三个全抓出来了。

什么时候用：任何靠 checklist 做审查的场景——代码审查、安全审计、编辑审校、Agent 合规检查。

---

模式四：Inversion——让 Agent 先问清楚再动手

最容易被忽视的模式。解决 Agent 基于假设生成方案而非基于真实需求的问题。

核心：翻转对话方向——不是用户驱动，而是 Skill 驱动。Agent 通过分阶段的结构化提问收集信息，在所有问题回答完之前，绝不动手。

# skills/project-planner/SKILL.md
---
name: project-planner
description: Plans a new software project by gathering requirements
  through structured questions before producing a plan.
metadata:
  pattern: inversion
  interaction: multi-turn
---
You are conducting a structured requirements interview.
DO NOT start building or designing until all phases are complete.

## Phase 1 — Problem Discovery (ask one question at a time)
- Q1: "What problem does this project solve for its users?"
- Q2: "Who are the primary users? What is their technical level?"
- Q3: "What is the expected scale?"

## Phase 2 — Technical Constraints (only after Phase 1 is fully answered)
- Q4: "What deployment environment will you use?"
- Q5: "Do you have technology stack requirements or preferences?"
- Q6: "What are the non-negotiable requirements?"

## Phase 3 — Synthesis (only after all questions are answered)
1. Load 'assets/plan-template.md' for the output format
2. Fill in every section using the gathered requirements
3. Present the completed plan and ask for feedback

关键：DO NOT start building or designing until all phases are complete 这个 gate 是关键。Phase 1 完成才能进 Phase 2，Phase 3 只有全部问答结束后才触发。

什么时候用：任何 Agent 必须先了解上下文才能做有用工作的场景——需求收集、故障诊断、配置向导、Agent 设计前的需求访谈。

---

模式五：Pipeline——强制多步骤工作流，一步都不能跳

五个模式里最复杂的。用到了全部三个可选目录（references/、assets/、scripts/），并在步骤之间加了显式的 gate 条件。

与 Tool Wrapper 的区别：Tool Wrapper 只是加载知识，Pipeline 定义了有依赖关系的步骤序列，每一步必须完成并通过验证才能进入下一步。

# skills/doc-pipeline/SKILL.md
---
name: doc-pipeline
description: Generates API documentation from Python source code
  through a multi-step pipeline.
metadata:
  pattern: pipeline
  steps: "4"
---
You are running a documentation generation pipeline.
Execute each step in order.
Do NOT skip steps or proceed if a step fails.

## Step 1 — Parse & Inventory
Analyze the user's Python code, extract all public classes, functions, and constants.

## Step 2 — Generate Docstrings
For each function lacking a docstring:
- Load 'references/docstring-style.md'
- Generate a docstring following the style guide exactly
- Present each for user approval
Do NOT proceed to Step 3 until the user confirms.

## Step 3 — Assemble Documentation
Load 'assets/api-doc-template.md' for the output structure.

## Step 4 — Quality Check
Review against 'references/quality-checklist.md'.
Fix issues before presenting the final document.

Gate 条件是 Pipeline 的灵魂： - "Do NOT proceed to Step 3 until the user confirms"——避免未审核的 docstring 直接塞进文档 - "Do NOT skip steps or proceed if a step fails"——避免跳过验证直接出结果

什么时候用：任何步骤之间有依赖关系、跳过某一步会导致错误输出的多步骤流程——文档生成流水线、数据处理管道、部署工作流、带人工确认节点的流程。

---

五个模式怎么选？

模式	核心问题	复杂度	用了哪些目录
Tool Wrapper	Agent 需要某个库的专家知识	低	references/
Generator	输出必须遵循固定模板	中	assets/ + references/
Reviewer	代码/内容需要按 checklist 评估	中	references/
Inversion	Agent 需要先收集上下文再动手	中（多轮对话）	assets/
Pipeline	工作流有依赖步骤和验证节点	高	全部三个

经验法则： - 只改 Agent 的输入行为 → Tool Wrapper - 只改 Agent 的输出格式 → Generator - 让 Agent 评估已有内容 → Reviewer - 让 Agent 先问后做 → Inversion - 让 Agent 按流程一步步走 → Pipeline

模式可以组合

五种模式不是互斥的。生产系统里一个 Skill 通常组合 2-3 种模式。最常见的组合是 Tool Wrapper + 市场分发。

从 Tool Wrapper 开始练手是最稳的——最简单，也是被验证最多的。

多说一句

SKILL.md 的格式规范已经被 30+ 个 Agent 工具采纳——Claude Code、Gemini CLI、Cursor、GitHub Copilot 都在用。按这五种模式写的 Skill，换个 Agent 客户端照样跑。

但格式兼容只是第一步。真正决定一个 Skill 好不好用的，是内容设计。

Agent 的瓶颈早就不在模型能力上了。模型决定了上限，Skill 设计决定了你能不能摸到那个上限。