setup-utarn-skills

设置 Utarn 的技能

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

• 问题跟踪器——问题存放的位置（默认使用 GitHub；开箱即用地支持本地 Markdown）
• 分类标签——用于五种标准分类角色的字符串
• 领域文档——CONTEXT.md 和 ADR 的存放位置，以及读取它们的使用方规则

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

流程

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 问题跟踪器惯例？
• 是否已安装 triage 技能？（与此技能并列的 triage 技能目录，或可用技能中的 triage。）这决定是否运行 B 部分。
• 单体仓库的信号——pnpm-workspace.yaml、package.json 中的 workspaces 字段，或包含自身 src/ 的非空 packages/*。这些信号只会出现在真正的大型多包仓库中；若不存在，则视为单一上下文，这适用于几乎所有仓库。

2. 呈现发现并询问

总结现有内容和缺失内容。然后按顺序逐节进行——一次一节，得到回答后再进入下一节。

每节开头先给出建议答案，让用户可以用一个词接受。只有在选项确实存在分支时，才用一句话解释；如果探索阶段已经确定，则跳过整节（未安装 triage 时跳过 B 节，没有 monorepo 时跳过 C 节）。

A 节——问题跟踪器。

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

默认建议：这些技能是为 GitHub 设计的。如果 git remote 指向 GitHub，则建议使用 GitHub。如果 git remote 指向 GitLab（gitlab.com 或自托管主机），则建议使用 GitLab。否则（或用户有偏好时），提供以下选项：

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

将选择记录在 docs/agents/issue-tracker.md 中。GitHub 和 GitLab 模板都带有“将 PR 作为请求入口”的标志，默认关闭——保持关闭，不要主动提及；希望将外部 PR 纳入 triage 队列的用户之后可以在文件中启用该标志。

B 节——Triage 标签用词。 如果未安装 triage 技能，则完全跳过本节（探索阶段已经告知你）——未安装的技能不需要标签。

如果已安装，则只问一个问题：

你想保留默认 triage 标签吗？（建议：是）

默认标签是五个规范角色，每个标签字符串都与其名称相同：needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix。回答是时，按原样写入。只有当用户回答否时（通常是因为其跟踪器已经使用了其他名称，例如用 bug:triage 对应 needs-triage），才收集替代标签，以便 triage 使用现有标签，而不是创建重复标签。

C 节——领域文档。 默认采用单上下文——在仓库根目录放置一个 CONTEXT.md 和 docs/adr/。这适用于几乎所有仓库；直接写入，不必询问。

只有在探索发现 monorepo 信号时，才提供多上下文方案——根目录下的 CONTEXT-MAP.md 指向各上下文对应的 CONTEXT.md 文件。然后确认用户希望采用哪种布局。

3. 确认并编辑

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

• 要添加到正在编辑的 CLAUDE.md / AGENTS.md 中的 ## Agent skills 区块（选择规则见第 4 步）
• docs/agents/issue-tracker.md、docs/agents/domain.md 和 docs/agents/triage-labels.md 的内容（仅在安装了 triage 时包含最后一个文件）

写入前，让用户先进行修改。

4. 编写

选择要编辑的文件：

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

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

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

区块内容：

## Agent skills

### Issue tracker

[one-line summary of where issues are tracked]. See `docs/agents/issue-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`.

仅当 triage 已安装且已运行第 B 节时，才包含 ### Triage labels 子区块并编写 docs/agents/triage-labels.md。否则，两者都省略。

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

• issue-tracker-github.md — GitHub 问题跟踪器
• issue-tracker-gitlab.md — GitLab 问题跟踪器
• issue-tracker-local.md — 本地 Markdown 问题跟踪器
• triage-labels.md — 标签映射（仅当 triage 已安装时）
• domain.md — 领域文档使用方规则与布局

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

5. 完成

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