setup-skills

设置技能

搭建各仓库配置，供工程技能使用：

• 问题跟踪器：问题所在位置（默认为本地 Markdown；也可以在此选择 GitHub、GitLab 或其他服务）
• 分类标签：用于六种标准分类角色的字符串
• 领域文档：GLOSSARY.md 和 ADR 的存放位置，以及使用者读取这些文档的规则
• Git 防护措施：在本仓库的 .claude/settings.json 中设置 permissions.deny 条目，以阻止破坏性 Git 操作（push、reset 等）。不要安装或注册钩子；用户如果需要，已经在全局设置了钩子。

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

流程

1. 探索

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

• git remote -v 和 .git/config：这是 GitHub 仓库吗？是哪个仓库？
• 仓库根目录下的 AGENTS.md 和 CLAUDE.md：是否存在其中任何一个？其中是否已有 ## Agent skills 章节？
• 仓库根目录下的 GLOSSARY.md 和 GLOSSARY-MAP.md
• docs/adr/ 和任何 src/*/docs/adr/ 目录
• docs/agents/：是否已经存在此技能先前生成的内容？
• .scratch/：是否表明已在使用本地 Markdown 问题跟踪约定？
• .claude/settings.json：permissions.deny 是否已列出用于阻止破坏性 Git 操作的 Bash(git …) 规则？
• Monorepo 信号：pnpm-workspace.yaml、package.json 中的 workspaces 字段，或包含自身 src/ 的已填充 packages/*。只有真正大型的多包仓库才会出现这些信号；若没有，则视为单一上下文，这几乎适用于所有仓库。

2. 展示发现并询问

总结现有内容和缺失内容。然后按顺序处理各个部分，每次处理一个部分，得到一个答复后再继续。

每个部分都先给出推荐答案，方便用户用一个词接受。只有在选项确实存在分歧时，才用一行说明；如果探索已确定选择，则跳过该部分（没有 Monorepo 时跳过 C 部分；项目的拒绝列表已存在时跳过 D 部分）。

A 部分：问题跟踪器。

说明：此处的“问题跟踪器”是指本仓库中问题的存放位置。to-tickets 和 to-spec 等技能会读取此文件并直接在其中发布内容，不会在每次运行时都询问，因此请选择你实际用于跟踪工作的地方。如果跳过设置（或尚未运行设置），这些技能会自行回退到本地 Markdown。用户仍可通过明确要求，在单次运行中覆盖目标位置。

默认优先选择本地 Markdown，除非用户明确表示想使用远程跟踪器。如果 git remote 指向 GitHub，且用户希望使用远程问题跟踪器，则建议使用 GitHub。如果 git remote 指向 GitLab（gitlab.com 或自托管主机），且用户希望使用远程问题跟踪器，则建议使用 GitLab。否则请提供以下选项：

• 本地 Markdown（推荐默认选项）：问题以文件形式存放在本仓库的 .scratch/<feature>/ 下（适合个人项目，或不想创建远程问题的情况）
• GitHub：问题存放在仓库的 GitHub Issues 中（使用 gh CLI）
• GitLab：问题存放在仓库的 GitLab Issues 中（使用 glab CLI）
• 其他（Jira、Linear 等）：请用户用一段话描述工作流；技能会将其记录为自由文本

将选择记录在 docs/agents/issue-tracker.md 中。GitHub 和 GitLab 模板都带有“将 PR 作为需求入口”的标志，默认设为关闭。保持关闭，不要提起：希望将外部 PR 纳入分类队列的用户之后可以自行修改文件中的标志。

说明：开源仓库收到的功能请求往往以 Pull Request 的形式出现，而不只是 Issue；PR 就是附带代码的问题。如果启用此选项，外部 PR 会被纳入同一分类队列，并按照与问题相同的标签和状态处理（协作者尚在进行中的 PR 不受影响）。如果 PR 对你来说不是需求入口，请保持关闭。 B 节：分类标签。 无论是否安装了分类技能，始终执行：to-spec、to-tickets 和 review-axes 也会通过这些标签记录状态。只问一个问题：

你想保留默认分类标签吗？（推荐：是）

说明：收到的问题经过分类后，会进入状态机中的某个状态：需要评估、等待提问者回复、等待 AFK Agent 接手、等待人工处理，或不予修复。为此，工程技能会应用与你实际配置的字符串相匹配的标签（或问题跟踪器中的等效项）。如果你的仓库已经使用了不同的标签名称（例如 bug:triage 而不是 needs-triage），请在此处映射它们，以便应用正确的标签，而不是创建重复标签。

C 节：领域文档。 默认采用单上下文（在仓库根目录放置一个 GLOSSARY.md 和 docs/adr/）。这适用于几乎所有仓库，无需询问，直接编写。

只有在探索时发现了单体仓库的迹象，才提供多上下文方案（根目录的 GLOSSARY-MAP.md 指向各上下文对应的 GLOSSARY.md 文件）。然后确认他们想采用哪种布局。

D 节：Git 防护措施。 推荐：是。如果 .claude/settings.json 已包含以下种子列表中的所有拒绝规则（或用户自定义的明显超集），则跳过。

要添加项目级 permissions.deny 规则，阻止 Claude Code 执行破坏性 Git 操作吗？（推荐：是）

说明：只将拒绝规则合并到此仓库的 .claude/settings.json 中，不使用钩子或脚本。Claude Code 会拒绝执行 git push、git reset --hard、git clean（也包括 git -C <dir> … 形式）、强制删除分支、丢弃所有更改的 checkout/restore 操作、stash drop/clear，以及强制删除标签。日常 Git 操作（add、commit、merge、rebase、switch、worktree、软重置）仍可使用，因此 /implement、/delegate-tickets 和 /implement-spec 等技能仍会正常运行。现有设置（允许规则、钩子、环境变量）会保留；替换文件前会写入带时间戳的备份。如果缺少 jq 或文件不是有效的 JSON，合并会停止且不做任何更改。现有的全局钩子也会保持不变。只有当你希望 Agent 可以在此仓库中随意修改 Git 历史记录时，才选择否。

如果现有拒绝列表包含较旧的宽泛规则（Bash(git reset *)、Bash(git rebase *) 或其 git -C 形式），请保留这些规则，并告知用户：它们会阻止 /implement-spec 和冲突解决可能需要的软重置与变基操作，手动删除它们是安全的。绝不要自行删除这些规则。

如果用户回答否，则省略拒绝规则合并、docs/agents/git-guardrails.md 和 ### Git guardrails 子块。用户回答否时，不要删除现有的拒绝规则。

3. 确认并编辑

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

• 要添加到正在编辑的 CLAUDE.md / AGENTS.md 文件中的 ## Agent skills 块（选择规则见第 4 步）
• docs/agents/issue-tracker.md、docs/agents/domain.md 和 docs/agents/triage-labels.md 的内容
• 当 D 节回答是时：docs/agents/git-guardrails.md 的内容，以及将合并到 .claude/settings.json 中的 permissions.deny 条目

写入前允许用户编辑。

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`.

### Git guardrails

Destructive git (`push`, `reset --hard`, …) is denied via `permissions.deny` in `.claude/settings.json`. A denied command is a stop signal: report it, never route around it. See `docs/agents/git-guardrails.md`.

只有当 D 节的答案为 是 时，才包含 ### Git guardrails 子区块并编写 docs/agents/git-guardrails.md。当 D 节的答案为 否 时，省略它们。

在 GitHub 或 GitLab 上，创建跟踪器中缺少的每个已配置标签（gh label create / glab label create）。

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

• issue-tracker-github.md：GitHub 问题跟踪器
• issue-tracker-gitlab.md：GitLab 问题跟踪器
• issue-tracker-local.md：本地 Markdown 问题跟踪器
• triage-labels.md：标签映射
• domain.md：领域文档使用者规则 + 布局
• git-guardrails.md：记录项目拒绝列表（仅当 D 节答案为是时）

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

4a. 项目 Git 拒绝规则（仅当 D 节答案为是时）

只写入目标项目的 .claude/settings.json。不要创建 .claude/hooks/，不要注册 PreToolUse，不要复制脚本，不要修改 ~/.claude/settings.json。

需要 jq。通过一次 Bash 调用运行下面的合并操作。它只会追加缺少的规则，保留文件中的其他所有内容（允许规则、钩子、环境变量、现有拒绝条目及其顺序），并在替换文件前在其旁边创建带时间戳的备份。仅当文件缺失或为空时，才会写入初始的 {}。

如果代码片段以非零状态退出（没有 jq，或文件不是 JSON 对象），请将其消息转告用户，并在此处停止 D 节：不要重新创建文件，不要写入初始的 {}，也不要通过手动编辑拒绝列表来绕过问题。由用户修复原因后重新运行。

种子拒绝列表（将这些字符串合并到 permissions.deny；保留项目已有的所有条目）。每条 git -C 规则有两种形式，因为末尾带空格和 * 的规则只有在它是规则中唯一的通配符时，才会匹配不带其他参数的命令：单独使用 Bash(git -C * push *) 会漏掉 git -C . push。

Bash(git push *)
Bash(git reset --hard *)
Bash(git clean *)
Bash(git -C * push)
Bash(git -C * push *)
Bash(git -C * reset --hard)
Bash(git -C * reset --hard *)
Bash(git -C * clean)
Bash(git -C * clean *)
Bash(git branch -D *)
Bash(git branch --delete --force *)
Bash(git checkout . *)
Bash(git restore . *)
Bash(git stash drop *)
Bash(git stash clear *)
Bash(git tag -d *)
Bash(git tag -D *)

幂等合并：

# setup-skills: merge git deny rules
PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
SETTINGS="$PROJECT_ROOT/.claude/settings.json"

if ! command -v jq >/dev/null 2>&1; then
  echo "setup-skills: jq is required to merge deny rules. Install jq and re-run. $SETTINGS was not touched." >&2
  exit 1
fi

mkdir -p "$(dirname "$SETTINGS")"
if [ ! -e "$SETTINGS" ] || [ -z "$(tr -d '[:space:]' < "$SETTINGS")" ]; then
  echo '{}' > "$SETTINGS"
elif ! jq -e 'type == "object"' "$SETTINGS" >/dev/null; then
  echo "setup-skills: $SETTINGS is not a valid JSON object (see the jq error above, if any). Fix it and re-run. The file was not touched." >&2
  exit 1
fi

TMP="$(mktemp "$SETTINGS.XXXXXX")"
if ! jq --indent 2 '
  .permissions //= {}
  | .permissions.deny //= []
  | reduce (
      [
        "Bash(git push *)",
        "Bash(git reset --hard *)",
        "Bash(git clean *)",
        "Bash(git -C * push)",
        "Bash(git -C * push *)",
        "Bash(git -C * reset --hard)",
        "Bash(git -C * reset --hard *)",
        "Bash(git -C * clean)",
        "Bash(git -C * clean *)",
        "Bash(git branch -D *)",
        "Bash(git branch --delete --force *)",
        "Bash(git checkout . *)",
        "Bash(git restore . *)",
        "Bash(git stash drop *)",
        "Bash(git stash clear *)",
        "Bash(git tag -d *)",
        "Bash(git tag -D *)"
      ][]
    ) as $rule (.; if (.permissions.deny | index([$rule])) then . else .permissions.deny += [$rule] end)
' "$SETTINGS" > "$TMP"; then
  rm -f "$TMP"
  echo "setup-skills: jq could not merge into $SETTINGS. The file was not touched." >&2
  exit 1
fi

if cmp -s "$TMP" "$SETTINGS"; then
  rm -f "$TMP"
  echo "setup-skills: deny rules already present, $SETTINGS unchanged."
else
  BACKUP="$SETTINGS.bak-$(date +%Y%m%d%H%M%S)"
  cp -p "$SETTINGS" "$BACKUP"
  mv "$TMP" "$SETTINGS"
  echo "setup-skills: merged deny rules into $SETTINGS (backup: $BACKUP)."
fi

同时根据种子模板编写 docs/agents/git-guardrails.md。

5. 完成

告知用户设置已完成，并说明哪些工程技能现在会读取这些文件。如果添加了 Git 防护规则，指出 .claude/settings.json → permissions.deny（而非钩子）。说明之后他们可以直接编辑 docs/agents/*.md 和拒绝列表：只有在想切换问题跟踪器、刷新拒绝规则或从头重新开始时，才需要重新运行此技能。

然后推荐配套的 /setup-solid 技能，但不要运行它：该技能会在 CLAUDE.md 中写入一个 SOLID 章节，内容与架构层面相关、与语言无关，并遵循童子军规则的适用范围。因此，SOLID 会应用于新代码以及每次更改已经涉及的代码，而不是触发全仓库重构。这是工程工作流随后遵循的编码标准。由用户决定是否输入该命令。