content-template-gateway

内容模板网关

概述

content-template-gateway 是本项目中所有由 Agent 编写的结构化内容的规范入口点，与内容的目标位置无关。每当用户或 Agent 准备编写将用于以下任一目标的内容时，都会首先调用此技能：

• 内容类型（由模板驱动）：RFC、ADR、事后复盘、操作手册、规范、计划、PRD、单页文档、路线图、README、教程、发行说明、回顾、状态报告、会议记录、简历、求职信、博客文章、GitHub PR 描述 / issue 正文 / PR 或 issue 评论、Jira 或 Linear 工单、多段提交消息、Slack 或电子邮件公告，或任何其他具有结构化模板的内容形式。
• 目标位置（相互独立——同一种内容类型可以用于任一目标）：本地 Markdown 文件、GitHub（通过 gh ... 提交 PR / issue / 评论正文）、Jira / Linear（通过 API 或网页）、Confluence、Notion、Google Drive、Slack、电子邮件，或任何未来可接收由 Agent 编写的结构化文本的系统。内容类型决定模板选择；目标位置只是附带在 Phase C 指令中的元数据。

此技能会：(a) 通过研究，根据用户或 Agent 的意图识别内容类型和变体；(b) 检查 docs/templates/<content-type>/<variant>/ 中是否存在现有模板；(c) 如果存在模板，则通过强制拒绝指令强制使用模板；(d) 如果不存在模板，则通过基于研究的工作流创建新模板；(e) 在用户询问时，就如何放置不适合现有模板的内容提供建议。

此技能可独立运行：如果已安装具备研究能力的技能，则优先使用；否则回退到内置的 WebSearch + WebFetch，以便在任何环境中正常工作。

何时激活

• 用户要求编写任何结构化内容——目标位置不限。这是主要触发条件。
• Agent 准备为任一目标位置编写结构化内容。 即使用户没有明确要求使用模板——只要你（Agent）准备执行以下任一操作，此技能就会首先激活。这与用户主动触发同样是必需的。示例（不限于此）：
  • 编写新的文档类文件：temp-spec-*.md、temp-plan-*.md、docs/<type>/<name>.md、子目录的 README，或任何具有结构化模板的产物。
  • 使用非简单正文调用 gh pr create、gh issue create、gh pr comment、gh issue comment。
  • 创建 Jira / Linear 工单或编写其描述正文。
  • 编写多段 git commit 正文。
  • 发布长篇 Slack / 电子邮件消息；发布 Confluence / Notion 页面。
• 用户要求重新创建现有模板（模式 force-regenerate）。
• 用户要求为现有内容类型添加新变体（模式 force-new-variant）。
• 用户说“**建议：**我有不适合现有模板的内容”——触发 Phase E。
• 用户明确调用此技能（例如 /content-template-gateway）。

不要在以下情况下激活：

• 用户想搭建项目结构（例如“创建一个 Python uv 工作区”）。这属于其他技能的范围。
• 用户想将现有模板翻译成其他语言或格式。不在此技能范围内。
• 用户想用实际内容填写模板（即实例化模板）。这是使用该技能的 Agent 的工作——此技能只返回模板和指令。
• 用户正在修改已编写的内容，以修正拼写错误 / 格式问题 / 表述清晰度。此技能用于编写新内容，而非编辑现有内容。
• 用户明确表示“我不需要模板——只要一条简短备注。”（覆盖情况；不会阻止操作，但技能不会自动触发。）
• 单行 / 简单内容（单行提交消息、单行 Slack 回复、简短代码注释）。此技能用于包含多个部分的结构化内容。

工作流

阶段 A — 识别

输入：

• 用户/Agent 的自由文本意图（例如：“我想编写一份重启 API 的操作手册”，或“我正准备为 auth 重构执行 gh pr create”）。
• 目标位置提示（文件路径、gh pr、gh issue、jira、linear、slack、commit-msg、confluence 等）。根据意图措辞或即将调用的工具推断；如果不明确则询问。
• 可选的显式模式提示（默认 use-or-create，force-regenerate、force-new-variant）。
• 可选的显式内容类型和/或变体覆盖项。

操作顺序：

