从教材到工具箱Agent Skills 语料库的审计方法论与补强路径 — Agent-Skills-for-Context-Engineering 技能改进分析【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering本文以仓库中的 技能改进分析 为核心完整还原一次针对 Agent Skills 语料库的结构化审计如何以公开的 Skill 编写最佳实践为标尺逐项检查 description 触发条件、渐进式披露、Gotchas、hooks、配置化与持久化等维度并给出按影响力排序的 6 大差距与三级A–J改进路线图。读完后你可以掌握一套可复制的技能库质量自检方法既知道审计表怎么列、差距怎么定级也知道如何用仓库中的校验脚本和源码证据核验每项差距是否已闭环。一、分析背景一次对标式审计的设定该分析文档写于 2026-03-17对标对象是 Anthropic 团队发布的 Lessons from Building Claude Code: How We Use Skills 一文。审计方式是把仓库中的全部技能分析时的基线为 13 个技能逐一对照 Anthropic 披露的技能编写实践打分输出做得好的方面 → 差距按影响力排序→ 分层建议 → 总结论四段式结论。文档开头有一条重要的历史注记原文照录其含义该分析早于当前 v2.3.x 的 15 技能语料库文中出现的 12/13、13 skills 等计数描述的是旧基线不应作为当前生产库存使用。当前 README 声明该仓库以单一插件形式发布17 个技能覆盖 context-fundamentals、context-compression、multi-agent-patterns、harness-engineering、bdi-mental-states 等方向。因此本文引用计数时一律注明口径。这套审计的价值在于它不是泛泛地介绍什么是 Agent Skills而是给出一套可逐项核对的合规性判据——每一项判据都有明确的百分比得分且差距直接映射到具体的仓库目录skills/、template/、scripts/改进项可以直接落到文件级操作。二、审计判据与现状得分Audit Summary 表文档的核心结论浓缩在一张汇总表里下表为原文档内容的完整继承计数为 13 技能基线口径判据状态得分备注Gotchas SectionsCRITICAL GAP31% (4/13)按对标文章这是单技能内信号密度最高的内容Description FormatPERFECT100% (13/13)触发条件式use when X格式Composable ScriptsSTRONG92% (12/13)存在但属 reference 级别演示级On-Demand HooksNOT IMPLEMENTED0% (0/13)高差异化机会Config/Setup PatternNOT IMPLEMENTED0% (0/13)框架相关技能需要Persistent StorageMINIMAL23% (3/13)无${CLAUDE_PLUGIN_DATA}使用Progressive DisclosureCOMPREHENSIVE100% (13/13)SKILL.md → references/ → scripts/Templates/AssetsCOMPREHENSIVE100% (13/13)全部有参考文档整体合规度 65%——文档的结论是仅补齐 Gotchas 一项差距就能把整体合规度提升到约 85%。这说明判据之间并非等权Gotchas 被对标文章明确称为任何技能中信号密度最高的内容其权重远高于其他条目。2.1 已经做对的四个维度1) Description 字段作为触发条件100% 达标。每个 SKILL.md 的 frontmatter description 都采用use when X格式。这一判据在当前仓库中已经从约定升级为机器校验repository 校验脚本 会检查 frontmatter 的 name 与目录名一致、name 为 kebab-case、description 不超过 1024 字符并对I can / Use me / You can use this等非第三人称表述发出告警——因为 description 会被注入系统提示词人称不一致会破坏技能发现。技能模板 也明确要求以第三人称书写并写明所有权边界含 Do not activate 区块防止宽泛技能抢走窄技能的激活。2) 渐进式披露Progressive Disclosure。三级层级SKILL.md → references/ → scripts/是教科书式的渐进披露结构启动时代理只加载技能名与描述技能被激活时才读取正文正文引用references/中的细节文档需要时再运行scripts/中的代码。README 的 Design Philosophy 一节与 目录结构 说明每个技能遵循SKILL.md必需scripts/可选references/可选的布局与该判据完全一致。3) 可组合脚本12/13。绝大多数技能带 Python 脚本包含可调用的类与函数。但文档同时指出这些脚本是参考实现reference implementation——演示代码而不是代理在任务中真正 import 使用的组合式辅助库。这一点的展开见下文差距 1。4) 不陈述显而易见的事。技能内容专注于把模型推离默认行为如 U 形注意力曲线、观测掩码、KV-cache 技巧而非复述模型已经知道的知识。模板 将这一原则固化为三问Claude 真的需要这段解释吗我能否假设 Claude 已经知道这一段落的 token 成本是否值得三、六大差距按影响力排序差距 1最高影响技能是知识优先而非行动优先Anthropic 披露的 9 类技能绝大多数是操作型的——验证、脚手架搭建、自动化、runbook、部署而分析基线中的 13 个技能绝大多数是概念型的——教 Claude 理解上下文工程原理。文档引用的关键论断是你能给 Claude 的最强能力是它可以在运行时组合的代码而不是它阅读并内化的知识。文档用一组 before/after 代码把这个差距表达得非常具体# Before (reference): 展示 compaction 如何实现 class ContextCompactor: Example implementation... # After (composable): Claude 真正会用到 def compact_observation(output: str, max_tokens: int 500) - str: Compact a tool observation to fit within token budget.一字之差性质改变前者是给你看原理后者是import 我就用。从源码结构看这一差距在分析之后得到了部分响应。当前 compaction.py 的模块 docstring 直接以 Public API 开头列出了 7 个函数与 2 个类ObservationStore、ContextBudget等的公开接口并通过__all__显式导出每个函数都带 Use when: ... 的使用条件说明与生产注意事项如 token 估算用 ~4 字符/token 启发式、生产环境应换用模型专属 tokenizer。ObservationStore.mask()返回(masked_content, ref_id)二元组、ContextBudget.should_optimize()返回(should_optimize, reasons)——这些都是面向调用者的组合式接口而非演示脚本。也就是说文档差距 1 中把脚本从示范型改造为组合型的建议下文 E 项至少在 context-optimization 技能上已经落地。差距 2缺少 Gotchas 区已解决RESOLVED这是文档中标注为CRITICAL GAP的一项对标文章认为The highest-signal content in any skill is the Gotchas section而基线中只有 4/13 技能有这一节。文档指出的根因很典型——模板缺什么新生成的技能就会缺什么template/SKILL.md当时没有 Gotchas 区所以新建技能默认永远不会带上它。文档记录了修复动作commit c847b20全部 13 个技能补齐标准化的 Gotchas 区每技能 5–9 条模板同步更新为含规范 Gotchas 区的版本。当前仓库的源码证据印证了闭环template/SKILL.md 现在包含## Gotchas区并规定写法列出经验得来的失败模式、常见错误与反直觉行为……每条必须具体、可操作、且不与正文已有指导重复使用编号格式validate_repo.py 把## Gotchas列入强制章节清单与## When to Activate、## Core Concepts、## Practical Guidance、## Examples、## Guidelines、## Integration、## References并列缺失即报错另有 500 行正文上限与第三人称检查。再看文档为 Tier 1 建议给出的三条 Gotchas 示例它们与当前技能正文中的成稿几乎一一对应文档建议示例原文当前技能中的落点context-compressionDont compress tool definitions — models need exact schemascontext-compression Gotchas 第 1 条Never compress tool definitions or schemas … Treat tool definitions as immutable anchors that bypass compression.multi-agent-patternsSub-agents sharing context via message passing doubles token cost vs. filesystem coordinationmulti-agent-patterns Gotchas 第 5 条Telephone game in message-passing … Use filesystem coordination instead of message-passing for state that multiple agents need to access faithfully.context-optimizationPrefix caching breaks when system prompts change between turnscontext-optimization Gotchas 第 1、2 条Whitespace breaks KV-cache … 与 Timestamps in system prompts destroy cache hit rates …这个对照恰好演示了文档的核心方法论Gotchas 必须捕获真实失败模式而非理论失败模式——文档给的是失败模式类别落稿时扩展为带机制解释与可执行对策的具体条款。差距 3没有 on-demand hooks对标文章把 on-demand hooks 视为差异化能力如/careful拦截破坏性命令、/freeze拦截目录外编辑展示了 hook 如何把一个知识型技能变成护栏。文档针对上下文工程市场这个定位提出了三个天然适配的 hook 构想/budget— 上下文用量超过阈值时发出警告/trace— 为事后分析记录每次工具调用的 token 数/compress— 会话变长时自动触发压缩。当前仓库状态从仓库检索结果看skills/目录下不存在 hook 定义PreToolUse/PostToolUse等词仅出现在该分析文档自身即这一差距尚未落地。可以推断它属于高差异化、中工程量项被排在了路线图 Tier 2见下文 F 项。差距 4没有 setup/config 模式对标文章推荐对需要用户上下文的技能采用config.json模式。文档给出的例子memory-systems技能可以询问用户当前使用哪个框架并记住该偏好。从仓库检索看skills/下没有任何技能声明或读取config.json此差距同样未落地归入 Tier 3 的 H 项。差距 5没有度量基础设施对标文章描述用PreToolUsehooks 跟踪哪些技能热门、哪些技能触发不足。分析时的痛点是我们根本不知道技能是否被正确激活。当前仓库状态这一差距是六个中闭环最完整的一个。仓库现在拥有完整的激活度量体系路由器基准 以 50 prompts × 4 模型 × 3 次重复 600 次调用做端到端技能路由评测三轮正式结果分别发布在 基线、描述改写后、全库加固后600/600 有效记录、0 格式失败README 披露的复现入口是 sdk-runner 与python3 researcher/scripts/run_benchmarks.py配套的还有 19 条确定性激活回归用例捕获技能边界混淆与技能健康门禁researcher/scripts/skill_health.py。一个可以直接引用的证据描述改写前后context-fundamentals的 top-1 路由准确率从 0.255 提升到 0.48923.4ppproject-development从 0.750 提升到 1.000。这正是文档差距 5 想要的知道技能是否被正确激活的能力——只不过最终实现选择的是离线基准而非PreToolUse日志。差距 6没有${CLAUDE_PLUGIN_DATA}持久化使用对标文章强调持久数据存储让技能可以随时间学习。文档指出分析基线的技能是无状态的——会话之间遗忘一切。从仓库检索看${CLAUDE_PLUGIN_DATA}至今只出现在该分析文档中此差距未落地归入 Tier 3 的 J 项。四、分层改进路线图Tier 1–3A–J 全量继承文档把建议按影响 × 工程量分成三级。以下完整继承原文档的全部 10 条建议A–J并补充当前仓库中的落点核验。Tier 1快速收益高影响、低工程量A. 给模板和全部缺失技能补 Gotchas。把## Gotchas加进template/SKILL.md再给缺该节的 9 个技能逐一补齐内容必须是真实失败模式。文档给出的三条示例已在 3.2 节对照正是此建议的验收样例。当前状态已完成——模板含规范 Gotchas 区template/SKILL.md校验脚本强制该章节现存 17 个技能的 SKILL.md 全部含## Gotchas。B. 增加 marketplace 策展流程。新增sandbox/目录存放实验性技能并在 CONTRIBUTING.md 中描述 sandbox → traction → marketplace 的晋升流程。当前状态仓库根目录中未见sandbox/目录此项未见落地。C. 用文章最佳实践更新 SKILL.md 模板。新增 Gotchas、Setup Requirements、Related Scripts、Storage Expectations 四个区。当前状态Gotchas 区已进模板见上后三个区未见进入 template/SKILL.md模板当前以所有权边界 三级披露 claim 溯源作为补充治理点要求数值/基准类声明携带claim-*ID 并在researcher/claims/index.jsonl中有据可查。Tier 2结构性增强中工程量、高差异化D. 创建 2–3 个操作型技能补足知识型技能的短板。文档原文的提案表拟建技能类别作用context-debuggerRunbook上下文故障的症状 → 排查 → 诊断流程agent-scaffoldingCode Scaffolding为新 agent 项目生成样板代码skill-creatorCode Scaffolding元技能按约定辅助创建新技能对照当前 17 技能清单见 README 技能总览这三个具体命名未出现但清单中的harness-engineering锁定指标、耐久日志、新奇门、回滚与人工审批边界的自主循环设计与self-improvement-loops失败驱动的 harness 自编辑、meta-harness 搜索、进化式脚手架搜索承担了相近的操作型定位——可以推断仓库后续选择走的是操作型 harness 技能而非文档最初设想的三个脚手架技能。E. 把脚本从示范型改造为组合型。即前文 before/after 代码所示的改造。当前 compaction.py 的 Public API Use when 结构第 3.1 节已引证是该改造的现成样本。F. 给 2–3 个技能加 on-demand hooks。文档指定的起步组合context-optimization→ 对超大工具输出发出警告的 hookevaluation→ 自动评估 Claude 输出质量的 hookcontext-compression→ 监控会话长度的 hook。当前状态与差距 3 一致尚未落地。Tier 3生态成熟度高工程量、长期价值G. 新增使用度计量技能——用PreToolUsehook 记录技能激活。当前仓库以离线路由器基准 激活回归用例researcher/benchmarks/、activation-cases覆盖了同类诉求实现形态不同但度量目标一致。H. 给框架相关技能memory-systems、multi-agent-patterns加 config.json 设置——未落地。I. 创建技能组合示例——展示技能如何互相调用。J. 通过${CLAUDE_PLUGIN_DATA}增加持久学习——让技能随时间变好。未落地。五、Meta-Insight教材与工具箱文档的总结论值得单独列出因为它是整个分析的战略层判断当前仓库是一部教材——教 Claude 如何思考上下文工程而 Anthropic 的文章揭示最有影响力的技能是工具箱——给 Claude 的是能做的事而不是要知道的事。该仓库最强的形态是两者兼备内嵌操作能力的知识型技能。知识底座让它被学术论文引用README 的 Recognition 一节列出了两篇引用它作为静态技能架构代表工作的论文在此之上叠加可执行工具gotchas、hooks、组合式脚本、持久状态会让技能在实际使用中显著更有用。这条判断解释了为什么审计判据里Composable Scripts虽然得分 92% 仍被标注为 STRONGreference-grade——数量达标不等于形态达标。六、Anthropic 的 9 类技能 vs. 本仓库覆盖度文档最后用一张覆盖矩阵回答知识型技能在 9 大类版图里站在什么位置完整继承原文档内容Our Skills 为 13 技能基线口径类别覆盖度对应技能Library API ReferenceModeratememory-systems, tool-designProduct VerificationModerateevaluation, advanced-evaluationData Fetching AnalysisLight仅 interleaved-thinking 示例Business Process AutomationLight仅 digital-brain 示例Code Scaffolding TemplatesLightproject-developmentCode Quality ReviewModerateevaluation, advanced-evaluationCI/CD DeploymentLighthosted-agentsRunbooksLightcontext-degradationInfrastructure OperationsLighthosted-agents矩阵显示覆盖度集中在 Moderate 及以下操作型类别Scaffolding、Runbooks、Automation普遍只有 Light 覆盖——与差距 1 的判断互为印证也解释了 Tier 2 D 项补操作型技能的由来。值得注意的是表中两处 仅 examples 覆盖 指向仓库的 examples 目录interleaved-thinking推理轨迹优化器与digital-brain-skill个人操作系统确实存在于 examples/ 下说明示例即覆盖是该仓库有意的设计——examples 目录承担了正式技能尚未覆盖的操作型版图。七、实操如何在自己的技能库上复现这套审计这套方法可以脱离本文档独立复用。最小可执行流程如下命令均以本仓库为参照路径见 README 的 Operator commands 一节列判据从对标材料提取可核对判据description 格式、渐进式披露、Gotchas、hooks、config、持久化、脚本组合性每条给 0/1 或百分比得分。查模板模板缺什么章节新技能就会系统性地缺什么——先修template/再回填存量。机器校验安装校验依赖后运行确定性门禁本仓库 CI 对每个 PR 都会跑python3 -m pip install -r requirements-dev.txt python3 researcher/scripts/validate_repo.py --strict # 校验 frontmatter、必填章节含 Gotchas、500 行上限 python3 researcher/scripts/skill_health.py --strict --no-history # 正文质量确定性打分 python3 researcher/scripts/check_activation_cases.py # 19 条激活边界回归 python3 researcher/scripts/run_benchmarks.py # 路由/有效性基准定级排期按影响 × 工程量把差距排进 Tier 1/2/3快速收益模板补章节 存量回填先行——本文档中仅补 Gotchas 即可把 65% 提到 ~85%就是典型的杠杆测算。核验闭环对每项已完成的建议在源码里找可验证落点强制章节校验、技能正文中的成稿 gotchas、公开 API 化脚本、基准发布记录而不是只看文档里的勾选框。适用前提与限制本文全部计数13/17 技能、31%、65%、85% 等分别对应 2026-03-17 分析时的 13 技能基线与当前 17 技能语料引用时须保留各自口径路由基准数字来自仓库公开发布结果600 次调用、4 个前沿模型、经 Cursor SDK 执行复现需具备相应 API 访问条件分析文档中关于 hooks差距 3、config.json差距 4、${CLAUDE_PLUGIN_DATA}差距 6的未实现结论基于当前仓库检索事实操作型技能走向 harness-engineering / self-improvement-loops为基于技能清单结构的推断。八、结语这份改进分析示范了技能库治理的一个完整周期对标 → 打分 → 定差距 → 分层建议 → 模板先行 → 机器门禁 → 基准核验。它最有迁移价值的两点一是把模板即默认值当成第一根因——技能库的系统性缺陷几乎都来自模板缺口修复模板比逐个打补丁便宜一个数量级二是用知识型 vs 操作型的双维度审视库存避免一个得分很高的技能库实际上只教会了模型知道却没给它做到的手段。对任何维护 Agent Skills 集合的团队这套以 审计表 为骨架、以 校验脚本 为门禁、以 路由器基准 为度量反馈的方法都可以直接照抄。【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
从教材到工具箱：Agent Skills 语料库的审计方法论与补强路径 — Agent-Skills-for-Context-Engineering 技能改进分析
从教材到工具箱Agent Skills 语料库的审计方法论与补强路径 — Agent-Skills-for-Context-Engineering 技能改进分析【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering本文以仓库中的 技能改进分析 为核心完整还原一次针对 Agent Skills 语料库的结构化审计如何以公开的 Skill 编写最佳实践为标尺逐项检查 description 触发条件、渐进式披露、Gotchas、hooks、配置化与持久化等维度并给出按影响力排序的 6 大差距与三级A–J改进路线图。读完后你可以掌握一套可复制的技能库质量自检方法既知道审计表怎么列、差距怎么定级也知道如何用仓库中的校验脚本和源码证据核验每项差距是否已闭环。一、分析背景一次对标式审计的设定该分析文档写于 2026-03-17对标对象是 Anthropic 团队发布的 Lessons from Building Claude Code: How We Use Skills 一文。审计方式是把仓库中的全部技能分析时的基线为 13 个技能逐一对照 Anthropic 披露的技能编写实践打分输出做得好的方面 → 差距按影响力排序→ 分层建议 → 总结论四段式结论。文档开头有一条重要的历史注记原文照录其含义该分析早于当前 v2.3.x 的 15 技能语料库文中出现的 12/13、13 skills 等计数描述的是旧基线不应作为当前生产库存使用。当前 README 声明该仓库以单一插件形式发布17 个技能覆盖 context-fundamentals、context-compression、multi-agent-patterns、harness-engineering、bdi-mental-states 等方向。因此本文引用计数时一律注明口径。这套审计的价值在于它不是泛泛地介绍什么是 Agent Skills而是给出一套可逐项核对的合规性判据——每一项判据都有明确的百分比得分且差距直接映射到具体的仓库目录skills/、template/、scripts/改进项可以直接落到文件级操作。二、审计判据与现状得分Audit Summary 表文档的核心结论浓缩在一张汇总表里下表为原文档内容的完整继承计数为 13 技能基线口径判据状态得分备注Gotchas SectionsCRITICAL GAP31% (4/13)按对标文章这是单技能内信号密度最高的内容Description FormatPERFECT100% (13/13)触发条件式use when X格式Composable ScriptsSTRONG92% (12/13)存在但属 reference 级别演示级On-Demand HooksNOT IMPLEMENTED0% (0/13)高差异化机会Config/Setup PatternNOT IMPLEMENTED0% (0/13)框架相关技能需要Persistent StorageMINIMAL23% (3/13)无${CLAUDE_PLUGIN_DATA}使用Progressive DisclosureCOMPREHENSIVE100% (13/13)SKILL.md → references/ → scripts/Templates/AssetsCOMPREHENSIVE100% (13/13)全部有参考文档整体合规度 65%——文档的结论是仅补齐 Gotchas 一项差距就能把整体合规度提升到约 85%。这说明判据之间并非等权Gotchas 被对标文章明确称为任何技能中信号密度最高的内容其权重远高于其他条目。2.1 已经做对的四个维度1) Description 字段作为触发条件100% 达标。每个 SKILL.md 的 frontmatter description 都采用use when X格式。这一判据在当前仓库中已经从约定升级为机器校验repository 校验脚本 会检查 frontmatter 的 name 与目录名一致、name 为 kebab-case、description 不超过 1024 字符并对I can / Use me / You can use this等非第三人称表述发出告警——因为 description 会被注入系统提示词人称不一致会破坏技能发现。技能模板 也明确要求以第三人称书写并写明所有权边界含 Do not activate 区块防止宽泛技能抢走窄技能的激活。2) 渐进式披露Progressive Disclosure。三级层级SKILL.md → references/ → scripts/是教科书式的渐进披露结构启动时代理只加载技能名与描述技能被激活时才读取正文正文引用references/中的细节文档需要时再运行scripts/中的代码。README 的 Design Philosophy 一节与 目录结构 说明每个技能遵循SKILL.md必需scripts/可选references/可选的布局与该判据完全一致。3) 可组合脚本12/13。绝大多数技能带 Python 脚本包含可调用的类与函数。但文档同时指出这些脚本是参考实现reference implementation——演示代码而不是代理在任务中真正 import 使用的组合式辅助库。这一点的展开见下文差距 1。4) 不陈述显而易见的事。技能内容专注于把模型推离默认行为如 U 形注意力曲线、观测掩码、KV-cache 技巧而非复述模型已经知道的知识。模板 将这一原则固化为三问Claude 真的需要这段解释吗我能否假设 Claude 已经知道这一段落的 token 成本是否值得三、六大差距按影响力排序差距 1最高影响技能是知识优先而非行动优先Anthropic 披露的 9 类技能绝大多数是操作型的——验证、脚手架搭建、自动化、runbook、部署而分析基线中的 13 个技能绝大多数是概念型的——教 Claude 理解上下文工程原理。文档引用的关键论断是你能给 Claude 的最强能力是它可以在运行时组合的代码而不是它阅读并内化的知识。文档用一组 before/after 代码把这个差距表达得非常具体# Before (reference): 展示 compaction 如何实现 class ContextCompactor: Example implementation... # After (composable): Claude 真正会用到 def compact_observation(output: str, max_tokens: int 500) - str: Compact a tool observation to fit within token budget.一字之差性质改变前者是给你看原理后者是import 我就用。从源码结构看这一差距在分析之后得到了部分响应。当前 compaction.py 的模块 docstring 直接以 Public API 开头列出了 7 个函数与 2 个类ObservationStore、ContextBudget等的公开接口并通过__all__显式导出每个函数都带 Use when: ... 的使用条件说明与生产注意事项如 token 估算用 ~4 字符/token 启发式、生产环境应换用模型专属 tokenizer。ObservationStore.mask()返回(masked_content, ref_id)二元组、ContextBudget.should_optimize()返回(should_optimize, reasons)——这些都是面向调用者的组合式接口而非演示脚本。也就是说文档差距 1 中把脚本从示范型改造为组合型的建议下文 E 项至少在 context-optimization 技能上已经落地。差距 2缺少 Gotchas 区已解决RESOLVED这是文档中标注为CRITICAL GAP的一项对标文章认为The highest-signal content in any skill is the Gotchas section而基线中只有 4/13 技能有这一节。文档指出的根因很典型——模板缺什么新生成的技能就会缺什么template/SKILL.md当时没有 Gotchas 区所以新建技能默认永远不会带上它。文档记录了修复动作commit c847b20全部 13 个技能补齐标准化的 Gotchas 区每技能 5–9 条模板同步更新为含规范 Gotchas 区的版本。当前仓库的源码证据印证了闭环template/SKILL.md 现在包含## Gotchas区并规定写法列出经验得来的失败模式、常见错误与反直觉行为……每条必须具体、可操作、且不与正文已有指导重复使用编号格式validate_repo.py 把## Gotchas列入强制章节清单与## When to Activate、## Core Concepts、## Practical Guidance、## Examples、## Guidelines、## Integration、## References并列缺失即报错另有 500 行正文上限与第三人称检查。再看文档为 Tier 1 建议给出的三条 Gotchas 示例它们与当前技能正文中的成稿几乎一一对应文档建议示例原文当前技能中的落点context-compressionDont compress tool definitions — models need exact schemascontext-compression Gotchas 第 1 条Never compress tool definitions or schemas … Treat tool definitions as immutable anchors that bypass compression.multi-agent-patternsSub-agents sharing context via message passing doubles token cost vs. filesystem coordinationmulti-agent-patterns Gotchas 第 5 条Telephone game in message-passing … Use filesystem coordination instead of message-passing for state that multiple agents need to access faithfully.context-optimizationPrefix caching breaks when system prompts change between turnscontext-optimization Gotchas 第 1、2 条Whitespace breaks KV-cache … 与 Timestamps in system prompts destroy cache hit rates …这个对照恰好演示了文档的核心方法论Gotchas 必须捕获真实失败模式而非理论失败模式——文档给的是失败模式类别落稿时扩展为带机制解释与可执行对策的具体条款。差距 3没有 on-demand hooks对标文章把 on-demand hooks 视为差异化能力如/careful拦截破坏性命令、/freeze拦截目录外编辑展示了 hook 如何把一个知识型技能变成护栏。文档针对上下文工程市场这个定位提出了三个天然适配的 hook 构想/budget— 上下文用量超过阈值时发出警告/trace— 为事后分析记录每次工具调用的 token 数/compress— 会话变长时自动触发压缩。当前仓库状态从仓库检索结果看skills/目录下不存在 hook 定义PreToolUse/PostToolUse等词仅出现在该分析文档自身即这一差距尚未落地。可以推断它属于高差异化、中工程量项被排在了路线图 Tier 2见下文 F 项。差距 4没有 setup/config 模式对标文章推荐对需要用户上下文的技能采用config.json模式。文档给出的例子memory-systems技能可以询问用户当前使用哪个框架并记住该偏好。从仓库检索看skills/下没有任何技能声明或读取config.json此差距同样未落地归入 Tier 3 的 H 项。差距 5没有度量基础设施对标文章描述用PreToolUsehooks 跟踪哪些技能热门、哪些技能触发不足。分析时的痛点是我们根本不知道技能是否被正确激活。当前仓库状态这一差距是六个中闭环最完整的一个。仓库现在拥有完整的激活度量体系路由器基准 以 50 prompts × 4 模型 × 3 次重复 600 次调用做端到端技能路由评测三轮正式结果分别发布在 基线、描述改写后、全库加固后600/600 有效记录、0 格式失败README 披露的复现入口是 sdk-runner 与python3 researcher/scripts/run_benchmarks.py配套的还有 19 条确定性激活回归用例捕获技能边界混淆与技能健康门禁researcher/scripts/skill_health.py。一个可以直接引用的证据描述改写前后context-fundamentals的 top-1 路由准确率从 0.255 提升到 0.48923.4ppproject-development从 0.750 提升到 1.000。这正是文档差距 5 想要的知道技能是否被正确激活的能力——只不过最终实现选择的是离线基准而非PreToolUse日志。差距 6没有${CLAUDE_PLUGIN_DATA}持久化使用对标文章强调持久数据存储让技能可以随时间学习。文档指出分析基线的技能是无状态的——会话之间遗忘一切。从仓库检索看${CLAUDE_PLUGIN_DATA}至今只出现在该分析文档中此差距未落地归入 Tier 3 的 J 项。四、分层改进路线图Tier 1–3A–J 全量继承文档把建议按影响 × 工程量分成三级。以下完整继承原文档的全部 10 条建议A–J并补充当前仓库中的落点核验。Tier 1快速收益高影响、低工程量A. 给模板和全部缺失技能补 Gotchas。把## Gotchas加进template/SKILL.md再给缺该节的 9 个技能逐一补齐内容必须是真实失败模式。文档给出的三条示例已在 3.2 节对照正是此建议的验收样例。当前状态已完成——模板含规范 Gotchas 区template/SKILL.md校验脚本强制该章节现存 17 个技能的 SKILL.md 全部含## Gotchas。B. 增加 marketplace 策展流程。新增sandbox/目录存放实验性技能并在 CONTRIBUTING.md 中描述 sandbox → traction → marketplace 的晋升流程。当前状态仓库根目录中未见sandbox/目录此项未见落地。C. 用文章最佳实践更新 SKILL.md 模板。新增 Gotchas、Setup Requirements、Related Scripts、Storage Expectations 四个区。当前状态Gotchas 区已进模板见上后三个区未见进入 template/SKILL.md模板当前以所有权边界 三级披露 claim 溯源作为补充治理点要求数值/基准类声明携带claim-*ID 并在researcher/claims/index.jsonl中有据可查。Tier 2结构性增强中工程量、高差异化D. 创建 2–3 个操作型技能补足知识型技能的短板。文档原文的提案表拟建技能类别作用context-debuggerRunbook上下文故障的症状 → 排查 → 诊断流程agent-scaffoldingCode Scaffolding为新 agent 项目生成样板代码skill-creatorCode Scaffolding元技能按约定辅助创建新技能对照当前 17 技能清单见 README 技能总览这三个具体命名未出现但清单中的harness-engineering锁定指标、耐久日志、新奇门、回滚与人工审批边界的自主循环设计与self-improvement-loops失败驱动的 harness 自编辑、meta-harness 搜索、进化式脚手架搜索承担了相近的操作型定位——可以推断仓库后续选择走的是操作型 harness 技能而非文档最初设想的三个脚手架技能。E. 把脚本从示范型改造为组合型。即前文 before/after 代码所示的改造。当前 compaction.py 的 Public API Use when 结构第 3.1 节已引证是该改造的现成样本。F. 给 2–3 个技能加 on-demand hooks。文档指定的起步组合context-optimization→ 对超大工具输出发出警告的 hookevaluation→ 自动评估 Claude 输出质量的 hookcontext-compression→ 监控会话长度的 hook。当前状态与差距 3 一致尚未落地。Tier 3生态成熟度高工程量、长期价值G. 新增使用度计量技能——用PreToolUsehook 记录技能激活。当前仓库以离线路由器基准 激活回归用例researcher/benchmarks/、activation-cases覆盖了同类诉求实现形态不同但度量目标一致。H. 给框架相关技能memory-systems、multi-agent-patterns加 config.json 设置——未落地。I. 创建技能组合示例——展示技能如何互相调用。J. 通过${CLAUDE_PLUGIN_DATA}增加持久学习——让技能随时间变好。未落地。五、Meta-Insight教材与工具箱文档的总结论值得单独列出因为它是整个分析的战略层判断当前仓库是一部教材——教 Claude 如何思考上下文工程而 Anthropic 的文章揭示最有影响力的技能是工具箱——给 Claude 的是能做的事而不是要知道的事。该仓库最强的形态是两者兼备内嵌操作能力的知识型技能。知识底座让它被学术论文引用README 的 Recognition 一节列出了两篇引用它作为静态技能架构代表工作的论文在此之上叠加可执行工具gotchas、hooks、组合式脚本、持久状态会让技能在实际使用中显著更有用。这条判断解释了为什么审计判据里Composable Scripts虽然得分 92% 仍被标注为 STRONGreference-grade——数量达标不等于形态达标。六、Anthropic 的 9 类技能 vs. 本仓库覆盖度文档最后用一张覆盖矩阵回答知识型技能在 9 大类版图里站在什么位置完整继承原文档内容Our Skills 为 13 技能基线口径类别覆盖度对应技能Library API ReferenceModeratememory-systems, tool-designProduct VerificationModerateevaluation, advanced-evaluationData Fetching AnalysisLight仅 interleaved-thinking 示例Business Process AutomationLight仅 digital-brain 示例Code Scaffolding TemplatesLightproject-developmentCode Quality ReviewModerateevaluation, advanced-evaluationCI/CD DeploymentLighthosted-agentsRunbooksLightcontext-degradationInfrastructure OperationsLighthosted-agents矩阵显示覆盖度集中在 Moderate 及以下操作型类别Scaffolding、Runbooks、Automation普遍只有 Light 覆盖——与差距 1 的判断互为印证也解释了 Tier 2 D 项补操作型技能的由来。值得注意的是表中两处 仅 examples 覆盖 指向仓库的 examples 目录interleaved-thinking推理轨迹优化器与digital-brain-skill个人操作系统确实存在于 examples/ 下说明示例即覆盖是该仓库有意的设计——examples 目录承担了正式技能尚未覆盖的操作型版图。七、实操如何在自己的技能库上复现这套审计这套方法可以脱离本文档独立复用。最小可执行流程如下命令均以本仓库为参照路径见 README 的 Operator commands 一节列判据从对标材料提取可核对判据description 格式、渐进式披露、Gotchas、hooks、config、持久化、脚本组合性每条给 0/1 或百分比得分。查模板模板缺什么章节新技能就会系统性地缺什么——先修template/再回填存量。机器校验安装校验依赖后运行确定性门禁本仓库 CI 对每个 PR 都会跑python3 -m pip install -r requirements-dev.txt python3 researcher/scripts/validate_repo.py --strict # 校验 frontmatter、必填章节含 Gotchas、500 行上限 python3 researcher/scripts/skill_health.py --strict --no-history # 正文质量确定性打分 python3 researcher/scripts/check_activation_cases.py # 19 条激活边界回归 python3 researcher/scripts/run_benchmarks.py # 路由/有效性基准定级排期按影响 × 工程量把差距排进 Tier 1/2/3快速收益模板补章节 存量回填先行——本文档中仅补 Gotchas 即可把 65% 提到 ~85%就是典型的杠杆测算。核验闭环对每项已完成的建议在源码里找可验证落点强制章节校验、技能正文中的成稿 gotchas、公开 API 化脚本、基准发布记录而不是只看文档里的勾选框。适用前提与限制本文全部计数13/17 技能、31%、65%、85% 等分别对应 2026-03-17 分析时的 13 技能基线与当前 17 技能语料引用时须保留各自口径路由基准数字来自仓库公开发布结果600 次调用、4 个前沿模型、经 Cursor SDK 执行复现需具备相应 API 访问条件分析文档中关于 hooks差距 3、config.json差距 4、${CLAUDE_PLUGIN_DATA}差距 6的未实现结论基于当前仓库检索事实操作型技能走向 harness-engineering / self-improvement-loops为基于技能清单结构的推断。八、结语这份改进分析示范了技能库治理的一个完整周期对标 → 打分 → 定差距 → 分层建议 → 模板先行 → 机器门禁 → 基准核验。它最有迁移价值的两点一是把模板即默认值当成第一根因——技能库的系统性缺陷几乎都来自模板缺口修复模板比逐个打补丁便宜一个数量级二是用知识型 vs 操作型的双维度审视库存避免一个得分很高的技能库实际上只教会了模型知道却没给它做到的手段。对任何维护 Agent Skills 集合的团队这套以 审计表 为骨架、以 校验脚本 为门禁、以 路由器基准 为度量反馈的方法都可以直接照抄。【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考