setup-formsg-ai-skills

设置 FormSG AI 技能

搭建工程技能所依赖的各仓库配置：

• 工单跟踪器 — 工单的存放位置（默认使用 GitHub；开箱即用地支持本地 Markdown）
• 分诊标签 — 用于五种标准分诊角色的字符串
• 领域文档 — CONTEXT.md 和 ADR 的存放位置，以及读取这些文档时适用的使用规则
• 评审准备 — 仓库的提交风格和线索标记约定，供 tdd（编写者）和 prepare-for-review（读取者）使用

这是一项由提示词驱动的技能，并非确定性脚本。先探索并展示发现的内容，与用户确认后再写入。

流程

1. 探索

检查当前仓库，了解其初始状态。阅读现有内容，不要想当然：

• git remote -v 和 .git/config — 这是 GitHub 仓库吗？是哪个仓库？
• 仓库根目录中的 AGENTS.md 和 CLAUDE.md — 是否存在其中之一？其中是否已有 ## Agent skills 章节？
• 仓库根目录中的 CONTEXT.md 和 CONTEXT-MAP.md
• docs/adr/ 以及任何 src/*/docs/adr/ 目录
• docs/agents/ — 此技能之前生成的内容是否已存在？
• .scratch/ — 是否表明已在使用本地 Markdown 工单跟踪器约定？

2. 展示发现并询问

总结已有内容和缺失内容。然后逐一引导用户完成这四项决策：展示一个部分，等待用户回答，再进入下一部分。不要一次性全部列出。

假设用户不了解这些术语。每个部分都先简短说明（它是什么、这些技能为什么需要它、选择不同选项会有什么变化），然后展示选项和默认值。

部分 A — 工单跟踪器。

说明：「工单跟踪器」是此仓库中存放工单的地方。to-tickets 和 to-spec 等技能会从中读取信息并写入内容——它们需要知道是调用 gh issue create、在 .scratch/ 下创建 markdown 文件，还是遵循你描述的其他工作流。请选择此仓库中实际用于跟踪工作的地方。

默认倾向：这些技能是为 GitHub 设计的。如果 git remote 指向 GitHub，就建议使用 GitHub。否则（或如果用户更倾向于其他选项），提供以下选项：

• GitHub — 工单存放在仓库的 GitHub Issues 中（使用 gh CLI）
• 本地 markdown — 工单以文件形式存放在此仓库的 .scratch/<feature>/ 下（适合个人项目或没有远程仓库的仓库）
• 其他（Jira、Linear 等）— 请用户用一段话描述工作流；技能会将其记录为自由格式文本

部分 B — 分类标签词汇。

说明：工单会在状态机中流转——需要评估、等待报告者补充信息、已准备好由 AFK Agent 领取、已准备好交给人工处理，或不予修复。为此，技能需要应用与工单跟踪器中实际配置的字符串相匹配的标签（或等效设置）。如果仓库已经使用不同的标签名称（例如 bug:triage 而不是 needs-triage），请在此处进行映射，以便技能应用正确的标签，而不是创建重复标签。

五种规范角色：

• needs-triage — 维护者需要评估
• needs-info — 等待报告者补充信息
• ready-for-agent — 规格完整，可由 AFK Agent 直接处理（Agent 无需人工提供背景信息即可领取）
• ready-for-human — 需要人工实现
• wontfix — 不予处理

默认值：每个角色对应的字符串与其名称相同。询问用户是否要覆盖任何默认值。如果其工单跟踪器中没有现有标签，默认值即可。

部分 C — 领域文档。

说明：某些技能（improve-codebase-architecture、tdd）会读取 CONTEXT.md 文件来了解项目的领域术语，并查看 docs/adr/ 中过往的架构决策。它们需要知道仓库是使用一个全局上下文，还是多个上下文（例如，前后端上下文分开的 monorepo），以便在正确的位置查找。

确认目录布局：

• 单一上下文 — 仓库根目录下有一个 CONTEXT.md 和 docs/adr/。大多数仓库都是这种情况。
• 多上下文 — 根目录下有一个 CONTEXT-MAP.md，指向各上下文对应的 CONTEXT.md 文件（通常用于 monorepo）。

部分 D — 评审准备。

说明：实现技能（tdd 及其后续技能）遵循两项项目约定：提交风格（让评审者能逐个阅读提交）和决策线索约定（Agent 工作时会将简短的决策记录写入 .scratch/<feature>/decisions.md）。之后，prepare-for-review 会将这些记录整理成 PR 正文中的要点和行内评审评论，让评审者看到的是做出决策时记录的实际理由，而不是事后重构的解释。

这两项设置始终配套采用，因此放在同一部分。与用户一起浏览种子模板，并允许他们在写入前编辑：

• docs/agents/commit-style.md — 每个提交只包含一个逻辑变更。
• docs/agents/decisions-breadcrumb.md — 决策线索格式，附示例。

3. 确认并编辑

向用户展示以下内容的草稿：

• 要添加到正在编辑的 CLAUDE.md / AGENTS.md 中的 ## Agent skills 区块（文件选择规则见第 4 步）
• docs/agents/ticket-tracker.md、docs/agents/triage-labels.md、docs/agents/domain.md、docs/agents/commit-style.md、docs/agents/decisions-breadcrumb.md 的内容

写入前让用户编辑。

4. 写入

选择要编辑的文件：

• 如果 CLAUDE.md 存在，则编辑它。
• 否则，如果 AGENTS.md 存在，则编辑它。
• 如果两者都不存在，询问用户要创建哪一个——不要替他们决定。

如果 CLAUDE.md 已存在，绝不要创建 AGENTS.md（反之亦然）——始终编辑已存在的文件。

如果所选文件中已存在 ## Agent skills 区块，就地更新其内容，而不是追加重复区块。不要覆盖周围各节中用户所做的编辑。

此区块：

## Agent skills

### Ticket tracker

[one-line summary of where tickets are tracked]. See `docs/agents/ticket-tracker.md`.

### Triage labels

[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.

### Domain docs

[one-line summary of layout — "single-context" or "multi-context"]. See `docs/agents/domain.md`.

### Review prep

Commit style and breadcrumb convention for review-ready PRs. See `docs/agents/commit-style.md` and `docs/agents/decisions-breadcrumb.md`.

然后，以此技能文件夹中的种子模板为起点，编写文档文件：

• ticket-tracker-github.md — GitHub 工单跟踪器
• ticket-tracker-local.md — 本地 Markdown 工单跟踪器
• triage-labels.md — 标签映射
• domain.md — 领域文档使用规则和布局
• commit-style.md — 按提交审查时采用的项目提交规范
• decisions-breadcrumb.md — 决策面包屑的架构和示例

对于“其他”工单跟踪器，根据用户的描述从头编写 docs/agents/ticket-tracker.md。

5. 完成

告知用户设置已完成，并说明今后哪些工程技能会从这些文件中读取信息。提醒他们之后可以直接编辑 docs/agents/*.md——只有在他们想切换工单跟踪器或从头重新设置时，才需要重新运行此技能。