forge-setup-project 是一个面向 agentic engineering 的技能，用于搭建或更新项目的上下文基础设施。它把上下文划分为三层：第一层是热记忆 AGENTS.md，始终加载，内容精简、约定密集，只保留智能体需要持续掌握的信息；第二层是温记忆 docs/*.md，按主题按需加载，仅当内容值得其 token 成本时才创建；第三层是冷记忆，包括规格、模式和运行手册，属于复杂项目的按需参考，不由本技能创建。核心原则是上下文必须对得起它的 token 成本，只收录智能体无法通过 Grep、Glob 和 Read 探索代码库自行发现的知识。
在文件取舍上，AGENTS.md 是唯一的指导文件。不要创建 CLAUDE.md：当不存在 CLAUDE.md 或 CLAUDE.local.md 时，Claude Code 会原生读取 AGENTS.md，因此符号链接或副本只会多出一个名字。只有当用户希望保留 Claude 专属内容时，CLAUDE.md 才具有合理性，此时它的形式是 @AGENTS.md 加上该内容，而不是副本。
输入方面，可选项目根路径（$ARGUMENTS，默认为当前工作目录），以及可选的 -- <additional context> 用于提供执行指导。
处理流程共十步。第一步：评估现有内容——扫描项目根目录下的 AGENTS.md、CLAUDE.md、README.md 和 docs/，文件状态决定工作方式：什么都不存在则从零生成；存在没有 AGENTS.md 的遗留 CLAUDE.md 则先迁移再更新；已有 AGENTS.md 则审计并更新。作为 AGENTS.md 符号链接或副本的 CLAUDE.md 会在第七步移除。第二步：探索代码库——了解结构、工具链、CI/CD 和文档（绿地项目可跳过），将每个发现归类为可发现（智能体能自行找到）或需要记录（决策、约定、失败模式），只有第二类才属于上下文文件；同时评估智能体就绪度，包括反馈回路（测试、linter、构建周期速度）、模块结构、应用可读性和已知风险。第三步：审计既有指导——对已有指导文件的每个部分按具体性、不可发现性、时效性和信号密度四个标准打分，并按影响分组呈现审计报告，在应用更改前通过 AskUserQuestion 获得用户确认。第四步：收集项目信息——用 AskUserQuestion 询问代码无法揭示的内容，包括核心原则、反复出现的失败模式和领域不变量，以及探索中的模糊点和第三步审计暴露的缺口，绝不询问可从代码中发现的内容，并在决定问什么时纳入任何附加上下文。第五步：生成或更新 AGENTS.md——保持约 200 行以内，长度由通过不可发现性测试的内容决定，结构见 agents-md-template.md；迁移时把被接受的遗留内容并入，并在第七步删除旧文件。第六步：生成或更新第二层 docs/——创建 docs/architecture.md（设计决策、数据流、模块职责）和 docs/pr-workflow.md（分支命名、PR 检查清单、评审流程）；只有当探索发现了值得记录的内容时，才通过 AskUserQuestion 提供更多文档（开发、编码规范、测试、领域特定）；每份文档都必须通过不可发现性测试，空文档只会浪费上下文。第七步：移除冗余的 CLAUDE.md 并更新 .gitignore——删除作为 AGENTS.md 符号链接、其副本或内容已迁入 AGENTS.md 的遗留 CLAUDE.md（被跟踪时用 git rm）；如果其中仍有未出现在 AGENTS.md 的内容，先通过 AskUserQuestion 询问用户再删除；如果其中有用户希望保留的 Claude 专属内容，则将其缩减为 @AGENTS.md 加上该内容；如果存在 CLAUDE.local.md，告知用户：在它存在时 Claude Code 会跳过 AGENTS.md；移除 CLAUDE.md 时提醒用户，在 Bedrock 上或禁用了遥测的、早于 v2.1.281 的 Claude Code 会话只读取 CLAUDE.md，对这些情况的修复办法是让 CLAUDE.md 内容为 @AGENTS.md；向 .gitignore 追加缺失的、与栈相称的条目，绝不覆盖已有的 .gitignore。第八步：创建面向人类的文件——README.md 不存在时创建（项目描述、快速开始、文档链接，面向人类而非智能体上下文）；已存在时通过 AskUserQuestion 询问替换、合并还是保留。第九步：提交——暂存并提交新增或修改的文件，提交信息为 docs: set up agentic context infrastructure（更新时为 docs: update context infrastructure）；如果存在不相关的已暂存更改或生成的文件有未决问题则跳过提交。第十步：总结——报告创建或更改的内容，包含各层状态及行数、智能体就绪度评估和后续步骤。
指南包括：不可发现性测试——如果智能体通过探索能找到，就不要写；信号优先于数量——表格胜过段落，省略空章节；层级纪律——AGENTS.md 保持在约 200 行以内，超过 200 行则移至第二层；边界情况——monorepo 建议每个包一个 AGENTS.md，没有测试或 CI 时作为后续步骤提及。相关技能方面，下一步可用 forge-create-issue 规划第一项工作，如果想法仍较粗糙、需要先经过收敛式提问，则用 forge-shape。示例用法：/forge-setup-project、/forge-setup-project /path/to/project、/forge-setup-project -- keep the setup lean and call out missing feedback loops。