1. 根据意图检测模式。 根据用户的措辞设置模式：
   • 以下表达会触发 force-regenerate：“重新生成 X”、“重新生成 X 模板”、“刷新 X”、“更新 X 模板”、“重做 X”。
   • 以下表达会触发 force-new-variant：“添加一个新变体”、“创建一个名为 X 的变体”、“创建一个名为 X 的 Y 新变体”。
   • 否则默认使用 use-or-create。
2. 调研内容类型 + 变体。 使用回退调研链：若已启用，优先使用 deep-research skill（199-biotechnologies/claude-deep-research-skill — 多来源调研，包含可信度评分和引文追踪）；否则使用任何其他具备调研能力的 skill；再否则使用内置的 WebSearch + WebFetch。（实际调研方法见 ## Research methodology。）
3. 处理歧义。 如果调研得出 2–3 个可能的内容类型候选项，提供每项的一句话说明，让用户选择。
4. 应用 slug 规则，生成规范的 <content-type> 和 <variant> slug（小写连字符格式；从变体中去掉内容类型词；截断至 30 个字符；保留的变体 slug：README/template/research/.*/_*）。
5. 确认 slug。 显示：“我会查找 docs/templates/<content-type>/<variant>/。请确认或重命名。”

失败处理： 如果经过调研后阶段 A 仍无法识别，请询问更多背景信息。最多进行 2 轮。之后以 force-new-variant 模式提示并中止。

输出到阶段 B： content-type slug、variant slug、mode、destination。

阶段 B — 检查

阶段 A 的输入： content-type、variant、mode、destination。

操作顺序：

1. 分类 docs/templates/<content-type>/<variant>/：

   • 完整 — template.md 和 research.md 均存在。
   • 缺失 — 文件夹不存在。
   • 残缺孤立项 — 文件夹存在，但缺少 template.md、research.md 或 forge: frontmatter。

2. 根据模式 + 状态分支：

   模式	状态	下一步
   use-or-create	完整	→ 阶段 C
   use-or-create	缺失	→ 阶段 D，然后 C
   use-or-create	孤立项	→ 孤立项子菜单（见下文），然后重新分类
   force-regenerate	完整或孤立项	→ 阶段 D（覆盖），然后 C
   force-regenerate	缺失	→ 阶段 D，然后 C
   force-new-variant	完整	→ slug 冲突；要求提供不同的 slug，然后重新进入 B
   force-new-variant	缺失	→ 阶段 D，然后 C
   force-new-variant	孤立项	→ 先进入孤立项子菜单，然后重新分类

孤立项子菜单（上表引用）：

对于检测到的每个孤立变体文件夹，询问用户：

检测到残缺的变体文件夹：<content-type>/<slug>（缺少：template.md 和/或 research.md 和/或 forge: frontmatter）。 您想如何处理？

1. 重新生成（针对该 slug 重新运行阶段 D）
2. 删除
3. 保留原样（跳过；下次运行时再次提示）

应用所选操作，然后重新分类该文件夹，并按照分支表继续。

输出到阶段 C 或 D： 已验证的 content-type、variant、destination，以及 should_forge 标志。

阶段 C — 执行

输入： 已验证的 content-type、variant、destination。模板文件位于 docs/templates/<content-type>/<variant>/。

操作顺序：

1. 加载 template.md 和 research.md。

2. 组装返回负载：

   ═══════════════════════════════════════════════════════════════
     TEMPLATE DIRECTIVE — MUST FOLLOW
   ═══════════════════════════════════════════════════════════════
   
   You are about to author content of type: <content-type>
   Variant: <variant>
   Destination: <destination>          (file path, gh pr, jira, slack, ...)
   Template source: docs/templates/<content-type>/<variant>/template.md
   
   RULES:
     1. You MUST follow the template structure below — section headings,
        order, and required fields are not negotiable.
     2. You MAY add placeholder text or fill in sections, but you MUST
        NOT remove or rename sections.
     3. If your content does not fit any section in the template, STOP
        and invoke content-template-gateway with intent "advise: I have
        content that doesn't fit" — do NOT improvise sections.
     4. You MUST author the content INTO the template before performing
        any destination-side action (writing the file, calling
        `gh pr create`, posting the ticket, sending the message, etc.).
        Do NOT call the destination first and patch later.
     5. If you proceed without this template, you are violating
        the project's "templates first" norm.
   
   ═══════════════════════════════════════════════════════════════
     TEMPLATE CONTENT — copy and fill in below
   ═══════════════════════════════════════════════════════════════
   
   <full template.md content>
   
   ═══════════════════════════════════════════════════════════════
     RESEARCH NOTES — for your reference (not required reading)
   ═══════════════════════════════════════════════════════════════
   
   <research.md content>
   

