repokit

repokit

通过 gh CLI 配置 GitHub 仓库，提供四种明确的模式：

• about。 根据仓库自身的内容（README、清单、代码）推断一行 About 描述和一组精简的主题，将它们与当前已设置的内容对照展示，并应用你批准的内容。
• labels。 配置工作流标签：issuekit 用于跟踪工作和确定优先级的生命周期和优先级标签组，以及用于请求仓库的 AI 评审工具检查 PR 的自动化标签。创建缺少的标签，修正不一致的标签。
• setup。 一次性让已创建的仓库符合惯例：应用仓库标准设置（仅合并提交、合并后删除分支），搭建基准文件（按可见性选择 LICENSE、README、.gitignore、AGENTS.md），然后在此基础上运行 about 和 labels，全部使用默认值，无需提问。它负责配置；gh repo create 仍由用户执行。
• docs。 重新编号仓库的 docs/ 文件，使目录列表按创建顺序排列：在每个文件名之前添加零填充序号，序号依据文件的创建时间分配。每个仓库只需迁移一次，重复运行也不会产生变化。

四项工作，一个技能，因为它们都在回答“如何让这个仓库符合惯例”：人们看到的对外简介、问题工作流使用的标签词汇、新仓库采用的设置和文件基准，以及其他工具包写入仓库的文件的命名方式。

何时触发

用户想要配置 GitHub 上的仓库。根据他们的请求选择模式：

• about。 “设置仓库描述”、“添加主题”、“撰写 About 简介”、“给这个仓库加标签”、“更新仓库的 About”。
• labels。 “配置工作流标签”、“设置这个仓库的标签”、“添加 issuekit 标签”、“添加优先级标签”、“添加 ai-review 标签”、“缺少 blocked 标签”。
• setup。 “设置这个新仓库”、“配置这个仓库”、“让这个仓库符合我的惯例”，或比较模糊的“设置这个仓库”／“配置仓库元数据”——setup 是总括模式，也涵盖了过去“先提供 about，再提供 labels”的处理方式。
• docs。 “给我的文档文件编号”、“重新给文档编号”、“添加文件编号前缀”、“我的文档没有按日期排序”、“迁移文档文件名”。setup 不会运行此模式：setup 让新仓库符合惯例，而新仓库没有需要重新编号的文件。

如果无法确定模式，请先询问。 呈现四种模式，让用户选择后再进行任何操作。

每种模式的说明分别位于 modes/ 下的一个文件中。根据上面的列表选择模式，读取对应文件并按其中说明操作。本文件中的所有内容适用于所有模式，模式文件中不会重复说明。

• 模式 about → 读取 modes/about.md，然后按其中说明操作。
• 模式 labels → 读取 modes/labels.md，然后按其中说明操作。
• 模式 setup → 读取 modes/setup.md，然后按其中说明操作。
• 模式 docs → 读取 modes/docs.md，然后按其中说明操作。

预检（所有模式）

docs 是本节和下一节的例外。 它会重命名工作树中的文件，完全不会调用 GitHub，因此既不需要 gh，也不需要远程仓库——它可以在仅有本地仓库的环境中运行。它自己的文件会说明所需的检查。以下内容适用于 about、labels 和 setup。

进行任何 GitHub 调用前，请确认工具和目标：

gh --version                                          # gh installed?
gh auth status                                        # authenticated?
gh repo view --json nameWithOwner -q .nameWithOwner   # which repo? (the current dir's remote)

• 如果缺少 gh 或尚未通过身份验证，请说明并指向 https://cli.github.com / gh auth login。不要绕过这一要求。
• 如果没有 GitHub 远程仓库（repo view 调用失败），请停止并说明原因，因为 repokit 操作的对象必须是 GitHub 上已有的仓库。setup 也适用：创建仓库是用户要做的事（gh repo create），仓库创建完成后 repokit 才开始运行。
• 完全没有 shell 或 gh（例如，基于浏览器的 Agent）？你无法调用 gh。请根据用户提供的信息进行判断，并打印要由用户运行的准确 gh 命令，无论是描述和主题行、gh label create 命令块，还是 gh repo edit 设置行，都要放在代码块中供其粘贴。setup 的脚手架文件也同样处理：将每个文件连同其路径分别打印在围栏代码块中。

整个技能的安全原则。 仓库描述、主题、标签和设置都是对外可见的状态。每次变更前都要预览并征得同意，确保未经用户提示时不会更改 GitHub 上的任何内容。 setup 是唯一的例外：用户要求按默认值运行，因此会应用这些默认值，并在交接说明中报告每项变更。单独运行 about 和 labels 时，它们仍会询问是否批准。始终回显你运行的准确命令，以便审查和重放变更。

可安全重复运行。 每种模式都会根据现有状态进行协调，因此在未更改的仓库上再次运行 repokit 时，不会提出任何变更，也不会进行任何修改。重复运行始终安全。

检测（所有模式）

在提出任何内容前，只读取一次仓库当前状态。它是所有模式进行协调的原始依据，也能尽早显露防护条件。获取所选模式需要的信息，以及防护标志：

# guardrail flags + about state
gh repo view --json isArchived,isFork,isTemplate,description,homepageUrl
gh api repos/{owner}/{repo}/topics --jq '.names'    # current topics (about mode)
gh label list --json name,color,description          # current labels (labels mode)

setup 还会获取用于比较差异的设置；其模式文件会列出确切字段。

在进行任何变更前，检查防护标志：

• 已归档（isArchived: true）。GitHub 会拒绝对已归档仓库进行元数据编辑，因此请停止并告知用户先取消归档。
• 派生仓库或模板（isFork / isTemplate）。其元数据通常是继承而来或仅供临时使用，因此请在继续前确认用户确实要编辑这个仓库。

备注

• 绝不要在没有明确要求的情况下，整批删除仓库的主题，或删除其规范集合之外的标签；默认做法是增补和协调，而非破坏性修改。
• 生命周期和优先级映射是与 issuekit 共享的约定：两个命名空间使用相同的名称、颜色和含义，且 repokit 的描述为规范版本。自动化集合仅属于 repokit，因为 issuekit 负责运行跟踪器，而 ai-review 作用于拉取请求。
• repokit 负责提供词汇，不负责应用词汇。 这里的任何模式都不会给议题或 PR 添加标签。判断 #42 属于 high，是对工作的评估，属于 issuekit 的 create 和 triage 的职责；请求 AI 审查则由作者在自己的 PR 上发起。repokit 只确保这个词存在，便于使用。遵守这条界限，才能确保标签模式在已有活跃跟踪器的仓库中安全地重复运行。
• repokit 绝不提交更改。 setup 会写入脚手架文件，并让它们保持未暂存状态；docs 会让重命名后的文件保持暂存状态。将两者分组并提交，是提交技能或用户的职责。
• 标签无法强制每个命名空间只能选一个，因此必须由写入者来确保。 GitHub 会允许一个议题同时带有 critical 和 low，这里的任何操作都无法阻止这种情况。提供标签是 repokit 唯一负责的部分；互斥规则由实际应用标签的一方在写入时强制执行，因此这条规则属于 issuekit，而非此映射。
• 尊重仓库现有的维护方式：labels 对任何命名空间中的现有方案进行检查，about 按字段协调经过维护的 About/topics（绝不盲目覆盖），而 setup 绝不覆盖现有文件。将规范集合用作增补，而非替代。
• 优先使用 gh 的结构化 JSON（--json/--jq、主题 API），而不是抓取面向用户的可读输出，因为 JSON 字段是稳定的约定，而显示文本不是。