mattpocock-skills标准化跨 Skill 调用术语——Call the Skill tool 约定及其双 Harness 实践【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills这篇指南基于仓库中的 changeset 文档 .changeset/skill-tool-invocation-terminology.md 展开讲解 mattpocock-skills 如何把各 Skill 之间调用另一个 Skill的指令从裸写的/skill风格散文统一为显式的 Call the Skill tool 表述。读完后你能理解为什么在文字里提到另一个 Skill 名字并不可靠、如何书写多 Skill 步骤、以及该约定在 Claude Code 与 Codex 双 Harness 下如何保持中立并掌握在.agents/invocation.md中沉淀的完整书写规范。变更背景这是一个什么改动该文件是一个 changeset变更描述片frontmatter 中声明了对mattpocock-skills包的 patch 级修改mattpocock-skills: patchchangeset 主体一句话概括了改动范围在code-review、diagnosing-bugs、grill-with-docs、grill-me、improve-codebase-architecture、tdd、to-spec、to-tickets、triage和wayfinder这 10 个 Skill 中把跨 Skill 调用统一为显式的 call the Skill tool 指令替代原来裸写的/skill风格散文。仓库使用.changeset/目录按一个文件一个变更的方式记录每次 patch/minor 修改由工具汇总进 CHANGELOG.md。这个 changeset 与另一个 changeset user-invoked-skill-invocation.md 是同一批工作的两部分前者建立怎么调的术语标准后者修复什么不能调的边界违规。问题根源散文里提到 Skill 名字不等于调用了它changeset 第一条给出了改动的技术动机原文明确承认了旧写法是一个有文档记录的粗糙边缘A skill that names another skill in prose (run the/grillingskill) does not reliably cause it to load. This is the documented rough edge behindgrill-with-docss most-reported problem.也就是说一个 Skill 若在正文里只写运行/grillingskill并不保证该 Skill 真正被加载——这正是grill-with-docs用户反馈最多的问题根源。grill-with-docs的整个实现就是委托给两个底层 Skill一旦委托失败用户看到的就是一次空转的面试流程。其底层原因在于大多数 harnessagent 运行框架把 Skill 调用暴露为一个工具模型必须真正去 call 这个工具才能触发加载。把/name当作普通文字丢进散文里是在希望模型把它读成命令——命中率不稳定。而直接点名工具Call the Skill tool with grilling把意图写得没有歧义changeset 原话是 is intended to raise the hit rate旨在提高命中率。约定本体显式点名 Skill 工具改动落地的写法是让 Skill 的正文用指令句式直接命名 Skill 工具而不是使用 slash-command 风格的名字。仓库中改动后的真实用例如下grill-me/SKILL.md 全文正文只有一行Call the Skill tool with grilling.grill-with-docs/SKILL.md 的正文Call the Skill tool twice, for grilling and domain-modeling.wayfinder/SKILL.md 的第一步命名目的地Call the Skill tool twice, for grilling and domain-modeling, to pin down what this map is finding its way to: the spec, decision, or change.improve-codebase-architecture/SKILL.md 中出现了两处调用一处是获取架构词汇表module、interface、depth、seam、adapter、leverage、locality另一处是指向 design-it-twice 的并行子代理模式Call the Skill tool with codebase-design for the architecture vocabulary ...Want to explore alternative interfaces for the deepened module?Call the Skill tool with codebase-design and use its design-it-twice parallel sub-agent pattern.retro/SKILL.md 的第一步Call the Skill tool withwriting-for-agentsfor the writing style guide.这些例子展示了约定的三个要点句式固定Call the Skill tool with ... 是一个可被模型无歧义执行的操作性指令而非描述性文字Skill 名字放在引号中作为参数与 slash-command 语法解耦调用发生在 Skill 自身的步骤里即 changeset 所指的 operative instructions操作性指令——Skill 的步骤正告诉 agent 现在就去运行另一个 Skill。去掉前导斜杠harness 中立而非降低要求changeset 第二条值得单独展开Dropping the leading/also makes the instruction harness-neutral rather than less: it no longer assumes Claude Codes trigger syntax.这是一个容易被误读的设计决策。表面上从/grilling到grilling像是丢掉了信息实际上恰恰相反——/name这种前缀假设了 Claude Code 的触发语法而 mattpocock-skills 同时支持多个 harness。从仓库结构看每个 Skill 都带有一份 agents/openai.yamlCodex 侧的元数据与 Claude Code 的 frontmatter 并行存在CHANGELOG.md 中 1.2.0 版本记录了这个双 harness 设计每个 user-invoked Skill 在 Claude Code 侧用disable-model-invocation: truefrontmatter在 Codex 侧用policy.allow_implicit_invocation: falseagents/openai.yaml标记两侧语义必须保持同步。既然 Skill 集合要在两种及未来更多harness 上运行正文里的指令就不能绑定任何一方的触发语法。裸 Skill 名字本身不携带 harness 假设这就是 changeset 里 harness-neutralrather than less 的含义中立性不是信息的减少而是信息密度的提升。同一批变更中还有同类动作的佐证——CHANGELOG.md 1.2.3 版本记录了从子代理分派指令中移除 Claude Code 专属的工具名和 agent 类型名使步骤在 Codex 等其他 harness 上同样可执行。多 Skill 步骤一次调用只带一个名字changeset 第三条规定了组合调用的写法A step needing more than one skill now says so as multiple calls (Call the Skill tool twice, forgrillinganddomain-modeling), not one call carrying two names.规范文档.agents/invocation.md对此给出了原理性解释Skill 工具一次调用只接收一个 Skill。需要两个 Skill 的步骤必须写成两次调用。原因很实际——措辞会引导模型的解析call it with X and Y 读起来像一次调用携带两个名字而Call the Skill tool twice, for grilling and domain-modeling在字面上就是一次动作发生两次模型没有歧义可犯。grill-with-docs是这个规则最典型的受益者它作为 user-invoked 的带文档版面试其全部行为就是依次加载grilling面试原语和domain-modeling领域建模纪律两个 model-invoked Skill并把产出沉淀为CONTEXT.md和 ADR。一行正文、两次显式调用委托链完全可预期。边界该约定只适用于 model-invoked 的 Skill写跨 Skill 调用指令时最容易被忽略的是被调方是否可达。.agents/invocation.md把 Skill 按谁能触达分成两类User-invoked只有人能触发。Claude Code 侧在 frontmatter 中设disable-model-invocation: trueCodex 侧在agents/openai.yaml中设policy.allow_implicit_invocation: falseModel-invoked模型和人都能触达是默认状态。description保留丰富的触发短语Use when the user wants…, mentions…, asks for…以便自动触发。不变式是任何 Skill 都永远无法触达另一个 user-invoked Skill——每个 harness 都会把 user-invoked Skill 排除在模型触达范围之外。因此Call the Skill tool with name约定只在被点名 Skill 是 model-invoked 时成立。这条边界在仓库中留下了真实的历史教训见配套 changeset user-invoked-skill-invocation.mdPR #878 引入本约定时曾把to-spec、wayfinder、to-tickets、triage、code-review五个 Skill 中如果没有配置运行/setup-matt-pocock-skills的前置条件机械地改写成了字面的Call the Skill tool with setup-matt-pocock-skills指令——但setup-matt-pocock-skills是 user-invoked 的这种调用必然失败其中diagnosing-bugs的失败更危险因为它发生在无人值守的自主修 bug 流程里。修复方式是把这些前置条件全部改写成告知人类去运行的指令例如 to-spec/SKILL.md 与 code-review/SKILL.md 中的The issue tracker should have been provided to you. If not, tell the user to run/setup-matt-pocock-skills.注意这里的/setup-matt-pocock-skills保留了前导斜杠因为它不是操作性调用指令而是给人类看的、在终端里要实际敲出的 slash command。.agents/invocation.md对两者的区分写得很清楚When a steps precondition is a user-invoked skill (e.g.setup-matt-pocock-skills), phrase it as an instruction for the human to act on: tell the user to run/setup-matt-pocock-skills, never as a Skill tool call.相应地该文档也在 Dependencies between them 一节补充了 carve-out豁免段落声明 Skill 工具约定仅适用于 model-invoked Skill。该 changeset 还点出了教训的另一层规范文档与八行之外的不变式没有对齐正是这个 bug 扩散到六处调用点而非一处的主因。约定文档化.agents/invocation.md的完整规则changeset 的最后一项是把整套约定写入.agents/invocation.md供后续新 Skill 遵循。除前文引用的四条点名工具、多调用写法、user-invoked 豁免、harness 中立外该文档还有两条与何时该调用、何时不该调用相关的细则值得纳入写作规范操作性指令 vs 路由性文字只有 Skill 自身步骤中现在就让我去运行另一个 Skill的指令才使用 Skill 工具句式而给人类做选择的导航文字如 ask-matt/SKILL.md 和各桶 README只是把 Skill 名字当标签列出保留/skill风格即可它们不构成调用被动阅读 vs 主动建模仅仅是读一下CONTEXT.md查词汇只是一行散文指引不等于调用domain-modeling。只有主动的构建/打磨纪律——质疑术语、用边界场景压测、写 ADR、内联更新CONTEXT.md——才算domain-modeling的调用。这防止了因为提到了某个词就顺手调了重型 Skill的过度触发。小结把希望模型看懂变成模型只能这样执行这个 patch 级的术语变更没有新增任何 Skill改的只是一批SKILL.md正文的措辞但它确立的是一条可复制的写作原则适用于任何由多个 Skill/命令/工具协作组成的 agent 技能库委托必须点名机制本身Call the Skill tool with X而不是描述性散文run the/grillingskill一次调用一个名字多 Skill 步骤显式写成多次调用名字不携带 harness 假设去掉与特定框架绑定的前缀语法写之前先核对调用边界user-invoked 的能力只能转化为告知人类去做的指令永远不能写成工具调用。配套的验收标准也很直接在仓库内全文检索Call the Skill tool应当只命中操作性调用点且每一处被点名的 Skill 都是 model-invoked——这一条可以在.agents/invocation.md的不变式对照下逐条核验。【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 mattpocock-skills：标准化跨 Skill 调用术语——“Call the Skill tool“ 约定及其双 Harness 实践
mattpocock-skills标准化跨 Skill 调用术语——Call the Skill tool 约定及其双 Harness 实践【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills这篇指南基于仓库中的 changeset 文档 .changeset/skill-tool-invocation-terminology.md 展开讲解 mattpocock-skills 如何把各 Skill 之间调用另一个 Skill的指令从裸写的/skill风格散文统一为显式的 Call the Skill tool 表述。读完后你能理解为什么在文字里提到另一个 Skill 名字并不可靠、如何书写多 Skill 步骤、以及该约定在 Claude Code 与 Codex 双 Harness 下如何保持中立并掌握在.agents/invocation.md中沉淀的完整书写规范。变更背景这是一个什么改动该文件是一个 changeset变更描述片frontmatter 中声明了对mattpocock-skills包的 patch 级修改mattpocock-skills: patchchangeset 主体一句话概括了改动范围在code-review、diagnosing-bugs、grill-with-docs、grill-me、improve-codebase-architecture、tdd、to-spec、to-tickets、triage和wayfinder这 10 个 Skill 中把跨 Skill 调用统一为显式的 call the Skill tool 指令替代原来裸写的/skill风格散文。仓库使用.changeset/目录按一个文件一个变更的方式记录每次 patch/minor 修改由工具汇总进 CHANGELOG.md。这个 changeset 与另一个 changeset user-invoked-skill-invocation.md 是同一批工作的两部分前者建立怎么调的术语标准后者修复什么不能调的边界违规。问题根源散文里提到 Skill 名字不等于调用了它changeset 第一条给出了改动的技术动机原文明确承认了旧写法是一个有文档记录的粗糙边缘A skill that names another skill in prose (run the/grillingskill) does not reliably cause it to load. This is the documented rough edge behindgrill-with-docss most-reported problem.也就是说一个 Skill 若在正文里只写运行/grillingskill并不保证该 Skill 真正被加载——这正是grill-with-docs用户反馈最多的问题根源。grill-with-docs的整个实现就是委托给两个底层 Skill一旦委托失败用户看到的就是一次空转的面试流程。其底层原因在于大多数 harnessagent 运行框架把 Skill 调用暴露为一个工具模型必须真正去 call 这个工具才能触发加载。把/name当作普通文字丢进散文里是在希望模型把它读成命令——命中率不稳定。而直接点名工具Call the Skill tool with grilling把意图写得没有歧义changeset 原话是 is intended to raise the hit rate旨在提高命中率。约定本体显式点名 Skill 工具改动落地的写法是让 Skill 的正文用指令句式直接命名 Skill 工具而不是使用 slash-command 风格的名字。仓库中改动后的真实用例如下grill-me/SKILL.md 全文正文只有一行Call the Skill tool with grilling.grill-with-docs/SKILL.md 的正文Call the Skill tool twice, for grilling and domain-modeling.wayfinder/SKILL.md 的第一步命名目的地Call the Skill tool twice, for grilling and domain-modeling, to pin down what this map is finding its way to: the spec, decision, or change.improve-codebase-architecture/SKILL.md 中出现了两处调用一处是获取架构词汇表module、interface、depth、seam、adapter、leverage、locality另一处是指向 design-it-twice 的并行子代理模式Call the Skill tool with codebase-design for the architecture vocabulary ...Want to explore alternative interfaces for the deepened module?Call the Skill tool with codebase-design and use its design-it-twice parallel sub-agent pattern.retro/SKILL.md 的第一步Call the Skill tool withwriting-for-agentsfor the writing style guide.这些例子展示了约定的三个要点句式固定Call the Skill tool with ... 是一个可被模型无歧义执行的操作性指令而非描述性文字Skill 名字放在引号中作为参数与 slash-command 语法解耦调用发生在 Skill 自身的步骤里即 changeset 所指的 operative instructions操作性指令——Skill 的步骤正告诉 agent 现在就去运行另一个 Skill。去掉前导斜杠harness 中立而非降低要求changeset 第二条值得单独展开Dropping the leading/also makes the instruction harness-neutral rather than less: it no longer assumes Claude Codes trigger syntax.这是一个容易被误读的设计决策。表面上从/grilling到grilling像是丢掉了信息实际上恰恰相反——/name这种前缀假设了 Claude Code 的触发语法而 mattpocock-skills 同时支持多个 harness。从仓库结构看每个 Skill 都带有一份 agents/openai.yamlCodex 侧的元数据与 Claude Code 的 frontmatter 并行存在CHANGELOG.md 中 1.2.0 版本记录了这个双 harness 设计每个 user-invoked Skill 在 Claude Code 侧用disable-model-invocation: truefrontmatter在 Codex 侧用policy.allow_implicit_invocation: falseagents/openai.yaml标记两侧语义必须保持同步。既然 Skill 集合要在两种及未来更多harness 上运行正文里的指令就不能绑定任何一方的触发语法。裸 Skill 名字本身不携带 harness 假设这就是 changeset 里 harness-neutralrather than less 的含义中立性不是信息的减少而是信息密度的提升。同一批变更中还有同类动作的佐证——CHANGELOG.md 1.2.3 版本记录了从子代理分派指令中移除 Claude Code 专属的工具名和 agent 类型名使步骤在 Codex 等其他 harness 上同样可执行。多 Skill 步骤一次调用只带一个名字changeset 第三条规定了组合调用的写法A step needing more than one skill now says so as multiple calls (Call the Skill tool twice, forgrillinganddomain-modeling), not one call carrying two names.规范文档.agents/invocation.md对此给出了原理性解释Skill 工具一次调用只接收一个 Skill。需要两个 Skill 的步骤必须写成两次调用。原因很实际——措辞会引导模型的解析call it with X and Y 读起来像一次调用携带两个名字而Call the Skill tool twice, for grilling and domain-modeling在字面上就是一次动作发生两次模型没有歧义可犯。grill-with-docs是这个规则最典型的受益者它作为 user-invoked 的带文档版面试其全部行为就是依次加载grilling面试原语和domain-modeling领域建模纪律两个 model-invoked Skill并把产出沉淀为CONTEXT.md和 ADR。一行正文、两次显式调用委托链完全可预期。边界该约定只适用于 model-invoked 的 Skill写跨 Skill 调用指令时最容易被忽略的是被调方是否可达。.agents/invocation.md把 Skill 按谁能触达分成两类User-invoked只有人能触发。Claude Code 侧在 frontmatter 中设disable-model-invocation: trueCodex 侧在agents/openai.yaml中设policy.allow_implicit_invocation: falseModel-invoked模型和人都能触达是默认状态。description保留丰富的触发短语Use when the user wants…, mentions…, asks for…以便自动触发。不变式是任何 Skill 都永远无法触达另一个 user-invoked Skill——每个 harness 都会把 user-invoked Skill 排除在模型触达范围之外。因此Call the Skill tool with name约定只在被点名 Skill 是 model-invoked 时成立。这条边界在仓库中留下了真实的历史教训见配套 changeset user-invoked-skill-invocation.mdPR #878 引入本约定时曾把to-spec、wayfinder、to-tickets、triage、code-review五个 Skill 中如果没有配置运行/setup-matt-pocock-skills的前置条件机械地改写成了字面的Call the Skill tool with setup-matt-pocock-skills指令——但setup-matt-pocock-skills是 user-invoked 的这种调用必然失败其中diagnosing-bugs的失败更危险因为它发生在无人值守的自主修 bug 流程里。修复方式是把这些前置条件全部改写成告知人类去运行的指令例如 to-spec/SKILL.md 与 code-review/SKILL.md 中的The issue tracker should have been provided to you. If not, tell the user to run/setup-matt-pocock-skills.注意这里的/setup-matt-pocock-skills保留了前导斜杠因为它不是操作性调用指令而是给人类看的、在终端里要实际敲出的 slash command。.agents/invocation.md对两者的区分写得很清楚When a steps precondition is a user-invoked skill (e.g.setup-matt-pocock-skills), phrase it as an instruction for the human to act on: tell the user to run/setup-matt-pocock-skills, never as a Skill tool call.相应地该文档也在 Dependencies between them 一节补充了 carve-out豁免段落声明 Skill 工具约定仅适用于 model-invoked Skill。该 changeset 还点出了教训的另一层规范文档与八行之外的不变式没有对齐正是这个 bug 扩散到六处调用点而非一处的主因。约定文档化.agents/invocation.md的完整规则changeset 的最后一项是把整套约定写入.agents/invocation.md供后续新 Skill 遵循。除前文引用的四条点名工具、多调用写法、user-invoked 豁免、harness 中立外该文档还有两条与何时该调用、何时不该调用相关的细则值得纳入写作规范操作性指令 vs 路由性文字只有 Skill 自身步骤中现在就让我去运行另一个 Skill的指令才使用 Skill 工具句式而给人类做选择的导航文字如 ask-matt/SKILL.md 和各桶 README只是把 Skill 名字当标签列出保留/skill风格即可它们不构成调用被动阅读 vs 主动建模仅仅是读一下CONTEXT.md查词汇只是一行散文指引不等于调用domain-modeling。只有主动的构建/打磨纪律——质疑术语、用边界场景压测、写 ADR、内联更新CONTEXT.md——才算domain-modeling的调用。这防止了因为提到了某个词就顺手调了重型 Skill的过度触发。小结把希望模型看懂变成模型只能这样执行这个 patch 级的术语变更没有新增任何 Skill改的只是一批SKILL.md正文的措辞但它确立的是一条可复制的写作原则适用于任何由多个 Skill/命令/工具协作组成的 agent 技能库委托必须点名机制本身Call the Skill tool with X而不是描述性散文run the/grillingskill一次调用一个名字多 Skill 步骤显式写成多次调用名字不携带 harness 假设去掉与特定框架绑定的前缀语法写之前先核对调用边界user-invoked 的能力只能转化为告知人类去做的指令永远不能写成工具调用。配套的验收标准也很直接在仓库内全文检索Call the Skill tool应当只命中操作性调用点且每一处被点名的 Skill 都是 model-invoked——这一条可以在.agents/invocation.md的不变式对照下逐条核验。【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考