3. 将组装好的负载返回给调用方。

不向用户提问。纯粹组装输出。

阶段 D — Forge（子流程）

**调用方：**阶段 B（缺失或已解决孤立项），或模式为 force-regenerate / force-new-variant 时直接调用。

操作顺序：

1. 通过回退链进行初步内容类型研究。（具体方法见 ## Research methodology。）

2. 提出变体。 当模式为 force-regenerate 或 force-new-variant 时，完全跳过此步骤——变体已在阶段 A 的输出中命名。否则（模式为 use-or-create），提供 2–4 个候选项，每个附带一行描述和自动生成的 slug。用户可以接受列表、编辑列表，或要求重新进行研究。

3. 针对每个变体进行深入研究。 使用该变体更具体的范围重新调用回退链。（具体方法见 ## Research methodology。）失败时：重试一次 → 显示子菜单（重试 / 跳过 / 取消）。

4. 生成产物（按以下顺序）：

   1. 对于每个变体：先将 template.md 写入 docs/templates/<content-type>/<variant>/，再写入 research.md。两者都包含 forge: frontmatter（status: unreviewed、forged: <YYYY-MM-DD>、reviewed: null）。
   2. 写入所有变体后，更新 docs/templates/<content-type>/README.md，将其用作变体索引。
   3. 跳过的变体不创建文件夹，也不会列入 README.md。

5. 按以下格式向调用方输出 Forge 结束摘要：

   Forge complete for `<content-type>`.
   
   Emitted:
     • <variant-1>  (docs/templates/<content-type>/<variant-1>/)
     • <variant-2>  (docs/templates/<content-type>/<variant-2>/)
   
   Skipped (research failed):
     • <variant-3> — retry by re-invoking with mode `force-new-variant`
   

   如果所有变体均成功，则完全省略“Skipped”区块。

**输出到阶段 C：**调用方要求的模板的 content-type + variant。

阶段 E — Advise（子流程）

**调用方：**阶段 A 中意图匹配 advise: 模式时。

**输入：**当前强制使用的模板的 content-type 和 variant，以及用户提供的不适用内容。

操作顺序：

1. 加载当前的 template.md 和 research.md。
2. 通过回退链研究内容位置——此类内容通常如何放置在这种内容类型中？（具体方法见 ## Research methodology。）
3. 判断并分支：
   • 符合现有变体 → 返回位置建议（第 N 段 → ## SectionName）。
   • 不符合 → 提出包含缺失章节的新变体。询问用户：是（为新变体调用阶段 D） / 否（返回现有变体中尽力而为的位置建议） / 修改（用户描述提案需要如何调整；最多进行 2 轮修改，然后接受最佳版本，或以位置建议作为回退方案中止）。

**输出：**位置建议（纯文本），或新模板 + 指令（通过阶段 D → 阶段 C）。

研究方法

所有研究调用（阶段 A；阶段 D 步骤 1 和 3；阶段 E）均遵循此方法。

每次研究调用的目标

• 阶段 A — 识别。“这是什么内容类型？有哪些变体？哪个变体最符合用户的意图？”
• 阶段 D 步骤 1 — 初步研究。“这种内容类型通常是什么？有哪些典型示例？”
• 阶段 D 步骤 3 — 针对变体的深入研究。“对于这个特定变体，通常有哪些章节 / 结构？”
• 阶段 E — 位置。“对于此模板中的这类内容，通常放在哪里？还是说需要新建一个变体？”

来源质量等级（优先选择列表靠前的来源）

