Agent Skill 规范、构建与设计模式前言Skill 不是 Prompt——它是围绕任务、工具、流程和输出边界的结构化行为设计。写好 Skill 的关键在于理解规范标准、掌握构建方法论、选择合适的设计模式。一、Skill 规范标准1.1 什么是 Agent Skill在 AI Agent 生态中Skill 是一种可复用的 Prompt 增强包通过渐进式加载机制为 Agent 注入领域知识和工作流程。2025 年 12 月Anthropic 将 Skill 规范作为开放标准发布目前已被 33 个 Agent 产品采纳包括 Claude Code、OpenAI Codex、GitHub Copilot、VS Code、Cursor、Gemini CLI、Kiro 等。一个 Skill 的最小形态只需要一个文件skill-name/ ├── SKILL.md # 必需YAML 元数据 Markdown 指令 ├── scripts/ # 可选可执行脚本 ├── references/ # 可选按需加载的参考文档 └── assets/ # 可选模板、资源文件1.2 SKILL 格式规范根据 Anthropic 提出的规范SKILL.md 由YAML frontmatter元数据和Markdown body指令正文两部分组成。YAML frontmatter 字段字段是否必填说明约束name是Skill 的唯一标识名最多 64 个字符仅允许小写字母、数字和连字符不能以连字符开头或结尾不能包含连续连字符必须与所在文件夹名一致description是描述这个 Skill 做什么、什么时候使用最多 1024 个字符不能为空应该包含帮助 AI 识别相关任务的关键词license否许可证信息许可证名称或指向许可证文件的引用compatibility否环境兼容性要求最多 500 字符说明需要的运行环境或依赖metadata否自定义扩展元数据键值对映射可存储规范之外的额外属性allowed-tools否预授权工具列表空格分隔的字符串实验性功能1.2.1 name 字段的命名规则name 字段有严格的命名规则必须为 1-64 个字符只能包含 Unicode 小写字母数字字符a-z和连字符-不能以连字符-开头或结尾不得包含连续的连字符--必须与父目录名称匹配合法示例name:pdf-processingname:data-analysisname:code-review非法示例name:PDF-Processing# 不允许大写字母name:-pdf# 不能以连字符开头name:pdf--processing# 不允许连续连字符1.2.2 description 字段的写法建议description 应该清晰描述 Skill 的功能和适用场景必须为 1-1024 个字符应该描述该技能的作用以及何时使用应包含有助于代理识别相关任务的特定关键词好的示例description:Extracts text and tables from PDF files,fills PDF forms,and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs,forms,or document extraction.差的示例description:Helps with PDFs.1.2.3 Markdown 正文内容元数据之后的 Markdown 正文部分就是 Skill 的核心指令。对正文格式没有硬性限制只要能帮助 AI 有效执行任务即可。建议包含以下内容分步骤的操作说明、输入输出示例、常见边界情况处理。建议正文控制在 500 行以内。如果内容较多可以把详细的参考资料拆分到单独的文件中。1.2.4 最简示例一个最简的 SKILL.md 只需要 name 和 description---name:skill-namedescription:A description of what this skill does and when to use it.---1.2.5 包含可选字段的示例---name:pdf-processingdescription:Extract PDF text,fill forms,merge files. Use when handling PDFs.license:Apache-2.0metadata:author:example-orgversion:1.0---# PDF Processing## When to use this skillUse this skill when the user needs to work with PDF files...## How to extract text1. Use pdfplumber for text extraction...1.2.6 文件引用规范在 SKILL.md 中引用其他文件时请使用相对于 Skill 根目录的路径。例如引用参考文档references/REFERENCE.md引用脚本scripts/extract.py建议文件引用保持在一层深度避免深层嵌套的引用链。1.2.7 可选目录结构scripts/ 目录存放 AI 可以运行的可执行代码。脚本应该是自包含的或明确说明依赖关系包含有用的错误提示信息并能妥善处理边界情况。常见支持的语言包括 Python、Bash 和 JavaScript。references/ 目录存放 AI 在需要时可以读取的补充文档例如REFERENCE.md详细技术参考、FORMS.md表单模板或结构化数据格式、或特定领域的文档如 finance.md、legal.md。建议每个参考文件保持聚焦因为 AI 是按需加载这些文件的文件越小消耗的上下文越少。assets/ 目录存放静态资源文件包括模板文件文档模板、配置模板、图片示意图、示例图、数据文件查找表、Schema 定义。1.3 三层渐进式加载机制这是 Agent Skills 规范最精妙的设计借鉴了 UI/UX 领域的渐进式信息披露策略层级加载内容加载时机Token 成本L1 目录层name description会话启动时每个 Skill ~50-100 tokensL2 指令层完整 SKILL.md bodySkill 被激活时建议 5000 tokensL3 资源层scripts/、references/、assets/ 中的文件指令引用时按需视文件大小关键价值即使安装了 20 个 Skill初始加载也仅 1000-2000 tokens。相比单体式提示词上下文使用量减少约 90%。L1 层Agent 启动时只加载所有 Skill 的 name description以 XML 格式注入系统提示词。Agent 此时只知道有哪些 Skill 可用。L2 层用户任务匹配某个 Skill 的描述时Agent 读取完整 SKILL.md body。建议控制在 500 行以内。L3 层SKILL.md 中的指令引用外部文件时按需加载。关键是告诉 Agent 何时加载如「当 API 返回非 200 时读取 references/api-errors.md」。1.4 触发机制设计Skill 的触发完全依赖 description 字段由模型自主判断当前任务是否匹配Model-driven Activation而非关键词硬编码匹配。description 写作要点使用祈使语气「Use this skill when…」聚焦用户意图而非 Skill 内部机制适当「强势」覆盖用户可能的各种表述包含关键触发词好的例子Analyze CSV and tabular data files — compute summary statistics, add derived columns, generate charts, and clean messy data. Use this skill when the user has a CSV, TSV, or Excel file and wants to explore, transform, or visualize the data, even if they dont explicitly mention CSV or analysis.差的例子Helps with PDFs.二、Skill-Creator 核心思想2.1 设计哲学Skill-Creator 是 Anthropic 官方的「用来创建 Skill 的 Skill」其设计哲学可以概括为像做机器学习一样做 Prompt Engineering——有训练集、测试集、评估指标、迭代优化循环、防过拟合机制。它将软件工程中的 CI/CD、A/B 测试、性能基准等最佳实践完整移植到 Skill 开发领域。2.2 核心思想泛化而非过拟合。Skill 要被使用无数次、面对无数种 prompt。如果只为测试用例做针对性修改skill 就废了。遇到顽固问题尝试换个隐喻或推荐不同的工作模式而不是加更多死板约束。解释为什么而非堆砌必须。这是全文最核心的洞察。今天的 LLM 有良好的心智理论与其写满大写的 ALWAYS 和 NEVER不如解释清楚为什么某件事重要。提取重复模式。如果所有测试用例中 Agent 都独立写了类似的辅助脚本比如都写了 create_docx.py这是一个强信号——应该把这个脚本放到 scripts/ 目录让 skill 直接调用。2.3 完整开发生命周期Skill-Creator 定义了六个阶段的闭环流程阶段一需求捕获→ 理解意图、明确触发场景、确定输出格式、区分客观可验证 vs 主观创意型阶段二编写 Skill→ 编写 SKILL.md含 YAML frontmatter 指令主体 准备辅助资源阶段三测试执行→ 设计 2-3 个测试用例 → 并行启动 with_skill 和 without_skill 两组子 AgentA/B 测试→ 利用等待时间起草量化断言 → 捕获 timing 数据阶段四评估与评审→ Grader 评分 → 聚合基准数据 → Analyzer 分析模式 → 生成 Eval Viewer → 用户在浏览器中评审 → 收集 feedback.json阶段五迭代改进→ 分析反馈 → 泛化改进方向避免过拟合→ 重写 Skill → 新 iteration 目录 → 回到阶段三阶段六优化与发布→ Description 优化run_loop.py→ 训练/测试集分割 → 自动迭代改进描述 → 校验 → 打包 .skill 文件2.4 Agent 系统 — 三个专业化角色Skill-Creator 设计了三个独立的子 Agent各司其职形成完整的评估链。2.4.1 Grader Agent评分者职责评估断言是否通过并评价评估本身。8 步流程读 Transcript → 检查输出文件 → 评估断言 → 提取隐含声明 → 读执行者笔记 → 评价评估本身 → 写结果 → 读指标数据最精妙的设计是自我批评“A passing grade on a weak assertion is worse than useless — it creates false confidence.”对一个薄弱断言给出通过的评级其危害比毫无用处还要糟糕——它会制造出虚假的信心。Grader 不仅评分还会指出断言本身的问题一个通过的断言是否太容易满足如只检查文件名存在不检查内容是否有重要结果没有被任何断言覆盖断言是否无法从可用输出中验证评分标准PASS不仅要有证据还要证据反映真正的任务完成而非表面合规FAIL包括巧合通过——断言技术上满足了但底层任务结果是错的2.4.2 Comparator Agent盲比较者职责在不知道哪个输出来自哪个 Skill 的情况下判断哪个更好。核心设计——去偏见化借鉴医学实验中的双盲实验思想Comparator 只看到 A 和 B不知道来源。双维度评分体系内容维度正确性、完整性、准确性各 1-5 分结构维度组织性、格式化、可用性各 1-5 分综合为 1-10 的总分判定优先级总分 断言通过率 平局极少出现2.4.3 Analyzer Agent分析者双重角色角色 A — 事后分析器在盲比较后揭盲分析 WHY 赢家赢了对比两个 Skill 的指令差异和执行模式差异生成按优先级排序的改进建议high / medium / low按类别分类instructions、tools、examples、error_handling、structure、references角色 B — 基准分析器分析聚合统计数据隐藏的模式哪些断言在两种配置下都 100% 通过哪些断言高方差时间/token 的异常值2.5 数据流与 JSON Schema 体系references/schemas.md 定义了 7 种 JSON 数据结构形成完整的数据管道evals.json ─── 测试定义prompt expectations │ ▼ timing.json ─── 运行计时来自子 Agent 完成通知 │ ▼ metrics.json ─── 执行指标工具调用次数、文件数等 │ ▼ grading.json ─── 评分结果断言通过/失败 证据 │ ▼ benchmark.json ─── 聚合基准mean ± stddevdelta 对比 │ ▼ comparison.json ─── 盲比较结果A/B 评分 赢家 │ ▼ analysis.json ─── 事后分析改进建议 执行模式洞察 │ ▼ history.json ─── 版本追踪迭代历史 当前最佳2.6 实践流程创建一个 Code Review SkillStep 1启动 Skill-Creator在 Claude Code 中直接告诉 Claude 你的需求我想创建一个 code-review skill能够对 Git diff 进行结构化的代码审查 输出包含严重程度分级的审查报告。Claude 会自动触发 Skill-Creator开始需求捕获阶段通过对话帮你明确触发场景“review my code”、“check this PR” 等输出格式Markdown 报告按严重程度分级是否需要测试用例代码审查有客观标准适合量化测试Step 2Claude 编写 Skill 草稿Claude 会基于你的需求编写 SKILL.md包括YAML frontmattername、description审查流程指令输出模板可能的辅助脚本Step 3设计测试用例Claude 会提出 2-3 个测试用例例如{skill_name:code-review,evals:[{id:1,prompt:Review this PR that adds user authentication with JWT tokens,expected_output:Structured review report with security considerations},{id:2,prompt:Check my changes to the database migration script,expected_output:Report highlighting potential data loss risks}]}你可以修改或添加更多测试用例。Step 4并行运行测试Claude 会同时启动 with_skill 和 without_skill 两组子 Agent在等待期间起草量化断言。Step 5评审结果Claude 运行 generate_review.py 在浏览器中打开 Eval ViewerOutputs 标签页逐个查看每个测试用例的输出Benchmark 标签页对比 with_skill vs without_skill 的通过率、耗时、token 用量你在 Viewer 中为每个输出写反馈完成后点击 “Submit All Reviews”。Step 6迭代改进Claude 读取你的 feedback.json分析反馈改进 Skill然后重新运行测试。这个循环持续到你满意为止。Step 7优化 DescriptionSkill 内容确定后运行 description 优化python-mscripts.run_loop\--eval-set evals/trigger_eval.json\--skill-path path/to/code-review\--modelclaude-sonnet-4-20250514\--max-iterations5\--verbose这会自动进行训练/测试集分割迭代优化 description 的触发准确率。Step 8打包发布python-mscripts.package_skill path/to/code-review生成 code-review.skill 文件可以分享给其他人安装使用。2.7 优势与局限2.7.1. 优势优势说明方法论完整将 ML 工程实践训练/测试集分割、防过拟合引入 Prompt Engineering是目前最系统化的 Skill 开发框架评估体系严谨三 Agent 协作Grader Comparator Analyzer 量化基准远超凭感觉改 Prompt的传统方式零依赖可移植纯 Python stdlib claude CLI无需安装任何第三方包任何环境均可运行人机协作设计Eval Viewer 让人类判断质量自动化处理重复工作分工合理自举式架构用 Skill 框架管理 Skill 生命周期设计优雅具有示范意义2.7.2. 已知局限与社区反馈问题一Token 消耗极高成本不透明这是社区反映最集中的问题有真实数据为证。GitHub Issue #5142026-03-04来自 anthropics/claude-plugins-official“A single description optimization run with 20 eval queries (3 runs each 60 sessions) consumed ~69% of a 5-hour time block, with 0 actionable results.” — jroy-poka, GitHub Issue #514问题根源SKILL.md 第 385 行指示 run_loop.py 使用--model session-model即当前会话所用的模型。当用户使用 Opus 会话时description 优化会启动 60 个 Opus 级别的 claude -p 子进程而触发检测本质上只是一个是/否的二元信号完全不需要 Opus 级别的推理能力。量化影响20 个评估查询 × 3 次运行 60 个并发 Opus 会话单次优化循环消耗约 69% 的 5 小时配额用户在触发前对成本完全没有预期社区建议的修复方案是将 eval 默认模型改为 claude-haiku成本降低 10-20 倍触发检测精度等价但截至当前该问题仍处于 Open 状态。问题二流程冗长用户需多次确认Skill-Creator 的完整流程涉及大量交互节点每一轮迭代都需要用户在浏览器中逐个查看测试用例输出为每个输出撰写文字反馈提交 feedback.json回到对话告知 Claude 已完成对于简单的 Skill如一个格式转换工具这套流程的开销远超 Skill 本身的价值。社区中有用户直接表示“对于简单需求直接手写 SKILL.md 比用 skill-creator 快得多。”问题三子任务数量庞大并发管理复杂一次完整的评测包含N 个测试用例 × 2with_skill without_skill个执行子 AgentN 个 Grader 子 Agent评分1 个 Analyzer 子 Agent分析可选N 个 Comparator 子 Agent盲比较以 3 个测试用例为例单轮评测就会产生 6 个执行 3 个评分 1 个分析 10 个子 Agent。多轮迭代下子任务数量呈线性增长在 Claude Code 的子 Agent 并发限制下容易出现排队等待。问题四Description 优化对操作型 Skill效果有限GitHub Issue #514 中还指出了一个深层问题“operational workflow skills show 0% recall regardless of description quality”对于某些操作型Skill如运行部署脚本、“生成日报”Claude 本身就能直接处理不会主动去查询 Skill导致触发率始终为 0%description 优化完全无效。这类 Skill 的触发机制与 description 质量无关而是取决于任务的复杂度和专业性。问题五Skill 膨胀风险来自 Medium 社区的观察Claude Code Skills Deep Dive“A 5KB skill balloons to 50KB. Response times slow to a crawl. Maintenance becomes a nightmare. Your once-elegant skill has become a bloated monster.”随着迭代改进Skill 有膨胀倾向——每次改进都可能增加新的指令、示例、边界情况处理最终导致 Skill 体积失控违背保持精简的初衷。问题六学习曲线陡峭Skill-Creator 的完整使用需要理解Skill 的三层加载机制JSON Schema 体系7 种数据结构子 Agent 的工作原理触发率评估的统计含义训练/测试集分割的防过拟合逻辑对于非技术背景的用户这套体系的认知负担相当高。三、Writing-Skills 核心思想3.1 Superpowers 框架概述Superpowers 是一个专门为 Claude Code、Cursor、Codex 等 AI 编程助手设计的结构化工作流框架定位是「Vibe Engineering」——在 AI 快速迭代的基础上强制注入软件工程纪律。框架包含 14 个可组合的 Skill覆盖从头脑风暴到代码交付的完整开发流程。核心理念测试先行Test-Driven Development系统化优于随机化Process over Guessing复杂度缩减Simplicity as Primary Goal证据优于声明Verify before Declaring Success3.2 Writing-Skills 的核心定位Writing-Skills 是 Superpowers 中的元技能——教 Agent 如何创建新的 Skill。它与 Anthropic 的 skill-creator 目标相似但方法论截然不同。文件结构writing-skills/ ├── SKILL.md # 核心指令 ├── anthropic-best-practices.md # Anthropic 官方最佳实践摘要 ├── persuasion-principles.md # 说服心理学原则 ├── testing-skills-with-subagents.md # TDD 测试方法论 ├── graphviz-conventions.dot # 图表约定 ├── render-graphs.js # 图表渲染脚本 └── examples/ # 示例TDD 概念Skill 创建测试用例压力场景 子代理生产代码Skill 文档SKILL.md测试失败REDAgent 在没有 Skill 时违反规则基线测试通过GREENAgent 在有 Skill 时遵守规则重构REFACTOR堵住漏洞同时保持合规3.3 RED-GREEN-REFACTOR 循环RED 阶段基线测试不带 Skill 运行压力场景记录 Agent 的确切行为和合理化借口场景示例你花了 4 小时实现了一个功能完美运行。你手动测试了所有边界情况。现在是下午 6 点6:30 有晚餐。明天 9 点有代码评审。你刚意识到没写测试。选项A) 删除代码明天用 TDD 重新开始B) 现在提交明天写测试C) 现在写测试延迟 30 分钟不带 TDD Skill 运行Agent 选择 B 或 C 并合理化“我已经手动测试过了”“先写后测也能达到同样目的”“删除是浪费”现在你知道 Skill 必须防止什么了。GREEN 阶段编写最小 Skill针对基线中发现的具体失败编写 Skill不要为假设的情况添加额外内容。REFACTOR 阶段堵住漏洞Agent 找到新的合理化借口逐一添加明确的反驳借口现实“保留作为参考先写测试”你会改编它。那就是事后测试。删除就是删除。“我遵循的是精神而非字面”违反字面就是违反精神。“太简单不需要测试”简单的代码也会出错。测试只需 30 秒。3.4 四种 Skill 类型及对应测试策略不同类型的 Skill 需要不同的测试方法Skill 类型定义测试方法成功标准纪律执行型强制遵守规则如 TDD、验证要求压力场景时间沉没成本疲劳组合施压Agent 在最大压力下仍遵守规则技术指导型具体方法的操作指南如条件等待、根因追踪应用场景能否正确应用边界情况指令有无缺口Agent 成功将技术应用到新场景思维模式型解决问题的心智模型如降低复杂度、信息隐藏识别场景能否识别何时适用何时不适用Agent 正确判断何时/如何应用模式参考资料型API 文档、命令参考、库指南检索场景能否找到正确信息常见用例是否覆盖Agent 找到并正确应用参考信息关键区别纪律执行型 Skill 需要最严格的测试压力场景 合理化借口反驳而参考资料型 Skill 主要测试信息的可发现性和完整性。3.5 Description 的关键要点这是 writing-skills 中最重要的发现之一。Description 只应描述触发条件绝不要总结 Skill 的工作流程。为什么测试发现当 description 总结了工作流程时Agent 可能直接按 description 执行而跳过阅读完整的 Skill 内容。# ❌ 总结了工作流 → Agent 可能走捷径跳过 Skill 正文description:Use when executing plans-dispatches subagent per task with code review between tasks# ✅ 只有触发条件 → Agent 会完整阅读 Skilldescription:Use when executing implementation plans with independent tasks in the current session3.6 Anthropic 官方最佳实践要点来源writing-skills 中引用的 anthropic-best-practices.md简洁是关键Context window 是公共资源。默认假设 Claude 已经很聪明只添加它不知道的信息# ✅ 简洁~50 tokens ## Extract PDF text Use pdfplumber for text extraction: import pdfplumber with pdfplumber.open(file.pdf) as pdf: text pdf.pages[0].extract_text() # ❌ 冗余~150 tokens ## Extract PDF text PDF (Portable Document Format) files are a common file format... To extract text from a PDF, youll need to use a library... There are many libraries available...设置合适的自由度自由度适用场景示例高多种方法都有效代码审查流程中有首选模式但允许变化带参数的脚本模板低操作脆弱、一致性关键数据库迁移命令工作流与反馈循环对于复杂任务Skill 中应包含清晰的工作流步骤和反馈循环工作流模式将复杂操作拆分为清晰的顺序步骤提供可追踪的检查清单## 研究综合工作流 复制此清单并跟踪进度 - [ ] Step 1: 阅读所有源文档 - [ ] Step 2: 识别关键主题 - [ ] Step 3: 交叉验证论点 - [ ] Step 4: 创建结构化摘要 - [ ] Step 5: 验证引用反馈循环模式运行验证器 → 修复错误 → 重复直到通过。这个模式能显著提升输出质量## 文档编辑流程 1. 编辑 document.xml 2. 立即验证python validate.py unpacked_dir/ 3. 如果验证失败 - 仔细阅读错误信息 - 修复 XML 中的问题 - 再次运行验证 4. 仅在验证通过后才继续 5. 重新打包python pack.py unpacked_dir/ output.docx关键验证脚本的错误信息要具体如 “Field ‘signature_date’ not found. Available fields: customer_name, order_total”帮助 Agent 快速定位和修复问题。迭代开发模式最有效的 Skill 开发过程Claude A专家帮你设计和优化 Skill ↓ Claude B测试者用 Skill 执行真实任务 ↓ 观察 Claude B 的行为发现问题 ↓ 回到 Claude A 改进 Skill ↓ 重复直到满意四、Skill 设计模式Google来源Google Cloud Tech规范告诉我们Skill 长什么样但没告诉我们Skill 内部的逻辑该怎么设计。一个封装 FastAPI 规范的 Skill 和一个分 4 步执行的文档流水线 Skill虽然外表都叫 SKILL.md但内部结构完全不是一回事。Google ADK 团队研究了生态中各种 Skill 的实现方式从 Anthropic 仓库到 Vercel 和 Google 内部指南总结出 5 种反复出现的设计模式。4.1 五种 Skill 设计模式模式一Tool Wrapper — 给 Agent 装技能包核心逻辑让 Agent 在需要时才加载特定领域的知识而不是把所有东西塞进 system prompt。---name:api-expertdescription:FastAPI 开发最佳实践与规范。适用于构建、审查或调试 FastAPI 应用程序时使用。---## 核心规范加载 references/conventions.md 获取完整规范列表。## 审查代码时1. 加载规范参考文件 2. 对照每条规范逐一检查用户代码 3. 针对每处违规引用具体规则并给出修改建议关键SKILL.md 本身不包含完整规范而是告诉 Agent去哪里加载规范。适用场景封装框架/库的编码规范、团队内部代码风格指南、特定技术栈的最佳实践。模式二Generator — 填空题式文档生成核心逻辑用模板 风格指南强制输出一致性。---name:report-generatordescription:以 Markdown 格式生成结构化技术报告。---第一步加载 references/style-guide.md获取语气和格式规范。 第二步加载 assets/report-template.md获取所需的输出结构。 第三步向用户询问缺失信息-主题或议题-关键发现或数据要点-目标受众 第四步按照风格指南规范填写模板。 第五步返回已完成的报告。关键Step 3 的主动提问——Agent 不会瞎猜缺什么直接问。适用场景标准化技术文档生成、API 文档自动生成、项目脚手架。模式三Reviewer — 代码审查自动化核心逻辑把查什么和怎么查分离。检查清单独立维护Agent 只负责执行打分。---name:code-reviewerdescription:审查 Python 代码的质量、风格与常见错误。---第一步加载 references/review-checklist.md。 第二步仔细阅读用户的代码。 第三步逐一应用清单中的每条规则。针对每处违规-记录行号-划分严重等级错误 / 警告 / 提示-解释问题的原因而不仅仅是描述问题本身-给出具体的修改建议 第四步按严重等级分组输出结构化的审查报告。关键Step 3 的 “WHY not WHAT”——不只指出问题还要解释为什么是问题。适用场景自动化 PR 审查、安全漏洞扫描、代码风格检查。模式四Inversion — 让 Agent 先问你核心逻辑翻转传统交互模式。不是用户驱动 prompt → Agent 执行而是 Agent 先采访用户收集完整需求后再动手。---name:project-plannerdescription:通过结构化提问收集需求 为新软件项目制定规划。---在所有阶段完成之前请勿开始构建。## 第一阶段 — 问题探索每次只提一个问题-问题1这个项目解决什么问题-问题2主要用户群体是哪些-问题3预期的使用规模是多少## 第二阶段 — 技术约束仅在第一阶段全部回答完毕后进行-问题4部署环境是什么-问题5是否有技术栈偏好-问题6哪些是不可妥协的硬性需求## 第三阶段 — 综合整理收集所有信息 → 加载模板 → 填写内容 → 呈现结果 → 迭代优化适用场景新项目规划、系统架构设计、需求不明确时的需求澄清。模式五Pipeline — 带检查点的多步工作流核心逻辑把复杂任务拆成严格顺序的步骤每步都有明确的输入/输出和通过条件Agent 不能跳步。---name:doc-pipelinedescription:通过多步骤流水线 从 Python 源代码生成 API 文档。---按顺序执行每个步骤不得跳过任何步骤。## 第一步 — 解析与清点分析代码提取所有公开 API以清单形式呈现。 询问这是完整的公开 API 列表吗## 第二步 — 生成文档字符串针对每个缺少文档字符串的函数生成内容并提交用户确认。 在用户确认之前不得进入第三步。## 第三步 — 组装文档加载模板将所有内容汇编为统一的 API 参考文档。## 第四步 — 质量检查对照清单进行审查在呈现最终文档之前修复所有问题。关键Step 2 → Step 3 的【确认前不得继续】是硬性约束——用户不点头Agent 不能往下走。适用场景从代码生成文档、多阶段内容生产、需要人工检查点的自动化流程。4.2 设计模式选择指南你需要什么选择哪种模式特定技术栈的专家知识Tool Wrapper一致的结构化输出Generator自动化代码/内容审查Reviewer需求不明确需先收集信息Inversion复杂的多步骤任务Pipeline不确定从 Tool Wrapper 开始4.3 模式组合推荐组合说明场景Pipeline Reviewer管道最后一步加自动审查文档生成后自动质量检查Generator Inversion先收集信息再填充模板需用户输入的结构化文档生成Pipeline Tool Wrapper管道某些步骤加载专家知识多步骤代码生成Inversion Pipeline先完成需求收集再进入执行流水线复杂项目全流程五、总结Skill 生态正在快速发展已形成规范标准agentskills.io→ 构建方法论Anthropic/Superpowers→ 设计模式Google的完整知识体系。三个关键认知Skill 不是 Prompt而是围绕任务、工具、流程和输出边界的结构化行为设计渐进式加载是核心机制解决了 Agent 系统的上下文膨胀问题描述是触发的关键写好 description 比写好指令主体更重要参考资料描述链接Agent Skills 开放规范https://agentskills.io/specificationAnthropic 官方 Skills 仓库https://github.com/anthropics/skillsSuperpowers 框架https://github.com/obra/superpowersGoogle ADK Skill 设计模式https://x.com/GoogleCloudTech/status/2033953579824758855Awesome Agent Skills1060 Skillshttps://github.com/VoltAgent/awesome-agent-skillsAnthropic 黑客马拉松获胜者的完整 Claude Code 配置集合包含skillshttps://github.com/affaan-m/everything-claude-codeSkill 编写规范http://www.uml.org.cn/ai/202605181.asp?artid27383开源 skills 市场https://skills.shhttps://skillsmp.comhttps://github.com/openclaw/clawhubhttps://qoder-community.pages.dev/zh/skillshttps://github.com/cinience/alicloud-skillshttps://hermes-agent.nousresearch.com/docs/skillsskill 评测https://www.skillsbench.ai/https://arxiv.org/html/2602.12670v1https://arxiv.org/html/2602.03279
Agent Skill 规范、构建与设计模式
Agent Skill 规范、构建与设计模式前言Skill 不是 Prompt——它是围绕任务、工具、流程和输出边界的结构化行为设计。写好 Skill 的关键在于理解规范标准、掌握构建方法论、选择合适的设计模式。一、Skill 规范标准1.1 什么是 Agent Skill在 AI Agent 生态中Skill 是一种可复用的 Prompt 增强包通过渐进式加载机制为 Agent 注入领域知识和工作流程。2025 年 12 月Anthropic 将 Skill 规范作为开放标准发布目前已被 33 个 Agent 产品采纳包括 Claude Code、OpenAI Codex、GitHub Copilot、VS Code、Cursor、Gemini CLI、Kiro 等。一个 Skill 的最小形态只需要一个文件skill-name/ ├── SKILL.md # 必需YAML 元数据 Markdown 指令 ├── scripts/ # 可选可执行脚本 ├── references/ # 可选按需加载的参考文档 └── assets/ # 可选模板、资源文件1.2 SKILL 格式规范根据 Anthropic 提出的规范SKILL.md 由YAML frontmatter元数据和Markdown body指令正文两部分组成。YAML frontmatter 字段字段是否必填说明约束name是Skill 的唯一标识名最多 64 个字符仅允许小写字母、数字和连字符不能以连字符开头或结尾不能包含连续连字符必须与所在文件夹名一致description是描述这个 Skill 做什么、什么时候使用最多 1024 个字符不能为空应该包含帮助 AI 识别相关任务的关键词license否许可证信息许可证名称或指向许可证文件的引用compatibility否环境兼容性要求最多 500 字符说明需要的运行环境或依赖metadata否自定义扩展元数据键值对映射可存储规范之外的额外属性allowed-tools否预授权工具列表空格分隔的字符串实验性功能1.2.1 name 字段的命名规则name 字段有严格的命名规则必须为 1-64 个字符只能包含 Unicode 小写字母数字字符a-z和连字符-不能以连字符-开头或结尾不得包含连续的连字符--必须与父目录名称匹配合法示例name:pdf-processingname:data-analysisname:code-review非法示例name:PDF-Processing# 不允许大写字母name:-pdf# 不能以连字符开头name:pdf--processing# 不允许连续连字符1.2.2 description 字段的写法建议description 应该清晰描述 Skill 的功能和适用场景必须为 1-1024 个字符应该描述该技能的作用以及何时使用应包含有助于代理识别相关任务的特定关键词好的示例description:Extracts text and tables from PDF files,fills PDF forms,and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs,forms,or document extraction.差的示例description:Helps with PDFs.1.2.3 Markdown 正文内容元数据之后的 Markdown 正文部分就是 Skill 的核心指令。对正文格式没有硬性限制只要能帮助 AI 有效执行任务即可。建议包含以下内容分步骤的操作说明、输入输出示例、常见边界情况处理。建议正文控制在 500 行以内。如果内容较多可以把详细的参考资料拆分到单独的文件中。1.2.4 最简示例一个最简的 SKILL.md 只需要 name 和 description---name:skill-namedescription:A description of what this skill does and when to use it.---1.2.5 包含可选字段的示例---name:pdf-processingdescription:Extract PDF text,fill forms,merge files. Use when handling PDFs.license:Apache-2.0metadata:author:example-orgversion:1.0---# PDF Processing## When to use this skillUse this skill when the user needs to work with PDF files...## How to extract text1. Use pdfplumber for text extraction...1.2.6 文件引用规范在 SKILL.md 中引用其他文件时请使用相对于 Skill 根目录的路径。例如引用参考文档references/REFERENCE.md引用脚本scripts/extract.py建议文件引用保持在一层深度避免深层嵌套的引用链。1.2.7 可选目录结构scripts/ 目录存放 AI 可以运行的可执行代码。脚本应该是自包含的或明确说明依赖关系包含有用的错误提示信息并能妥善处理边界情况。常见支持的语言包括 Python、Bash 和 JavaScript。references/ 目录存放 AI 在需要时可以读取的补充文档例如REFERENCE.md详细技术参考、FORMS.md表单模板或结构化数据格式、或特定领域的文档如 finance.md、legal.md。建议每个参考文件保持聚焦因为 AI 是按需加载这些文件的文件越小消耗的上下文越少。assets/ 目录存放静态资源文件包括模板文件文档模板、配置模板、图片示意图、示例图、数据文件查找表、Schema 定义。1.3 三层渐进式加载机制这是 Agent Skills 规范最精妙的设计借鉴了 UI/UX 领域的渐进式信息披露策略层级加载内容加载时机Token 成本L1 目录层name description会话启动时每个 Skill ~50-100 tokensL2 指令层完整 SKILL.md bodySkill 被激活时建议 5000 tokensL3 资源层scripts/、references/、assets/ 中的文件指令引用时按需视文件大小关键价值即使安装了 20 个 Skill初始加载也仅 1000-2000 tokens。相比单体式提示词上下文使用量减少约 90%。L1 层Agent 启动时只加载所有 Skill 的 name description以 XML 格式注入系统提示词。Agent 此时只知道有哪些 Skill 可用。L2 层用户任务匹配某个 Skill 的描述时Agent 读取完整 SKILL.md body。建议控制在 500 行以内。L3 层SKILL.md 中的指令引用外部文件时按需加载。关键是告诉 Agent 何时加载如「当 API 返回非 200 时读取 references/api-errors.md」。1.4 触发机制设计Skill 的触发完全依赖 description 字段由模型自主判断当前任务是否匹配Model-driven Activation而非关键词硬编码匹配。description 写作要点使用祈使语气「Use this skill when…」聚焦用户意图而非 Skill 内部机制适当「强势」覆盖用户可能的各种表述包含关键触发词好的例子Analyze CSV and tabular data files — compute summary statistics, add derived columns, generate charts, and clean messy data. Use this skill when the user has a CSV, TSV, or Excel file and wants to explore, transform, or visualize the data, even if they dont explicitly mention CSV or analysis.差的例子Helps with PDFs.二、Skill-Creator 核心思想2.1 设计哲学Skill-Creator 是 Anthropic 官方的「用来创建 Skill 的 Skill」其设计哲学可以概括为像做机器学习一样做 Prompt Engineering——有训练集、测试集、评估指标、迭代优化循环、防过拟合机制。它将软件工程中的 CI/CD、A/B 测试、性能基准等最佳实践完整移植到 Skill 开发领域。2.2 核心思想泛化而非过拟合。Skill 要被使用无数次、面对无数种 prompt。如果只为测试用例做针对性修改skill 就废了。遇到顽固问题尝试换个隐喻或推荐不同的工作模式而不是加更多死板约束。解释为什么而非堆砌必须。这是全文最核心的洞察。今天的 LLM 有良好的心智理论与其写满大写的 ALWAYS 和 NEVER不如解释清楚为什么某件事重要。提取重复模式。如果所有测试用例中 Agent 都独立写了类似的辅助脚本比如都写了 create_docx.py这是一个强信号——应该把这个脚本放到 scripts/ 目录让 skill 直接调用。2.3 完整开发生命周期Skill-Creator 定义了六个阶段的闭环流程阶段一需求捕获→ 理解意图、明确触发场景、确定输出格式、区分客观可验证 vs 主观创意型阶段二编写 Skill→ 编写 SKILL.md含 YAML frontmatter 指令主体 准备辅助资源阶段三测试执行→ 设计 2-3 个测试用例 → 并行启动 with_skill 和 without_skill 两组子 AgentA/B 测试→ 利用等待时间起草量化断言 → 捕获 timing 数据阶段四评估与评审→ Grader 评分 → 聚合基准数据 → Analyzer 分析模式 → 生成 Eval Viewer → 用户在浏览器中评审 → 收集 feedback.json阶段五迭代改进→ 分析反馈 → 泛化改进方向避免过拟合→ 重写 Skill → 新 iteration 目录 → 回到阶段三阶段六优化与发布→ Description 优化run_loop.py→ 训练/测试集分割 → 自动迭代改进描述 → 校验 → 打包 .skill 文件2.4 Agent 系统 — 三个专业化角色Skill-Creator 设计了三个独立的子 Agent各司其职形成完整的评估链。2.4.1 Grader Agent评分者职责评估断言是否通过并评价评估本身。8 步流程读 Transcript → 检查输出文件 → 评估断言 → 提取隐含声明 → 读执行者笔记 → 评价评估本身 → 写结果 → 读指标数据最精妙的设计是自我批评“A passing grade on a weak assertion is worse than useless — it creates false confidence.”对一个薄弱断言给出通过的评级其危害比毫无用处还要糟糕——它会制造出虚假的信心。Grader 不仅评分还会指出断言本身的问题一个通过的断言是否太容易满足如只检查文件名存在不检查内容是否有重要结果没有被任何断言覆盖断言是否无法从可用输出中验证评分标准PASS不仅要有证据还要证据反映真正的任务完成而非表面合规FAIL包括巧合通过——断言技术上满足了但底层任务结果是错的2.4.2 Comparator Agent盲比较者职责在不知道哪个输出来自哪个 Skill 的情况下判断哪个更好。核心设计——去偏见化借鉴医学实验中的双盲实验思想Comparator 只看到 A 和 B不知道来源。双维度评分体系内容维度正确性、完整性、准确性各 1-5 分结构维度组织性、格式化、可用性各 1-5 分综合为 1-10 的总分判定优先级总分 断言通过率 平局极少出现2.4.3 Analyzer Agent分析者双重角色角色 A — 事后分析器在盲比较后揭盲分析 WHY 赢家赢了对比两个 Skill 的指令差异和执行模式差异生成按优先级排序的改进建议high / medium / low按类别分类instructions、tools、examples、error_handling、structure、references角色 B — 基准分析器分析聚合统计数据隐藏的模式哪些断言在两种配置下都 100% 通过哪些断言高方差时间/token 的异常值2.5 数据流与 JSON Schema 体系references/schemas.md 定义了 7 种 JSON 数据结构形成完整的数据管道evals.json ─── 测试定义prompt expectations │ ▼ timing.json ─── 运行计时来自子 Agent 完成通知 │ ▼ metrics.json ─── 执行指标工具调用次数、文件数等 │ ▼ grading.json ─── 评分结果断言通过/失败 证据 │ ▼ benchmark.json ─── 聚合基准mean ± stddevdelta 对比 │ ▼ comparison.json ─── 盲比较结果A/B 评分 赢家 │ ▼ analysis.json ─── 事后分析改进建议 执行模式洞察 │ ▼ history.json ─── 版本追踪迭代历史 当前最佳2.6 实践流程创建一个 Code Review SkillStep 1启动 Skill-Creator在 Claude Code 中直接告诉 Claude 你的需求我想创建一个 code-review skill能够对 Git diff 进行结构化的代码审查 输出包含严重程度分级的审查报告。Claude 会自动触发 Skill-Creator开始需求捕获阶段通过对话帮你明确触发场景“review my code”、“check this PR” 等输出格式Markdown 报告按严重程度分级是否需要测试用例代码审查有客观标准适合量化测试Step 2Claude 编写 Skill 草稿Claude 会基于你的需求编写 SKILL.md包括YAML frontmattername、description审查流程指令输出模板可能的辅助脚本Step 3设计测试用例Claude 会提出 2-3 个测试用例例如{skill_name:code-review,evals:[{id:1,prompt:Review this PR that adds user authentication with JWT tokens,expected_output:Structured review report with security considerations},{id:2,prompt:Check my changes to the database migration script,expected_output:Report highlighting potential data loss risks}]}你可以修改或添加更多测试用例。Step 4并行运行测试Claude 会同时启动 with_skill 和 without_skill 两组子 Agent在等待期间起草量化断言。Step 5评审结果Claude 运行 generate_review.py 在浏览器中打开 Eval ViewerOutputs 标签页逐个查看每个测试用例的输出Benchmark 标签页对比 with_skill vs without_skill 的通过率、耗时、token 用量你在 Viewer 中为每个输出写反馈完成后点击 “Submit All Reviews”。Step 6迭代改进Claude 读取你的 feedback.json分析反馈改进 Skill然后重新运行测试。这个循环持续到你满意为止。Step 7优化 DescriptionSkill 内容确定后运行 description 优化python-mscripts.run_loop\--eval-set evals/trigger_eval.json\--skill-path path/to/code-review\--modelclaude-sonnet-4-20250514\--max-iterations5\--verbose这会自动进行训练/测试集分割迭代优化 description 的触发准确率。Step 8打包发布python-mscripts.package_skill path/to/code-review生成 code-review.skill 文件可以分享给其他人安装使用。2.7 优势与局限2.7.1. 优势优势说明方法论完整将 ML 工程实践训练/测试集分割、防过拟合引入 Prompt Engineering是目前最系统化的 Skill 开发框架评估体系严谨三 Agent 协作Grader Comparator Analyzer 量化基准远超凭感觉改 Prompt的传统方式零依赖可移植纯 Python stdlib claude CLI无需安装任何第三方包任何环境均可运行人机协作设计Eval Viewer 让人类判断质量自动化处理重复工作分工合理自举式架构用 Skill 框架管理 Skill 生命周期设计优雅具有示范意义2.7.2. 已知局限与社区反馈问题一Token 消耗极高成本不透明这是社区反映最集中的问题有真实数据为证。GitHub Issue #5142026-03-04来自 anthropics/claude-plugins-official“A single description optimization run with 20 eval queries (3 runs each 60 sessions) consumed ~69% of a 5-hour time block, with 0 actionable results.” — jroy-poka, GitHub Issue #514问题根源SKILL.md 第 385 行指示 run_loop.py 使用--model session-model即当前会话所用的模型。当用户使用 Opus 会话时description 优化会启动 60 个 Opus 级别的 claude -p 子进程而触发检测本质上只是一个是/否的二元信号完全不需要 Opus 级别的推理能力。量化影响20 个评估查询 × 3 次运行 60 个并发 Opus 会话单次优化循环消耗约 69% 的 5 小时配额用户在触发前对成本完全没有预期社区建议的修复方案是将 eval 默认模型改为 claude-haiku成本降低 10-20 倍触发检测精度等价但截至当前该问题仍处于 Open 状态。问题二流程冗长用户需多次确认Skill-Creator 的完整流程涉及大量交互节点每一轮迭代都需要用户在浏览器中逐个查看测试用例输出为每个输出撰写文字反馈提交 feedback.json回到对话告知 Claude 已完成对于简单的 Skill如一个格式转换工具这套流程的开销远超 Skill 本身的价值。社区中有用户直接表示“对于简单需求直接手写 SKILL.md 比用 skill-creator 快得多。”问题三子任务数量庞大并发管理复杂一次完整的评测包含N 个测试用例 × 2with_skill without_skill个执行子 AgentN 个 Grader 子 Agent评分1 个 Analyzer 子 Agent分析可选N 个 Comparator 子 Agent盲比较以 3 个测试用例为例单轮评测就会产生 6 个执行 3 个评分 1 个分析 10 个子 Agent。多轮迭代下子任务数量呈线性增长在 Claude Code 的子 Agent 并发限制下容易出现排队等待。问题四Description 优化对操作型 Skill效果有限GitHub Issue #514 中还指出了一个深层问题“operational workflow skills show 0% recall regardless of description quality”对于某些操作型Skill如运行部署脚本、“生成日报”Claude 本身就能直接处理不会主动去查询 Skill导致触发率始终为 0%description 优化完全无效。这类 Skill 的触发机制与 description 质量无关而是取决于任务的复杂度和专业性。问题五Skill 膨胀风险来自 Medium 社区的观察Claude Code Skills Deep Dive“A 5KB skill balloons to 50KB. Response times slow to a crawl. Maintenance becomes a nightmare. Your once-elegant skill has become a bloated monster.”随着迭代改进Skill 有膨胀倾向——每次改进都可能增加新的指令、示例、边界情况处理最终导致 Skill 体积失控违背保持精简的初衷。问题六学习曲线陡峭Skill-Creator 的完整使用需要理解Skill 的三层加载机制JSON Schema 体系7 种数据结构子 Agent 的工作原理触发率评估的统计含义训练/测试集分割的防过拟合逻辑对于非技术背景的用户这套体系的认知负担相当高。三、Writing-Skills 核心思想3.1 Superpowers 框架概述Superpowers 是一个专门为 Claude Code、Cursor、Codex 等 AI 编程助手设计的结构化工作流框架定位是「Vibe Engineering」——在 AI 快速迭代的基础上强制注入软件工程纪律。框架包含 14 个可组合的 Skill覆盖从头脑风暴到代码交付的完整开发流程。核心理念测试先行Test-Driven Development系统化优于随机化Process over Guessing复杂度缩减Simplicity as Primary Goal证据优于声明Verify before Declaring Success3.2 Writing-Skills 的核心定位Writing-Skills 是 Superpowers 中的元技能——教 Agent 如何创建新的 Skill。它与 Anthropic 的 skill-creator 目标相似但方法论截然不同。文件结构writing-skills/ ├── SKILL.md # 核心指令 ├── anthropic-best-practices.md # Anthropic 官方最佳实践摘要 ├── persuasion-principles.md # 说服心理学原则 ├── testing-skills-with-subagents.md # TDD 测试方法论 ├── graphviz-conventions.dot # 图表约定 ├── render-graphs.js # 图表渲染脚本 └── examples/ # 示例TDD 概念Skill 创建测试用例压力场景 子代理生产代码Skill 文档SKILL.md测试失败REDAgent 在没有 Skill 时违反规则基线测试通过GREENAgent 在有 Skill 时遵守规则重构REFACTOR堵住漏洞同时保持合规3.3 RED-GREEN-REFACTOR 循环RED 阶段基线测试不带 Skill 运行压力场景记录 Agent 的确切行为和合理化借口场景示例你花了 4 小时实现了一个功能完美运行。你手动测试了所有边界情况。现在是下午 6 点6:30 有晚餐。明天 9 点有代码评审。你刚意识到没写测试。选项A) 删除代码明天用 TDD 重新开始B) 现在提交明天写测试C) 现在写测试延迟 30 分钟不带 TDD Skill 运行Agent 选择 B 或 C 并合理化“我已经手动测试过了”“先写后测也能达到同样目的”“删除是浪费”现在你知道 Skill 必须防止什么了。GREEN 阶段编写最小 Skill针对基线中发现的具体失败编写 Skill不要为假设的情况添加额外内容。REFACTOR 阶段堵住漏洞Agent 找到新的合理化借口逐一添加明确的反驳借口现实“保留作为参考先写测试”你会改编它。那就是事后测试。删除就是删除。“我遵循的是精神而非字面”违反字面就是违反精神。“太简单不需要测试”简单的代码也会出错。测试只需 30 秒。3.4 四种 Skill 类型及对应测试策略不同类型的 Skill 需要不同的测试方法Skill 类型定义测试方法成功标准纪律执行型强制遵守规则如 TDD、验证要求压力场景时间沉没成本疲劳组合施压Agent 在最大压力下仍遵守规则技术指导型具体方法的操作指南如条件等待、根因追踪应用场景能否正确应用边界情况指令有无缺口Agent 成功将技术应用到新场景思维模式型解决问题的心智模型如降低复杂度、信息隐藏识别场景能否识别何时适用何时不适用Agent 正确判断何时/如何应用模式参考资料型API 文档、命令参考、库指南检索场景能否找到正确信息常见用例是否覆盖Agent 找到并正确应用参考信息关键区别纪律执行型 Skill 需要最严格的测试压力场景 合理化借口反驳而参考资料型 Skill 主要测试信息的可发现性和完整性。3.5 Description 的关键要点这是 writing-skills 中最重要的发现之一。Description 只应描述触发条件绝不要总结 Skill 的工作流程。为什么测试发现当 description 总结了工作流程时Agent 可能直接按 description 执行而跳过阅读完整的 Skill 内容。# ❌ 总结了工作流 → Agent 可能走捷径跳过 Skill 正文description:Use when executing plans-dispatches subagent per task with code review between tasks# ✅ 只有触发条件 → Agent 会完整阅读 Skilldescription:Use when executing implementation plans with independent tasks in the current session3.6 Anthropic 官方最佳实践要点来源writing-skills 中引用的 anthropic-best-practices.md简洁是关键Context window 是公共资源。默认假设 Claude 已经很聪明只添加它不知道的信息# ✅ 简洁~50 tokens ## Extract PDF text Use pdfplumber for text extraction: import pdfplumber with pdfplumber.open(file.pdf) as pdf: text pdf.pages[0].extract_text() # ❌ 冗余~150 tokens ## Extract PDF text PDF (Portable Document Format) files are a common file format... To extract text from a PDF, youll need to use a library... There are many libraries available...设置合适的自由度自由度适用场景示例高多种方法都有效代码审查流程中有首选模式但允许变化带参数的脚本模板低操作脆弱、一致性关键数据库迁移命令工作流与反馈循环对于复杂任务Skill 中应包含清晰的工作流步骤和反馈循环工作流模式将复杂操作拆分为清晰的顺序步骤提供可追踪的检查清单## 研究综合工作流 复制此清单并跟踪进度 - [ ] Step 1: 阅读所有源文档 - [ ] Step 2: 识别关键主题 - [ ] Step 3: 交叉验证论点 - [ ] Step 4: 创建结构化摘要 - [ ] Step 5: 验证引用反馈循环模式运行验证器 → 修复错误 → 重复直到通过。这个模式能显著提升输出质量## 文档编辑流程 1. 编辑 document.xml 2. 立即验证python validate.py unpacked_dir/ 3. 如果验证失败 - 仔细阅读错误信息 - 修复 XML 中的问题 - 再次运行验证 4. 仅在验证通过后才继续 5. 重新打包python pack.py unpacked_dir/ output.docx关键验证脚本的错误信息要具体如 “Field ‘signature_date’ not found. Available fields: customer_name, order_total”帮助 Agent 快速定位和修复问题。迭代开发模式最有效的 Skill 开发过程Claude A专家帮你设计和优化 Skill ↓ Claude B测试者用 Skill 执行真实任务 ↓ 观察 Claude B 的行为发现问题 ↓ 回到 Claude A 改进 Skill ↓ 重复直到满意四、Skill 设计模式Google来源Google Cloud Tech规范告诉我们Skill 长什么样但没告诉我们Skill 内部的逻辑该怎么设计。一个封装 FastAPI 规范的 Skill 和一个分 4 步执行的文档流水线 Skill虽然外表都叫 SKILL.md但内部结构完全不是一回事。Google ADK 团队研究了生态中各种 Skill 的实现方式从 Anthropic 仓库到 Vercel 和 Google 内部指南总结出 5 种反复出现的设计模式。4.1 五种 Skill 设计模式模式一Tool Wrapper — 给 Agent 装技能包核心逻辑让 Agent 在需要时才加载特定领域的知识而不是把所有东西塞进 system prompt。---name:api-expertdescription:FastAPI 开发最佳实践与规范。适用于构建、审查或调试 FastAPI 应用程序时使用。---## 核心规范加载 references/conventions.md 获取完整规范列表。## 审查代码时1. 加载规范参考文件 2. 对照每条规范逐一检查用户代码 3. 针对每处违规引用具体规则并给出修改建议关键SKILL.md 本身不包含完整规范而是告诉 Agent去哪里加载规范。适用场景封装框架/库的编码规范、团队内部代码风格指南、特定技术栈的最佳实践。模式二Generator — 填空题式文档生成核心逻辑用模板 风格指南强制输出一致性。---name:report-generatordescription:以 Markdown 格式生成结构化技术报告。---第一步加载 references/style-guide.md获取语气和格式规范。 第二步加载 assets/report-template.md获取所需的输出结构。 第三步向用户询问缺失信息-主题或议题-关键发现或数据要点-目标受众 第四步按照风格指南规范填写模板。 第五步返回已完成的报告。关键Step 3 的主动提问——Agent 不会瞎猜缺什么直接问。适用场景标准化技术文档生成、API 文档自动生成、项目脚手架。模式三Reviewer — 代码审查自动化核心逻辑把查什么和怎么查分离。检查清单独立维护Agent 只负责执行打分。---name:code-reviewerdescription:审查 Python 代码的质量、风格与常见错误。---第一步加载 references/review-checklist.md。 第二步仔细阅读用户的代码。 第三步逐一应用清单中的每条规则。针对每处违规-记录行号-划分严重等级错误 / 警告 / 提示-解释问题的原因而不仅仅是描述问题本身-给出具体的修改建议 第四步按严重等级分组输出结构化的审查报告。关键Step 3 的 “WHY not WHAT”——不只指出问题还要解释为什么是问题。适用场景自动化 PR 审查、安全漏洞扫描、代码风格检查。模式四Inversion — 让 Agent 先问你核心逻辑翻转传统交互模式。不是用户驱动 prompt → Agent 执行而是 Agent 先采访用户收集完整需求后再动手。---name:project-plannerdescription:通过结构化提问收集需求 为新软件项目制定规划。---在所有阶段完成之前请勿开始构建。## 第一阶段 — 问题探索每次只提一个问题-问题1这个项目解决什么问题-问题2主要用户群体是哪些-问题3预期的使用规模是多少## 第二阶段 — 技术约束仅在第一阶段全部回答完毕后进行-问题4部署环境是什么-问题5是否有技术栈偏好-问题6哪些是不可妥协的硬性需求## 第三阶段 — 综合整理收集所有信息 → 加载模板 → 填写内容 → 呈现结果 → 迭代优化适用场景新项目规划、系统架构设计、需求不明确时的需求澄清。模式五Pipeline — 带检查点的多步工作流核心逻辑把复杂任务拆成严格顺序的步骤每步都有明确的输入/输出和通过条件Agent 不能跳步。---name:doc-pipelinedescription:通过多步骤流水线 从 Python 源代码生成 API 文档。---按顺序执行每个步骤不得跳过任何步骤。## 第一步 — 解析与清点分析代码提取所有公开 API以清单形式呈现。 询问这是完整的公开 API 列表吗## 第二步 — 生成文档字符串针对每个缺少文档字符串的函数生成内容并提交用户确认。 在用户确认之前不得进入第三步。## 第三步 — 组装文档加载模板将所有内容汇编为统一的 API 参考文档。## 第四步 — 质量检查对照清单进行审查在呈现最终文档之前修复所有问题。关键Step 2 → Step 3 的【确认前不得继续】是硬性约束——用户不点头Agent 不能往下走。适用场景从代码生成文档、多阶段内容生产、需要人工检查点的自动化流程。4.2 设计模式选择指南你需要什么选择哪种模式特定技术栈的专家知识Tool Wrapper一致的结构化输出Generator自动化代码/内容审查Reviewer需求不明确需先收集信息Inversion复杂的多步骤任务Pipeline不确定从 Tool Wrapper 开始4.3 模式组合推荐组合说明场景Pipeline Reviewer管道最后一步加自动审查文档生成后自动质量检查Generator Inversion先收集信息再填充模板需用户输入的结构化文档生成Pipeline Tool Wrapper管道某些步骤加载专家知识多步骤代码生成Inversion Pipeline先完成需求收集再进入执行流水线复杂项目全流程五、总结Skill 生态正在快速发展已形成规范标准agentskills.io→ 构建方法论Anthropic/Superpowers→ 设计模式Google的完整知识体系。三个关键认知Skill 不是 Prompt而是围绕任务、工具、流程和输出边界的结构化行为设计渐进式加载是核心机制解决了 Agent 系统的上下文膨胀问题描述是触发的关键写好 description 比写好指令主体更重要参考资料描述链接Agent Skills 开放规范https://agentskills.io/specificationAnthropic 官方 Skills 仓库https://github.com/anthropics/skillsSuperpowers 框架https://github.com/obra/superpowersGoogle ADK Skill 设计模式https://x.com/GoogleCloudTech/status/2033953579824758855Awesome Agent Skills1060 Skillshttps://github.com/VoltAgent/awesome-agent-skillsAnthropic 黑客马拉松获胜者的完整 Claude Code 配置集合包含skillshttps://github.com/affaan-m/everything-claude-codeSkill 编写规范http://www.uml.org.cn/ai/202605181.asp?artid27383开源 skills 市场https://skills.shhttps://skillsmp.comhttps://github.com/openclaw/clawhubhttps://qoder-community.pages.dev/zh/skillshttps://github.com/cinience/alicloud-skillshttps://hermes-agent.nousresearch.com/docs/skillsskill 评测https://www.skillsbench.ai/https://arxiv.org/html/2602.12670v1https://arxiv.org/html/2602.03279
