GitHub 工程技能包Engineering Skills完全指南一套面向 AI Agent 的端到端工程工作流【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills导读GitHub_Trending/skills13/skills仓库维护着作者日常编码时使用的一组 Agent 技能Skills其中skills/engineering/README.md是工程类技能的总索引它把从想法到上线的完整编码工作流拆解成一组可独立调用的技能并明确了每项技能何时被用户显式调用、何时由模型自动触发。读完本文你将掌握这套技能包的完整拓扑——主流程idea → ship、两条汇入主流程的入口on-ramps、底层共享词汇层、阶段边界处理策略以及triage、to-spec、to-tickets、implement、code-review、tdd等核心技能各自的职责、调用方式与底层设计原则并能直接在本仓库中查阅对应实现细节。一、技能包定位与仓库结构仓库根目录的README.md将自身定位为Skills for Real Engineers. Straight from my .agents directory——这些技能直接取自作者真实使用的.agents目录面向日常编码工作。工程类技能全部集中在 skills/engineering/ 下其 README 的定位是总索引 路由入口它本身不承载实现细节而是回答遇到什么情况该调哪个技能。每个技能是一个独立目录包含SKILL.md技能的完整定义以 YAML frontmattername、description、disable-model-invocation声明元数据正文描述调用流程agents/openai.yaml面向 Codex 等 OpenAI 系 Agent 的技能配置若干附属文档如PHASE-BOUNDARIES.md、AGENT-BRIEF.md、OUT-OF-SCOPE.md、HTML-REPORT.md等沉淀该技能的支撑材料。工程技能与productivity/如 grilling、grill-me、handoff、in-progress/、misc/技能共同构成完整体系而工程技能包是其中规模最大、流程化程度最高的一组。二、两种调用方式User-invoked 与 Model-invokedskills/engineering/README.md用一组前置条件将技能分为两类类别触发方式配置约定技能User-invoked仅当用户显式输入技能名时才可到达Claude Code 中disable-model-invocation: trueCodex 中agents/openai.yaml的policy.allow_implicit_invocation: falseask-matt、grill-with-docs、triage、improve-codebase-architecture、setup-matt-pocock-skills、to-spec、to-tickets、implement、wayfinderModel-invoked模型可自动触达也可由用户调用采用丰富的触发措辞rich trigger phrasing让模型能识别何时该使用prototype、diagnosing-bugs、research、tdd、domain-modeling、codebase-design、code-review、resolving-merge-conflicts、wizard这一区分是整套设计的核心决策流程性、状态性强的技能如 grilling 访谈、ticket 拆分必须由人显式发起避免模型擅自启动重型流程词汇性、参考性、诊断性技能如 tdd 的红绿循环、domain-modeling 的术语校准则允许模型自动触达因为它们往往是其他流程的内部组件。可以在任意一个SKILL.md的 frontmatter 中验证该约定例如 ask-matt/SKILL.md 声明了disable-model-invocation: true。三、主流程idea → ship想法到上线ask-matt技能skills/engineering/ask-matt/SKILL.md扮演整套技能包的路由器它开篇就点明一个事实你不会记得每一个技能所以问。它把大多数工作经过的路径总结为一条主流程加两条汇入的 on-ramps主流程的三个步骤/grill-with-docs打磨想法只要你在一个工作目录中工作都从这里开始。它通过一轮轮访谈把模糊的想法问清楚并且是有状态的——会把学到的内容沉淀进CONTEXT.md和 ADR 中留下纸面痕迹。若当前没有工作目录则改用productivity包中的/grill-me无状态版本。两者底层都运行同一个/grilling原语区别仅在是否留痕。分支判断所有问题都能在对话中解决吗如果某个问题需要可运行的答案状态、业务逻辑、必须亲眼看效果的 UI就绕道/prototype用/handoff双向桥接——prototype 住在自己的独立目录里这正是/handoff的用途先/handoff出去在新会话中/prototype再把结论/handoff回来并引用回原想法线程。阶段边界细节见 PHASE-BOUNDARIES.md。分支判断这是多会话构建吗是→/to-spec把对话变成 spec再/to-tickets拆成一组曳光弹tracer-bullet工单每个工单声明自己的blocking edges阻塞边。本地追踪器上每个工单是.scratch/feature/issues/下的一个文件按依赖顺序手工推进真实追踪器上边会变成原生的阻塞链接任何阻塞项已完成的工单都可以被认领。随后对每个工单启动/implement每个工单之间用/clear清空上下文——因为每个工单自包含最后一个工单的上下文可以丢弃。否→ 直接在同一个上下文窗口里/implement。无论哪条路/implement内部都会驱动/tdd一个红绿切片接一个提交前用/code-review做双轴审查收尾。上下文卫生Context hygiene步骤 1–3 应保持在一个不中断的上下文窗口内在/to-tickets之前不要 compact 或 clear让 grilling、spec、tickets 都建立在同一份思考上每次/implement则从工单重新开始。其上限是所谓的智能区约 150k token模型仍能清晰推理的窗口——会话逼近上限时不要在退化状态下硬撑应在最近的阶段边界处/compact继续。阶段边界Phase boundaries两个阶段之间如 grilling 与实现之间有五个选项选择它们是整张地图中最模糊的决策选项适用场景Continue留在原地零成本零损失是应该最先排除的那个/clear清空窗口当当前内容对下一步毫无价值时/handoff写一个可移植的 markdown 文件仅用于新的 harness、新目录、同事或阶段中分叉子任务Subagent把边界清晰的任务送到独立窗口并取回报告/compact压缩当前上下文并用它播种新会话是树底的默认项决策必须在边界处做出阶段中途则继续推进或把剩余部分拆给 subagent。四、两条 On-ramps从异常状况汇入主流程主流程默认从已有想法起步但现实工作常以异常状况开场Bug 与请求堆积→/triage。它把 issue 沿着一组 triage 角色状态机推进产出 agent-ready 的 issue之后由/implement认领。注意边界triage只处理非你创建的 issuebug 报告、外来功能请求/to-tickets产出的工单已 agent-ready不需要 triage。某处坏了→/diagnosing-bugs。用于那些第一眼看不穿、间歇性 flake、两个已知良好状态之间混入的回归。它坚持在建立紧致反馈环一条已经能在这个 bug 上变红的命令之前不空谈理论然后带回归测试修复。事后复盘post-mortem若发现真正问题是没有好的 seam 来锁死 bug则移交给/improve-codebase-architecture。巨大的、迷雾般的工作greenfield 项目或超大功能一个会话装不下→/wayfinder这是整套体系里认知负担最重的流程。它在 issue tracker 上绘制一张由决策工单decision tickets组成的共享地图逐个解决产出的是决策而非交付物直到迷雾被推开、道路清晰。当grill-with-docs处理的是一个会话内能握住的想法时wayfinder 处理的是握不住的想法因此更慢更稠密只为这类场景保留。关键约束地图清晰后 wayfinder 是移交而非构建——它汇入主流程的/to-spec由 spec 把地图上相互链接的决策折叠成一个可构建的计划再走/to-tickets和/implement。直接把地图循环进/implement会丢弃折叠后的链接细节只有当工作确实很小才可以这么做。五、代码库健康与底层词汇层代码库健康Codebase health/improve-codebase-architecture在你有零碎时间时运行用来保持代码库对 Agent 友好。它扫描出deepening opportunities深化机会选中一个机会就生成一个想法可带入主流程的/grill-with-docs。它是发现候选对象的勘察而/codebase-design是设计选中对象的工作台。底层词汇Vocabulary underneath两个 model-invoked 的参考技能运行在其他技能之下各自是其词汇的唯一真源。当问题出在词而不是流程上时直接调用它们/domain-modeling打磨项目的领域语言——质疑模糊术语、解决一词多义如account身兼三种职责、把难以逆转的决策记录为 ADR。它是grill-with-docs驱动CONTEXT.md保持干净词汇表的主动纪律。/codebase-design深层模块的词汇表module、interface、depth、seam、adapter、leverage、locality用于设计模块的形状大量行为藏在干净 seam 上的一小个接口之后。tdd与improve-codebase-architecture都使用这套语言。六、核心技能逐个拆解6.1 grill-with-docs会留下文档的拷问式访谈grill-with-docs/SKILL.md 的正文极简但点明了它的实现方式调用 Skill 工具两次分别传入grilling和domain-modeling。也就是说它由两个底层原语组合而成——/grilling提供多轮访谈、前沿推进、事实是 Agent 的职责而决策是你的职责的访谈机制/domain-modeling在访谈过程中同步校准术语并内联更新CONTEXT.md与 ADR。这正是它比grill-me更优的原因同样的访谈却留下了纸面痕迹。6.2 triage角色状态机驱动的 issue 分流triage/SKILL.md 定义了一个清晰的状态机两个分类角色bug坏了与enhancement新功能或改进五个状态角色needs-triage等待维护者评估、needs-info等待报告者补充信息、ready-for-agent规格完整可交给 AFK 的 Agent、ready-for-human需人工实现、wontfix不予处理。每个被 triage 的 issue 必须且只能携带一个分类角色和一个状态角色状态角色冲突时先标记并向维护者确认。PR 被视作附着代码的 issue复用同一状态机对 PR 而言ready-for-agent表示附带了 brief 且 Agent 应对 diff 迈出下一步ready-for-human表示可人工合并。triage 的完整流程包括收集上下文读完整 issue/PR检查冗余实现与.out-of-scope/中的既往拒绝记录→给出建议分类状态理由等待指示→验证声明对 bug 按报告者步骤复现对 PR 检出并跑测试→必要时 grilling再次调用grilling与domain-modeling两个 Skill→应用结果发布 agent brief、needs-info 模板或关闭。所有 AI 生成的三方评论必须以 *This was generated by AI during triage.*开头。详细规范见 AGENT-BRIEF.md 与 OUT-OF-SCOPE.md。6.3 to-spec把对话合成规格书to-spec/SKILL.md 明确不要访谈用户只综合你已经知道的内容——它是对话的蒸馏而非新一轮提问。核心过程探索代码库现状 →勾画测试 seam优先复用既有 seam尽量用最高层 seam理想数量是一个并需与用户确认→ 按模板写 spec 并发布到 issue tracker直接打上ready-for-agent标签无需额外 triage。模板包含七个部分Problem Statement用户视角的问题、Solution用户视角的解决方案、User Stories极长的编号列表格式为As an actor, I want a feature, so that benefit、Implementation Decisions不含具体文件路径与代码片段因为会很快过时prototype 产出的状态机/reducer/schema 等精炼片段是例外可内联并注明来源、Testing Decisions好测试的定义、被测模块、先例、Out of Scope、Further Notes。6.4 to-tickets拆成声明阻塞边的曳光弹工单to-tickets/SKILL.md 把计划/spec/对话拆成一组**垂直切片vertical slices**工单每条切片规则苛刻每个切片垂直贯穿所有层schema、API、UI、测试而非某一层的水平切片完成的切片可独立 demo 或验证每个切片大小适合一个全新的上下文窗口任何预重构prefactoring先行。每个工单声明它的blocking edges无阻塞的工单可立即开始始终推进前沿frontier——那些阻塞项全部完成的工单。宽重构wide refactor是垂直切片的例外当一次机械改动如重命名列、重打类型的爆炸半径blast radius横扫整个代码库时不要强行塞进曳光弹而应按expand–contract排序——先 expand新旧形式并存不破坏任何东西再按爆炸半径分批迁移调用点每批一个工单阻塞于 expand最后 contract无调用者后删除旧形式。分批仍无法单独保持 CI 绿时让各批共享一个集成分支最终由集成与验证工单承诺绿色。发布形态取决于setup-matt-pocock-skills配置的追踪器本地文件形态是.scratch/feature-slug/issues/NN-slug.md一个工单一个文件按依赖顺序从01编号真实追踪器GitHub、Linear 等则按依赖顺序逐个发布优先使用平台原生的 blocking/sub-issue 关系。两种形态都附带了完整的工单模板What to build、Blocked by、Status: ready-for-agent、Acceptance criteria勾选列表。6.5 implement按 spec/工单构建implement/SKILL.md 简短却定义了执行纪律在预先约定的 seam 上尽可能使用/tdd定期跑类型检查与单个测试文件最后跑一次完整测试套件完成后用/code-review审查提交到当前分支。6.6 tdd红绿重构循环的参考tdd/SKILL.md 是让红绿循环产出值得保留的测试的参考。核心内容好测试的标准通过公共接口验证行为而非实现细节读起来像规格书Seam接缝测试所在的位置只在预先约定的 seam 上测试——写任何测试前先写下被测 seam 并与用户确认无确认的 seam 不写测试三大反模式实现耦合测试因重构而碎但行为未变、同义反复断言用与代码相同的方式重算期望值永远不可能失败、水平切片先写完所有测试再写实现测试的是想象中的行为循环规则先红后绿先写失败测试再写恰好通过的代码、一次一个切片一个 seam、一个测试、一个最小实现、重构不属于循环它属于 review 阶段。配套的 tests.md 与 mocking.md 提供了测试示例与 mock 指南。6.7 code-review双轴并行审查code-review/SKILL.md 审查自固定点commit、分支、tag 或 merge-base以来的 diff沿两个独立轴进行由并行 sub-agent执行以避免相互污染上下文Standards 轴代码是否符合仓库记录的编码标准除了仓库文档永远叠加一份Fowler 坏味道基线源自《重构》第 3 章共 12 项Mysterious Name、Duplicated Code、Feature Envy、Data Clumps、Primitive Obsession、Repeated Switches、Shotgun Surgery、Divergent Change、Speculative Generality、Message Chains、Middle Man、Refused Bequest。两条约束仓库标准优先仓库背书的东西不报每项坏味道都是带标签的启发式而非硬性违规。Spec 轴代码是否忠实实现了来源 issue/spec按提交信息中的 issue 引用 → 用户传入的路径 → docs/specs/.scratch 下匹配的 spec 文件的顺序定位 spec找不到则询问用户确实没有则跳过并注明。两轴各自报告、绝不合并或重排结尾各给一行汇总每轴的总发现数与最严重问题因为分离的意义就在于防止一轴掩盖另一轴——符合全部标准但实现错了东西Standards 过、Spec 挂与完全按 issue 做了但破坏约定Spec 过、Standards 挂必须同时可见。6.8 domain-modeling领域模型的主动打磨domain-modeling/SKILL.md 定义了文件结构与会话纪律。文件结构上单上下文仓库为根目录CONTEXT.mddocs/adr/多上下文仓库由根目录CONTEXT-MAP.md指向各子上下文每处有自己的CONTEXT.md与docs/adr/。文件懒创建第一次术语落定才建CONTEXT.md第一个 ADR 需要时才建docs/adr/。会话中要做对照词汇表质疑冲突术语、为模糊/过载的用词提出精确规范术语、用具体场景压测领域关系、与代码交叉验证你的代码取消了整个 Order但你刚才说支持部分取消哪个是对的、术语落定时立即内联更新CONTEXT.md格式见 CONTEXT-FORMAT.md且CONTEXT.md必须是纯词汇表不得混入实现细节以及克制地提供 ADR——只有同时满足三个条件才创建难以逆转、缺乏上下文会令人费解、真实权衡的结果格式见 ADR-FORMAT.md。6.9 codebase-design深层模块的共享词汇codebase-design/SKILL.md 的核心信条是深层模块 小接口 大量实现少数方法、简单参数、内部藏更多复杂性避开浅层模块大接口 薄实现。它的词汇表刻意精确、禁止用 component/service/API/boundary 混用术语定义禁用替身Module任何有接口和实现的东西规模无关函数、类、包、跨层切片unit、component、serviceInterface调用者正确使用模块所需知道的一切类型签名 不变量 顺序约束 错误模式 配置 性能特征API、signatureDepth接口处的杠杆每单位接口可施展的行为量—SeamMichael Feathers不就地编辑即可改变行为的位置即模块接口所在处boundaryAdapter在 seam 处满足接口的具体东西描述角色而非实质—Leverage调用者从深度得到的一份实现回馈 N 个调用点与 M 个测试—Locality维护者从深度得到的变更、bug、知识与验证集中在一处—它追求三重目标调用者的 leverage、维护者的 locality、所有人的可测试性。6.10 其余技能速览improve-codebase-architecture扫描代码库中的架构摩擦并给出深化机会。先定范围YAGNI优先近期变更的热点区域sub-agent 有机漫步找摩擦点用**删除测试deletion test**验证删除它会集中复杂度还是只是搬移。候选结果渲染成自包含 HTML 报告Tailwind Mermaid via CDN每项候选带 before/after 可视化与Strong/Worth exploring/Speculative强度徽章写入$TMPDIR或/tmp、%TEMP%下的architecture-review-timestamp.html并自动打开不在这一步提出接口设计而是先问用户想探索哪一项。完整 HTML 脚手架见 HTML-REPORT.md。wayfinder以wayfinder:map标签的单个 issue 作为地图索引而非存储每项决策只存在于其工单中子工单每次会话体量约 100K token按目的地 → Notes → Decisions so far → Not yet specified → Out of scope结构组织所有引用按名称标题而非裸编号因为一面 #42、#43、#44 的墙无法阅读。resolving-merge-conflicts逐 hunk 处理进行中的 merge/rebase 冲突按意图追溯到双方各自的一手来源解决而非挑行最后完成操作绝不--abort。prototype一次性小程序回答一个设计问题。可抛弃是书写约束而非销毁承诺——答案会折回真实代码原型作为一手来源保存在 main 之外的一个prototype/name分支上由实现 issue 指向它。diagnosing-bugs纪律化的诊断循环见第四节 on-ramp。research把阅读苦力委托给后台 Agent它对照一手来源调研并把带引用的 Markdown 文件留在仓库里你继续工作。产物是带入/grill-with-docs的素材研究喂养思考而非替代思考。wizard为只有人类能执行的步骤生成交互式 bash 向导开通基础设施、配置凭据/CI 密钥、操作陌生第三方面板、执行一次性迁移/切换。模型在遇到只有你能越过的墙时自动触达它。七、前置条件setup-matt-pocock-skills所有工程流程都假定仓库已配置好 issue tracker、triage 标签词汇与文档布局。skills/engineering/README.md的 Precondition 章节以及to-spec、to-tickets、triage、code-review、wayfinder多个技能中反复出现的如果未提供告诉用户运行/setup-matt-pocock-skills都指向这一技能在每个仓库上运行一次。它支持自定义 issue tracker并提供多种内置形态的参考文档包括 issue-tracker-github.md、issue-tracker-gitlab.md、issue-tracker-local.md、triage-labels.md 与 domain.md涵盖从本地 markdown 文件追踪到 GitHub/GitLab 原生追踪的完整光谱。八、设计哲学为什么这样编排纵观整套工程技能包可以提炼出几条贯穿始终的设计原则技能是组合的不是孤立的grill-with-docsgrillingdomain-modelingimplement内部驱动tdd、收尾于code-reviewto-spec与to-tickets串成多会话流水线。每个 SKILL.md 的 frontmatter 与正文都显式声明了它依赖的底层技能。状态有明确的归属CONTEXT.md与 ADR 是领域知识的唯一落点工单是待办决策的落点handoff文件是跨会话/跨目录的可移植载体。技能之间通过这些文件交接而非依靠 Agent 的记忆。上下文窗口是稀缺资源一切流程围绕它设计工单按一个新鲜上下文窗口定尺寸、每个/implement从工单冷启动、阶段边界提供 Continue/clear/handoff/subagent/compact 五种转移选项、智能区约 150k token作为硬约束。人始终在环上triage 的每个状态变化都要确认、to-tickets的粒度与阻塞边要逐项过审、wizard明确为只有人类能做的步骤而生——Agent 负责事实与执行人类负责决策。从源码结构看skills/engineering/README.md承担的是总路由角色真正的流程细节分布在各子目录的SKILL.md中若要在自己的仓库中复刻这套体系建议从阅读 ask-matt/SKILL.md整张地图的说明文档与 PHASE-BOUNDARIES.md边界决策树开始再沿着 README 索引逐技能展开。【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考