agent-skills 元技能解析using-agent-skills 如何驱动技能发现与 Agent 工程纪律【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills在 agent-skills 这个面向 AI 编码代理的生产级工程技能仓库中using-agent-skills是唯一的元技能meta-skill它不完成任何具体开发任务而是负责在每次任务到来时把请求路由到正确的技能工作流并定义所有技能共享的操作纪律。读完本文你将掌握该元技能的完整决策树、六大核心操作行为、16 步生命周期编排以及它在仓库中通过 SessionStart 钩子自动注入、通过 evals 评测验证的实际运行机制。什么是元技能using-agent-skills 的定位仓库由 24 个生命周期技能加 1 个元技能共 25 个技能组成每个技能是一个带步骤、验证门和反合理化表格的结构化工作流。using-agent-skills的职责在 README.md 中被明确定义为Maps incoming work to the right skill workflow and defines shared operating rules把到来的工作映射到正确的技能工作流并定义共享操作规则触发时机是开始会话或决定哪个技能适用当前任务时。技能定义文件 skills/using-agent-skills/SKILL.md 的 YAML frontmatter 正是这种元角色的声明--- name: using-agent-skills description: Discovers and invokes agent skills. Use when starting a session or when you need to discover which skill applies to the current task. This is the meta-skill that governs how all other skills are discovered and invoked. ---这里体现了仓库技能格式的两个关键设计详见 docs/skill-anatomy.mddescription 即触发器。Agent 是通过读取 description 来发现技能的——启动时只有技能名和 description 驻留在上下文中完整 SKILL.md 只在 Agent 判断相关时才加载渐进式披露Progressive Disclosure。因此 description 必须同时说明做什么和何时用而不能摘要工作流步骤否则 Agent 可能跟随摘要而不读完整技能文件。元技能是渐进式披露的第一层入口。它自身保持精简远小于 500 行上限只承载路由表 共享规则把具体流程下沉到各生命周期技能目录中按需加载。技能发现任务到技能的决策树元技能的核心内容是 Skill Discovery 决策树任务到来时先识别所处的开发阶段再应用对应技能。完整决策树如下继承自原技能文档Task arrives │ ├── Dont know what you want yet? ──────→ interview-me ├── Have a rough concept, need variants? → idea-refine ├── New project/feature/change? ──→ spec-driven-development ├── No quality bar written down? ──→ constraint-driven-development ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown ├── Implementing code? ────────────→ incremental-implementation │ ├── UI work? ─────────────────→ frontend-ui-engineering │ ├── API work? ────────────────→ api-and-interface-design │ ├── Need better context? ─────→ context-engineering │ ├── Need doc-verified code? ───→ source-driven-development │ └── Stakes high / unfamiliar code? ──→ doubt-driven-development ├── Writing/running tests? ────────→ test-driven-development │ └── Browser-based? ───────────→ browser-testing-with-devtools ├── Something broke? ──────────────→ debugging-and-error-recovery ├── Reviewing code? ───────────────→ code-review-and-quality │ ├── Too complex? ─────────────→ code-simplification │ ├── Security concerns? ───────→ security-and-hardening │ └── Performance concerns? ────→ performance-optimization ├── Committing/branching? ─────────→ git-workflow-and-versioning ├── CI/CD pipeline work? ──────────→ ci-cd-and-automation ├── Deprecating/migrating? ────────→ deprecation-and-migration ├── Writing docs/ADRs? ───────────→ documentation-and-adrs ├── Adding logs/metrics/alerts? ───→ observability-and-instrumentation └── Deploying/launching? ─────────→ shipping-and-launch从源码结构看这棵树的分支组织遵循两条原则按阶段分层interview-me→idea-refine→spec-driven-development→planning-and-task-breakdown构成定义/规划层incremental-implementation是构建层的主干UI、API、上下文、源码验证、高 stakes 审查作为它的子分支挂接test-driven-development是验证层浏览器测试作为子分支code-review-and-quality是审查层简化、安全、性能三个专项技能作为子分支。入口条件可判定每个分支节点都是一个具体可判定的问句还没想清楚要什么没有书面质量标准有规格但缺任务拆分而不是模糊的阶段名称。值得注意的一个细节决策树覆盖了全部 24 个生命周期技能其中constraint-driven-development只出现在决策树No quality bar written down?分支中而下面的 Quick Reference 表未收录它——需要该技能的读者应从决策树入口进入 skills/constraint-driven-development/SKILL.md。仓库中的 AGENTS.md 还给出了 OpenCode 环境下的意图映射表可以视为决策树的压缩版新特性 →spec-driven-development→incremental-implementation→test-driven-developmentbug/异常行为 →debugging-and-error-recovery代码审查 →code-review-and-quality重构 →code-simplificationAPI 设计 →api-and-interface-designUI →frontend-ui-engineering。其执行模型要求只要任务与某个技能有哪怕 1% 的匹配度就必须调用该技能且不得部分执行。核心操作行为贯穿所有技能的六条纪律决策树解决用哪个技能而 Core Operating Behaviors 解决用任何技能时都必须怎么做。原技能文档将这六条行为标记为non-negotiable不可协商它们在所有技能之上、全程生效。1. 显式暴露假设Surface Assumptions在实现任何非平凡的东西之前必须先显式陈述假设ASSUMPTIONS IM MAKING: 1. [assumption about requirements] 2. [assumption about architecture] 3. [assumption about scope] → Correct me now or Ill proceed with these.文档指出最常见的失败模式是做出错误假设且不经过检查就一路狂奔。不要悄悄填补模糊的需求——尽早暴露不确定性成本远低于返工。2. 主动管理困惑Manage Confusion Actively遇到不一致、相互冲突的需求或规格不清晰时执行四步停下来STOP不要带着猜测继续。明确指出具体的困惑点。呈现权衡tradeoff或提出澄清问题。等待解决后再继续。文档给出了对比示例错误做法悄悄选择一种解释指望它是对的。正确做法规格里写的是 X但现有代码里是 Y哪个优先3. 在合理时反驳Push Back When Warranted你不是 yes-machine只会点头的机器。当某个方案存在明显问题时直接指出问题说明具体代价尽量量化——这会引入约 200ms 延迟而不是这可能会更慢提出替代方案如果人类在充分知情后仍坚持接受其决定。文档把谄媚sycophancy明确列为失败模式对一个坏想法说当然可以然后照做对谁都没有帮助。诚实的技术分歧比虚假的同意更有价值。4. 强制执行简洁Enforce SimplicityAgent 的天然倾向是把事情搞复杂必须主动抵抗。完成任何实现前自问能否用更少的行数完成这些抽象值得它们引入的复杂度吗Staff 工程师看了会说你为什么不直接……吗如果你写了 1000 行而 100 行就够你失败了。优先选择无聊的、显而易见的方案——精巧cleverness是有代价的。5. 保持范围纪律Maintain Scope Discipline只动你被要求动的部分。明令禁止的行为包括删除你不理解的注释顺手清理与任务正交的代码把重构相邻系统当作副作用在没有明确批准的情况下删除看似无用的代码添加规格之外看起来有用的功能。原文的措辞是Your job is surgical precision, not unsolicited renovation.你的工作是外科手术式的精准而不是未经请求的翻新。6. 验证而非假设Verify, Dont Assume每个技能都包含一个验证步骤任务在验证通过之前都不算完成。看起来对永远不充分——必须有证据测试通过、构建输出、运行时数据。这里原文档引出了一个项目级的重要概念每个技能的验证是本地检查而适用于每一次变更无论当时激活的是哪个技能的全项目门槛是 Definition of Done——测试通过、无回归、运行时行为已验证、文档已更新。该文档指向仓库根目录的 references/definition-of-done.md原技能文件内写作../../references/definition-of-done.md从仓库根目录出发即为references/definition-of-done.md。references/definition-of-done.md 将 Definition of Done 与验收标准acceptance criteria做了明确区分验收标准因任务而异回答我们做的是不是对的东西DoD 固定不变回答这件事是否达到了我们的标准完成了。其常设清单覆盖五个维度Correctness验收标准全部满足运行时行为已验证不只是编译/类型检查通过新行为有没有这个变更就失败、有了它就通过的测试既有测试无回归边界与错误路径被处理。Quality命名与结构自解释意图无重复业务逻辑无死代码、调试输出或注释掉的代码块变更范围未夹带无关重构lint 与格式化通过。Integration变更与系统其余部分协同工作数据库迁移、配置变更、feature flag 被纳入考虑公共接口变更考虑向后兼容。Documentation公共接口与用户可见行为有文档值得保留的架构决策已记录引用documentation-and-adrs文档描述当前状态而非变更历史。Ship-readiness不受信输入、认证、数据处理经过安全审查引用security-and-hardening新关键路径有可观测性引用observability-and-instrumentation高风险项有回滚路径引用shipping-and-launch人类在合并/部署前已审查批准。应用方式是分层级的每任务确认 Correctness 与 Quality每特性确认 Integration 与 Documentation每发布以完整清单为底线再由shipping-and-launch叠加部署专项门。该文档还定义了五个 Red Flags例如我写完了只是还没运行——未经验证的代码不算完成测试通过被当作完成的同义词而跳过文档与运行时验证截止时间压力下门槛被调低等。十种失败模式看似高效、实则埋雷原技能文档把 Failure Modes to Avoid 描述为看起来像生产力、实则制造问题的微妙错误完整清单为做出错误假设而不检查不管理自己的困惑——迷路时仍然硬冲注意到不一致却不暴露对非显而易见的决策不呈现权衡对有明显问题的方案谄媚迎合Of course!过度复杂化代码和 API修改与任务正交的代码或注释删除自己不完全理解的东西因为显而易见就跳过规格直接写代码因为看起来对就跳过验证。这份清单与上面六条核心行为一一对应是从行为准则反推出来的可观察违规信号方便在代码评审和 Agent 自检时核对。技能规则四条硬性约定Skill Rules 一节给出了四条规则开工前先检查是否有适用技能。技能编码的是防止常见错误的过程。技能是工作流不是建议。按顺序执行步骤不得跳过验证步骤。多个技能可以同时适用。一个特性实现可能依次经历idea-refine→spec-driven-development→planning-and-task-breakdown→incremental-implementation→test-driven-development→code-review-and-quality→code-simplification→shipping-and-launch。拿不准时从规格开始。如果任务非平凡且没有规格先启动spec-driven-development。生命周期顺序16 步全量编排对一个完整特性原技能文档给出的典型技能序列如下完整继承1. interview-me → Extract what the user actually wants 2. idea-refine → Refine vague ideas 3. spec-driven-development → Define what were building 4. planning-and-task-breakdown → Break into verifiable chunks 5. context-engineering → Load the right context 6. source-driven-development → Verify against official docs 7. incremental-implementation → Build slice by slice 8. observability-and-instrumentation → Instrument as you build (runs parallel with 7-9, not after) 9. doubt-driven-development → Cross-examine non-trivial decisions in-flight 10. test-driven-development → Prove each slice works 11. code-review-and-quality → Review before merge 12. code-simplification → Reduce unnecessary complexity while preserving behavior 13. git-workflow-and-versioning → Clean commit history 14. documentation-and-adrs → Document decisions 15. deprecation-and-migration → Retire old systems and move users safely when needed 16. shipping-and-launch → Deploy safely两个要点值得强调第 8 步是并行而非串行可观测性埋点与第 7–9 步并行执行边构建边埋点而不是构建完成后再补。这与 README.md 对observability-and-instrumentation的摘要instrument as you build一致。不是每个任务都需要所有技能。一个 bug 修复可能只需要debugging-and-error-recovery→test-driven-development→code-review-and-quality。元技能的价值正在于此——按任务实际形态裁剪序列而不是机械走完全程。Quick Reference分阶段技能速查表原技能文档的 Quick Reference 表按六个阶段组织完整继承如下每个技能均可从 skills/ 目录下对应路径直接阅读阶段技能一句话摘要Defineinterview-me在任何计划、规格或代码出现之前挖出用户真正想要的东西Defineidea-refine通过结构化的发散与收敛思维打磨想法Definespec-driven-development先写需求与验收标准再写代码Planplanning-and-task-breakdown分解为小而可验证的任务Buildincremental-implementation薄垂直切片每片先测再扩Buildsource-driven-development实现前先对照官方文档验证Builddoubt-driven-development对每个非平凡决策做对抗式的新鲜上下文审查Buildcontext-engineering在正确的时间提供正确的上下文Buildfrontend-ui-engineering带可访问性的生产级 UIBuildapi-and-interface-design契约清晰的稳定接口Verifytest-driven-development先写失败测试再让它通过Verifybrowser-testing-with-devtools用 Chrome DevTools MCP 做运行时验证Verifydebugging-and-error-recovery复现 → 定位 → 修复 → 加防护Reviewcode-review-and-quality五轴审查加质量门Reviewcode-simplification保持行为不变的前提下削减复杂度Reviewsecurity-and-hardeningOWASP 预防、输入校验、最小权限Reviewperformance-optimization先测量只优化真正重要的部分Shipgit-workflow-and-versioning原子提交、干净历史Shipci-cd-and-automation每次变更都过自动化质量门Shipdeprecation-and-migration安全移除旧系统并迁移用户Shipdocumentation-and-adrs记录决策的原因而不只是内容Shipobservability-and-instrumentation结构化日志、RED 指标、追踪、基于症状的告警Shipshipping-and-launch上线前检查清单、监控、回滚计划如前所述速查表未收录constraint-driven-development它经由决策树的 No quality bar written down? 分支进入详见 skills/constraint-driven-development/SKILL.md。仓库实现纵深元技能如何被注入、路由与验证以上是技能文档本身的规则内容。接下来从仓库实现层面看这套规则是如何被真正执行的。SessionStart 钩子元技能在每个新会话自动注入与其他 24 个按需发现的技能不同元技能是主动注入的。hooks/hooks.json 注册了一个SessionStart钩子在会话启动时执行 hooks/session-start.sh。脚本逻辑为定位skills/using-agent-skills/SKILL.md读取其全部内容通过jq构造合法的 JSON 并转义输出标准的 SessionStart 信封{hookSpecificOutput: {hookEventName: SessionStart, additionalContext: agent-skills loaded. Use the skill discovery flowchart to find the right skill for your task.\n\nSKILL.md 全文}}这解释了元技能 frontmatter 中 Use when starting a session 的运行机制Agent 无需意识到自己应该查找元技能它在会话开始的那一刻就已经拥有了完整的决策树和六条操作纪律。脚本还处理了两种降级路径jq缺失时输出带安装提示的降级上下文并正常退出元技能文件缺失时提示技能仍可单独使用。注释中特别指出输出必须遵循标准 SessionStart 信封因为 Codex CLI 与 Claude Code 等宿主会对钩子输出做形状校验其他格式会被拒绝。评测体系路由正确性是可测的元技能的路由逻辑不是只写在纸上的——仓库为其配备了专门的评测用例 evals/cases/using-agent-skills.json正向触发positive triggers三条应路由到本技能的提示如 Which skill should I use for this task?、How do I decide which workflow applies to this piece of work?、Route this request to the right skill in the pack要求在前top_k: 3中命中。负向触发negative triggersDebug the null pointer crash in checkout 的所有者声明为debugging-and-error-recoveryMake the modal accessible for keyboard users 同理指向 UI 类技能——元技能不应在这些任务上抢占首位。行为评测behavioral eval给定提示 A user asks: the login page is broken after yesterdays deploy. Decide which skill applies and why.配套的现场输入是 evals/fixtures/using-agent-skills/incident.md登录页部署后返回 500请求到达认证回调后在写入会话 Cookie 前失败根因未知用户要的是恢复登录而非重新设计认证。评测期望所选技能与元技能的决策树一致正确路由应为debugging-and-error-recovery、理由引用路由逻辑而非猜测、核心操作行为暴露假设被遵守。按 evals/README.md 的说明这类触发评测属于第二层Trigger routing基于描述的 stemmed TF-IDF 词法近似在 CI 中通过node scripts/run-evals.js确定性运行成本为零它能抓住两类真实触发 bug——描述缺少用户实际用语漏报和描述过宽压过正确技能误报。第三层行为评测则通过无头claude实际执行并对照expectations[]判分。三层编排元技能处于哪一层从 AGENTS.md 的编排模型看仓库有三层可组合构件Skillsskills/name/SKILL.md——带步骤与退出条件的工作流是怎么做the howPersonasagents/role.md共 4 个专家角色如 agents/code-reviewer.md——带视角与输出格式的角色是谁来做the whoSlash commands——面向用户的入口是何时做the when的编排层。组合规则是用户或斜杠命令是唯一编排者persona 不调用 personapersona 可以调用技能。using-agent-skills元技能与斜杠命令共同承担意图到技能的映射职责而 references/orchestration-patterns.md 给出了被认可的多 persona 编排模式如/ship的并行 fan-out 合并报告。安装与运行方式元技能随整个技能包分发当前版本见 plugin.json 的version: 0.6.9。查看与使用方式整包安装推荐携带references/共享清单与hooks/通过 skills CLI 执行npx skills add addyosmani/agent-skills或按 README.md 中各宿主章节的 marketplace / plugin /gemini skills install/cmd skills add等原生方式安装单个技能安装只复制skills/name/不含仓库级references/目录——此时元技能引用的 Definition of Done 等共享清单路径将不可达README 中记录的已知可移植性缺口。因此若要完整体验元技能指向的全项目 DoD 门建议整仓集成安装后无需手动调用SessionStart 钩子会自动注入元技能在支持技能工具的 Agent 中也可以直接按名引用using-agent-skills来重新加载路由表。小结using-agent-skills用不到两百行 Markdown 承担了整个技能包的两个关键职能一是发现——一棵按开发阶段组织的可判定决策树把任意新任务路由到 24 个生命周期技能之一并支持多技能串行16 步全量生命周期或 bug 修复三件套这类裁剪序列二是纪律——暴露假设、管理困惑、敢于反驳、强制简洁、范围纪律、验证优先这六条不可协商的行为加上十条失败模式清单构成了跨越所有技能的共享操作层并与 references/definition-of-done.md 的全项目完成门槛共同兜底。仓库实现进一步保证了这套机制的落地SessionStart 钩子让元技能零成本进入每个会话evals 用例把路由是否正确变成了 CI 可回归的断言。对于维护多技能体系的 Agent 工程来说这个路由 纪律分离的元技能设计是值得直接借鉴的模式。【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考