1. 官方 / 权威参考资料——原始规范（例如 Michael Nygard 关于 ADR 的文章）、官方文档、语言 / 框架参考文档、目标平台文档（GitHub 的 PR 模板指南、Atlassian 的 Jira 工单指南）。
2. 多个相互印证的工程博客——Google SRE Book、Atlassian Handbook、GitLab 文档等成熟来源，以及知名公司的工程博客。
3. 单一可靠来源——可以使用，但需在 research.md 中标记为单一来源。
4. 避免使用——未经其他来源印证的 Stack Overflow 个人回答、AI 生成的内容农场、没有出处的个人教程。

查询模式（由宽到窄）

1. 宽泛：“what is a <content-type>”——确认整体形态。
2. 结构：“<content-type> template / sections / structure”
3. 变体：“<content-type> variants / types”
4. 示例：“<content-type> example”——核实建议的章节是否出现在实际示例中。

将某个章节认定为「规范章节」前的最低来源要求

• 至少 2 个独立来源必须包含某个章节，才能将其视为该变体的规范章节。
• 只有 1 个来源 → 将其纳入模板，但在 research.md 中将该章节标记为「单一来源；依赖前请核实」。
• 来源相互矛盾 → 在 research.md 中列出两种解释；根据用户可能的上下文选择其一，或询问用户。

输出前的核验检查

• 拟定的 template.md 中的每个章节，都至少出现在该变体的 2 个真实示例中。
• 变体之间存在实质差异——如果两个拟定变体的章节重合度达到 90% 以上，它们就不算真正不同的变体（应合并或重命名）。
• 章节名称使用常见术语（不要另造名称）。

停止条件

• 2–3 个来源对结构形态达成一致 → 足够。
• 新查询返回的内容已见过 → 停止。
• 达到 Token／时间预算 → 停止并尽力完成；在 research.md 中标明。

规则

硬性规则（绝不违反）：

• 绝不返回缺少硬性拒绝指令的模板。
• 除 Phase D 以及 force-regenerate 或 force-new-variant 模式外，绝不覆盖现有模板文件。
• 绝不声明技能依赖。该技能是自包含的；研究备用链是运行时偏好。
• 除示例说明外，绝不在 SKILL.md 正文中逐一列出触发命令。When to activate 列表仅供说明，并非封闭列表——Agent 应将底层原则（「面向任何目标的结构化 Agent 编写内容」）应用于任何新的工具／API／系统。

偏好（可由用户选择覆盖）：

• 如可用，优先使用 deep-research 技能（199-biotechnologies/claude-deep-research-skill）（备用顺序）。
• Phase D 中优先选择失败时跳过，而非失败时中止。
• 优先立即取消，不经确认。

输出

该技能会返回以下其中一项：

1. Phase C 载荷——组装后的指令 + 模板 + 研究内容，限定为 ASCII 字符。任何成功的 use-or-create / force-regenerate / force-new-variant / Phase-E-new-variant 路径都会返回此项。
2. Phase E 放置建议——纯文本章节映射。Phase E 的研究判定内容适用于现有变体时返回此项。
3. 中止信号——纯文本原因。用户取消，或 Phase A 用尽 2 轮上下文收集后返回此项。

磁盘副作用：

• Phase D 会在 docs/templates/<content-type>/ 下写入 template.md、research.md 和 README.md。
• 其他阶段都不会写入磁盘。
• 该技能绝不会写入外部目标位置（docs/templates/ 以外的文件、GitHub、Jira、Slack 等）。调用方在收到 Phase C 载荷后执行目标端操作。

渐进式披露

技能正文完全自包含。

未来可添加：

• references/forge-research-prompts.md——常见内容类型的预设研究提示词。
• assets/directive-template.txt——受 ASCII 字符限制的指令模板。
• scripts/check-orphans.sh——用于 Phase B 孤立项分类的辅助脚本。

相关内容

• 相关技能（content-template-gateway 不会调用，但与之相邻）：deep-research、writing-skills、brainstorming、external-content-sanitizer。

正文预算

• description ≤ 1,024 个字符（agentskills.io 上限）
• 正文 ≤ 约 500 行／5,000 个 Token——Claude 每轮都会将其保留在上下文中
• 硬性上限为 30,000 个字符（重新渲染为 Agent 时的 Copilot 自定义 Agent 限制）