skills 仓库 ADR 解析为何/setup-matt-pocock-skills指针只为硬依赖技能保留【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skillsskills仓库Skills for Real Engineers源自 .agents 目录的技能集合中的工程类技能依赖一份按仓库隔离的配置——issue tracker、triage 标签词汇与领域文档布局它们由/setup-matt-pocock-skills一次性播种。本篇文章以 .agents/adr/0001-explicit-setup-pointer-only-for-hard-dependencies.md 这份架构决策记录ADR为主体拆解仓库如何把技能划分为“硬依赖”与“软依赖”两类解释为什么只有前者需要在技能正文里写死指向 setup 技能的提示语并给出相应的源码与配置证据。读完你将掌握这套依赖分类判据、提示语措辞规范以及如何在to-tickets、triage、to-spec等技能中验证这套设计。背景工程技能为什么需要 per-repo 配置仓库里的工程技能并非自包含的通用提示词它们依赖按仓库定制的配置而这份配置由setup-matt-pocock-skills播种见 skills/engineering/setup-matt-pocock-skills/SKILL.mdIssue tracker问题到底存放在哪里GitHub 默认本地 markdown 开箱即用GitLab 或自定义工作流亦可以及操作它的 CLIgh、glab或自由描述Triage 标签词汇五个规范 triage 角色needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix在目标 tracker 中对应的真实标签字符串领域文档布局CONTEXT.md与 ADR 存放在哪里、如何读取。关键差异在于有些技能在缺少这份配置时输出就是错的——它们必须把结果发布到特定 issue tracker、应用特定标签字符串否则产出无法落库另一些技能只是利用配置让输出更精准——缺少配置时依然能工作只是措辞不那么贴合项目词汇。ADR 原文用一句话点明了这种分化第 3 段Engineering skills depend on per-repo config … seeded by/setup-matt-pocock-skills. Some skills cannot meaningfully function without that config … Others only use it to sharpen output … and degrade gracefully without it.这正是把技能拆成两类、并决定“提示语写不写”的依据。两类依赖的判定标准与名单ADR第 5–8 行给出如下划分类别名单缺配置时的表现提示语策略硬依赖hard dependencyto-tickets、to-spec、triage输出错误而非仅仅含糊技能正文中包含一行显式提示… should have been provided to you; run/setup-matt-pocock-skillsif not.软依赖soft dependencydiagnose、tdd、improve-codebase-architecture仍然正常工作只是输出不那么精准只在行文中模糊引用项目的领域词汇表与你正在改动区域的 ADR三个硬依赖技能在 SKILL.md 中确实各自包含这一行提示to-ticketsThe issue tracker and triage label vocabulary should have been provided to you. If not, tell the user to run /setup-matt-pocock-skills.to-specThe issue tracker and triage label vocabulary should have been provided to you. If not, tell the user to run /setup-matt-pocock-skills.triageThese are canonical role names. The actual label strings used in the issue tracker may differ. The mapping should have been provided to you. If not, tell the user to run /setup-matt-pocock-skills.三个软依赖技能则只用宽松措辞引用配置diagnosing-bugs读CONTEXT.md若存在建立心智模型并检查正在改动区域的 ADRtdd读CONTEXT.md让测试命名与接口词汇贴合项目领域语言尊重改动区域的 ADRimprove-codebase-architecture先读领域词汇表CONTEXT.md与改动区域的 ADR。对比可见硬依赖技能把“配置应已提供给你”写成了强制前置软依赖技能则用“if it exists / if not”的容错语气配置缺了也不阻塞主流程。为什么这样划分正确性边界决定提示语是否“承重”ADR 第 10 行的落点句给出了设计动机The split keeps soft-dependency skills token-light and avoids cargo-culting the setup pointer into places where it isnt load-bearing.两层含义值得展开token-light节省上下文预算软依赖技能没有真正的配置缺口如果也写一行 setup 指针等于在每个技能里都重复一段与产出无关的指令白白占用模型上下文窗口。ADR 的取向是提示语是稀缺资源只用在能改变结果的地方。避免 cargo-culting防止仪式性复制如果把 setup 指针机械地复制到所有技能它就会变成一种“别人都这么写所以我这么写”的装饰读者以及模型无法从提示语本身判断它是否承重。ADR 要求提示语只在“load-bearing承重”的位置出现——即缺失它会导致错误输出的技能里。判断一个技能属于哪一类核心问题是配置缺失时输出是“错”还是“模糊”会错就是硬依赖只是变模糊就是软依赖。这套判据也帮助维护者在新技能加入时快速归类而不必逐个斟酌措辞。在硬依赖技能里验证这套设计to-tickets向配置的 tracker 发布阻塞边to-tickets的核心行为是“把计划/规格/对话拆成 tracer-bullet 垂直切片票据并把阻塞边发布到配置的 tracker”。发布环节的“怎么发”完全由/setup-matt-pocock-skills配置的 tracker 决定SKILL.md 第 60–67 行本地文件.scratch/feature-slug/issues/NN-slug.md每票据一个文件、从01起按依赖序编号Blocked by 引用前置票据编号真实 trackerGitHub、Linear 等按依赖序逐个发 issue优先使用平台原生 blocking / sub-issue 关系并默认打上ready-for-agent标签。注意“默认打ready-for-agent标签”这一动作如果标签词汇没有配置triage技能就会发明不存在的标签字符串。这正是 ADR 判定to-tickets为硬依赖的直接证据——它的输出发到哪个 tracker、打什么标签在缺少配置时是错误的而不是模糊的。to-spec发布规格到配置的 trackerto-spec不做访谈直接综合当前对话与代码库认知产出规格并发布到配置的 issue tracker、应用ready-for-agent标签。同样发布目标是配置决定的缺少配置时规格无处可去——硬依赖成立。triage标签字符串必须与 tracker 实际存在的一致triage定义五个规范状态角色needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix与两个类别角色bug、enhancement但强调“These are canonical role names. The actual label strings used in the issue tracker may differ.”。它只是把角色映射到 tracker 中真实存在的字符串而不负责创建标签——docs/engineering/setup-matt-pocock-skills.md 中明确“It doesnt rungh label create”。如果映射缺失triage会应用错误的标签导致 tracker 上出现重复或错误的标签集合输出同样从“错”起步。配置被写入哪里docs/agents/与指令文件setup-matt-pocock-skills将三类决策记录为 markdown 文件SKILL.md 第 104–112 行docs/agents/issue-tracker.md——GitHub / GitLab / 本地 markdown 三个模板分别为 issue-tracker-github.md、issue-tracker-gitlab.md、issue-tracker-local.mddocs/agents/domain.md——领域文档消费者规则与布局domain.mddocs/agents/triage-labels.md——仅当triage技能已安装时写入triage-labels.md。同时技能还会把## Agent skills块写入已存在的CLAUDE.md或AGENTS.md若都不存在则询问用户不替用户决定。这些文件是技能运行的输入硬依赖技能运行时读取docs/agents/issue-tracker.md决定发布方式读取triage-labels.md决定标签字符串软依赖技能则只读取domain.md指向的CONTEXT.md与 ADR。判定清单与扩展思考判据配置缺失时输出是“错”还是“模糊”——错则硬依赖模糊则软依赖。提示语硬依赖写一行显式指针“should have been provided to you; run/setup-matt-pocock-skillsif not.”软依赖只用“if exists / 相关区域 ADR”式宽松引用。验证检查to-tickets/to-spec/triage的 SKILL.md 是否含 setup 指针diagnosing-bugs/tdd/improve-codebase-architecture是否只有模糊引用。动机节省上下文 token避免把 setup 指针仪式化复制到不承重的位置。延伸思考基于仓库文档的公开讨论docs/engineering/setup-matt-pocock-skills.md记录了“是否应该有一个技能去配置其他技能”的长期争论having a skill to set up the other skill does not feel right to meADR 0001 的依赖分层其实正是对这一问题的一个侧面回答——不是让每个技能都重复“配置在哪”而是只让真正依赖配置的技能在关键时刻抛出 setup 指针其余技能保持轻量。这套思路对任何“带配置的技能集”类项目都有直接的借鉴价值。【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考