AI 编码代理的 20 个生产级工程技能：agent-skills 从需求到上线的完整实战指南
【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills
agent-skills 是一套面向 AI 编码代理的工程技能集：20 个技能把资深工程师"什么时候写规范、写什么测试、怎么审查、何时发布"的判断力，打包成 agent 能稳定执行的工作流。这篇指南不按教科书流程讲，而是按 6 种真实处境组织——你先找到自己的处境，再对号入座拿技能。
需求还一团浆糊时：先让 AI 别急着写代码
最贵的翻车不是代码写错，而是方向就猜错了。AI 写代码快，但它面对模糊需求时"猜"得比你还快——而且绝不承认自己在猜。这一组技能全部发生在敲下第一行业务代码之前。
一句话需求 → 逐题盘问。你说"我想要个类似 XX 的东西"，interview-me 技能不会让你列需求清单，而是一次只问一个问题，连续追问到你和代理对"到底要什么"达到约 95% 的把握为止。它要挖的是你实际想要的，不是你觉得该想要的。
有概念没方案 → 先散焦再收焦。idea-refine 提供一套结构化的发散/收敛思考：先把模糊概念摊开成多个可行变体，再收敛成具体提案。它的价值在"先给你选项"，而不是替你直接拍板。
动代码前 → 先有规范。spec-driven-development 的立场很硬：没有规范的代码就是在赌。规范要求写清构建什么、为什么构建、以及怎样算做完，并且走 SPECIFY → PLAN → TASKS → IMPLEMENT 四道门禁，每道都有人工确认。如果一条需求其实塞了好几个能独立验证的能力（比如身份、计费、通知），它还会先逼你画一张"能力地图"拆模块，而不是硬写一整篇大规范。单行修复、改错别字这类自明式改动则明确豁免，不用走这套流程。
规范 → 任务。planning-and-task-breakdown 负责把规范拆成小的、可验证的任务：每个任务带验收标准，任务之间有依赖排序。目的只有一个——别让 agent 拿到一堆没有优先级的任务后乱序开工。
接手烂摊子时的三板斧：停手、排障、存档
假设你刚接手一个测试红一半、文档缺角的仓库。新手最常见的错误是"边修边加功能"，而这里三个技能恰好覆盖接手第一周的三个动作。
停手保现场。debugging-and-error-recovery 的第一条规则叫"停线"：出现意外就先停止一切功能开发，把错误输出、日志、复现步骤都保住，再按五步走——复现 → 定位 → 缩减 → 修复 → 加防护。它的核心警告是：带着没修好的 bug 继续往下写，后面的每一步都会建立在错误的结果上，错误只会复利式地滚大。
提交当存档点。git-workflow-and-versioning 建议主干开发：main 随时可部署，功能分支只活 1-3 天，每次成功的小增量单独提交。分支活得越久，合并风险攒得越多。这套纪律的意义在 agent 场景下被放大——AI 产出代码的速度极快，只有版本控制能把它的产出切成可审查、可回滚的小块。
修 bug 先写"翻车证明"。test-driven-development 里的 Prove-It 模式专治 bug：先写一个能稳定复现这个 bug 的测试，再动修复。测试从红变绿，就是修好的证据，还顺手堵住了同一个坑第二次出现的可能。
改完了，怎么证明它是对的："好像没问题"不算完成
写代码这组技能的共同敌人是一个词：好像。"看起来对"在这套体系里永远不够，必须有测试通过、构建输出或运行时数据这类证据。
先红后绿再重构。TDD 的循环是：写一个失败的测试 → 写最少代码让它通过 → 重构。测试数量上有 80/15/5 的金字塔参考（单元/集成/端到端）。有个细节值得强调：技能要求先摸清这个仓库自己用什么命令跑测试（Gradle、Cargo、pytest 各有各的写法），绝不假设默认命令。
一次只切一片。incremental-implementation 的纪律是垂直切片：一片 = 一条从 UI 到数据库的完整窄路径，做完 → 测 → 验 → 提交，再切下一片。触发条件很直白——任何一次超过 100 行还没跑过测试的冲动，就该停下来切片。
浏览器里的东西眼见为实。browser-testing-with-devtools 接上 Chrome DevTools MCP，直接看真实的 DOM、console 日志、网络请求和性能曲线。前端问题靠想象是查不出来的，这个技能逼你把运行时证据摆出来。
合并前的最后关卡：审查、瘦身、安全、性能
代码离进主干只有一步之遥时，这四道关卡按顺序过。
五轴审查。code-review-and-quality 从正确性、可读性、架构、安全、性能五个轴过一遍。审批标准值得抄下来：只要这次改动确实提升了整体代码健康度就批准——完美代码不存在，目标只是持续改进。改动规模建议约 100 行，超过就拆；小标注（Nit/Optional/FYI）区分轻重，避免评审变成吹毛求疵大会。
不懂就别删。code-simplification 的第一原则是 Chesterton's Fence：看不见一道篱笆为什么存在时，先别拆它。简化必须保持行为逐字节一致，只删复杂度、不改行为。
先把攻击者想一遍。security-and-hardening 的立场：每个外部输入都是敌意的，每个密钥都是神圣的，每个鉴权检查都是强制的。动手前先花五分钟做威胁建模——画出信任边界（注意 LLM 输出也算一个常被漏掉的入口）、点名要保护的资产、对每条边界跑一遍 STRIDE 六问，然后给每个功能补一条"滥用用例"作为第一个测试。它引用的判断是：多数漏洞始于设计而非代码。
不给数据不优化。performance-optimization 开头就否掉"拍脑袋优化"：先测量 → 找到真实瓶颈 → 修 → 复测 → 加防回归监控，五步循环。核心 Web Vitals 达标线是 LCP ≤ 2.5s、INP ≤ 200ms、CLS ≤ 0.1，并且坚持两条腿走路：Lighthouse/DevTools 的合成数据用于回归定位，web-vitals/CrUX 的真实用户数据用于确认用户真的变快了。
上线那 48 小时：发布清单、CI/CD 与环境一致性
发布是可回滚、可观测、渐进式的。shipping-and-launch 把上线拆成清单加三段式：先过检查单（全量测试通过、构建无警告、无遗留 TODO 和调试语句、密钥没进仓库、依赖审计无高危、CORS 写死具体来源而不是通配符），再分阶段放量——feature flag 控制开关、小比例灰度、明确回滚触发条件。它信奉"快即安全"：含 3 个变更的部署远比含 30 个变更的部署好排查。
把检查焊死在流水线上。ci-cd-and-automation 让每个 PR 自动穿过质量门：lint → 类型检查 → 单测 → 构建，全绿才能合。两条理念支撑它——"左移"（在 lint 抓住的 bug 只花几分钟，在生产抓住要几小时，检查越往前放越便宜）和"小批量高频发布"（发布频率本身就是信心来源）。配套的失败反馈环要求流水线红了必须产生 actionable 的信息，而不是一枚红徽章。
别让环境差异吃掉你。同一技能里对多环境的要求是：开发、测试、生产之间配置保持一致，差异必须显式声明，而不是靠"在我机器上是好的"蒙混。环境漂移是线上事故里最廉价也最恶心的一类来源。
让项目活得更久：下线计划、ADR 与可观测性
上线不是终点，这组技能面向的是"三年后还有人（或 agent）要碰这个系统"的处境。
代码是负债，不是资产。deprecation-and-migration 的第一句就反直觉：每行代码都在持续收费——测试、安全补丁、依赖升级、新人的理解成本。Hyrum 定律解释了删除为什么难：用户最终会依赖所有可观察行为，包括你的 bug 和没写进文档的副作用。所以废弃不能只靠公告，得有主动迁移路径；而且下线规划要在设计新系统时就开始——"这套东西三年后怎么拆"应当是设计评审的固定问题。
把 why 写下来。documentation-and-adrs 的核心不是写更多文档，而是记录决策的 why：架构决策用 ADR 留档（背景、备选、为什么选它），API 变更和关键功能随船出文档。没有 why 的文档只是索引，有 why 的文档才能替代不在场的人。
埋探针要趁早。observability-and-instrumentation 要求可观测性在构建时就埋入而不是事后补：结构化日志、RED 指标、OpenTelemetry 链路追踪、基于症状（用户可感知异常）而非症状堆砌的告警。一个上线版系统如果没有这些，出事时你得到的只有一片"用户说它坏了"。
这套 agent-skills 技能库本身怎么用
上面 20 个技能有一个统一形态：每个都是工作流而非参考文档，包含触发条件、分步流程、一张"常见借口与反驳"表（比如"测试我回头再补"会被逐条驳回），以及硬性的验证出口——没有证据就不能宣布完成。
使用上有三条建议：
- 按需加载，别全塞。写 UI 就加载前端技能，修 bug 就加载调试技能；上下文不是越多越好，无关技能会稀释关键指令。
- 用 8 个斜杠命令当入口：/spec、/plan、/build、/test、/review、/code-simplify、/webperf、/ship，各自动激活对应技能。其中 /build auto 让你批准一次计划后由 agent 自主推进——但验证没被删：每个任务仍走测试驱动、单独提交，失败或高风险步骤会暂停。
- 起步只需要三个：spec-driven-development、test-driven-development、code-review-and-quality。这三个恰好堵住 AI 辅助开发最要命的三个缺口：先定义、再证明、后合入。
安装上两条路任选。通用装法一条命令：
npx skills add addyosmani/agent-skills这条命令把全部技能装入 70 多个主流 agent（Claude Code、Cursor、Codex、Copilot 等）。想自己掌控或按需裁剪，也可以直接克隆仓库再按工具接入：
git clone https://gitcode.com/GitHub_Trending/agentskill/agent-skills然后打开仓库里的入门文档 docs/getting-started.md，里面有各工具的接入方式和上下文加载策略。装完之后，下次任务来临时问自己一句"这是哪张牌"，答案就在那 20 个技能的触发条件里。
【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
