用途
该技能旨在解决以下问题:当 agent 猜测错误的代码托管平台、错误的规格框架或错误的 forge API 主机时,可能打开错误形式的拉取请求或向错误位置发送请求。本技能通过从仓库自身证据和开发者回答中一次性确定八项关键事实,并将它们作为一个块记录在根目录的 AGENTS.md 中,使后续每个 agent 会话都能直接读取这些事实,无需再次检测。
主要能力
该技能解析并记录以下八项事实:
- Forge(代码托管平台):根据远程主机和根目录的 .gitlab-ci.yml 等证据判断。
- Access(访问方式):包括 ssh_host、web_host、project、project_id 和 cli 等键,依据原始 URL 和 forge 探测结果。
- Exposure(公开性):判断仓库是否有发布路径,可能为 public 或 internal,并记录目标 URL。
- Framework(规格框架):根据框架目录存在情况判断,如 openspec、spec-kit 等。
- Base branch(基础分支):通过 git 命令或 forge 默认分支确定。
- Verification(验证命令):从 Makefile、package.json、pyproject.toml 或 CI 配置中提取仓库自身运行的命令。
- Tracker(问题跟踪器):根据散文声明或 forge 是否启用 issue 功能判断。
- Reviewer(评审者):根据 CI 工作流、散文声明或近期合并请求中的机器人评审判断。
该技能会区分证据与散文描述的矛盾,并将矛盾作为问题提交给开发者。它还会检查当前机器的 forge CLI 安装和认证状态,但不会在记录块中存储任何认证方法或凭证信息。
使用方式
该技能通过命令行参数调用:
- 无参数:解析所有事实,询问剩余问题,显示差异,并在确认后写入。
--headless:不询问任何问题,对所有问题采用推荐答案并标记为 (inferred),打印将要写入的差异,但不实际写入。
技能执行流程包括七个步骤:读取已有记录、从证据解析事实、询问未决问题、决定块可携带的内容、显示差异并在确认后写入、检查本机、报告结果。
适用场景
适用于需要为仓库建立统一开发上下文记录的团队,特别是当多个 agent 会话需要一致地了解仓库的代码托管平台、规格框架、验证命令等信息时。也适用于需要确保敏感信息(如内部主机名、命名空间路径、项目 ID)不会出现在公开文件中的场景。
限制
- 仅在当前会话的工作目录内写入,写入工作目录之外需要用户明确指定路径。
- 不执行任何会创建、修改或删除远程资源的 forge 请求。
- 不将记录块写入多个文件,也不写入任何其他文件。
- 不基于散文描述决定文件系统或 git 可以决定的事实。
- 不记录猜测;没有信号且开发者未回答的事实将保持未解析状态。
- 不记录本机的认证方式、凭证名称或值。
- 不提交或推送任何更改。
- 在非 git 仓库中停止执行。
- 临时文件例外,但必须在完成前删除。