| name | dev-create-agents-md |
| description | 何时使用需要为编程项目、monorepo 或多级目录创建/更新 AGENTS.md、CLAUDE.md 软链接、项目级 agent 操作手册、子目录局部规则、验证命令和 Coding Agent 上下文边界时使用。 |
Create AGENTS.md
概述
为项目生成分层的 agent-readable 操作手册。根目录 AGENTS.md 写全局事实，子目录 AGENTS.md 只写相对父级新增或覆盖的规则；每个同级 CLAUDE.md 必须是指向 AGENTS.md 的软链接，避免多份规则分叉。
先用工具检索项目真实结构、脚本、测试入口、现有文档和邻近 AGENTS.md/CLAUDE.md，再写规则。禁止凭经验补全技术栈、命令、目录职责或团队偏好。
AGENTS.md 只记录会改变 agent 行为的稳定事实：目录边界、操作约束、验证命令、风格偏好、禁止事项、示例入口和升级路径。不要写日志、愿景、空泛原则或一次性任务过程。
工作流
1. 选目录层级 -> 验证：每个 AGENTS.md 都对应真实边界
2. 读取证据 -> 验证：每条规则能追溯到文件、脚本或用户指令
3. 写 AGENTS.md -> 验证：子目录只写差异，不复制父级
4. 建 CLAUDE.md 软链 -> 验证：readlink 指向 AGENTS.md
5. 复查冗余和命令 -> 验证：规则最小、命令可执行或明确说明未运行
1. 选目录层级
默认只在这些位置创建或更新：
- 仓库根目录
- monorepo 的
apps/*、packages/*、services/*、libs/*
- 技术栈、部署方式、测试入口或权限边界明显不同的子目录
- 用户明确指定的目录
默认跳过：
.git/、node_modules/、.venv/、dist/、build/、coverage/- vendored/upstream/submodule 目录，除非用户明确要求
- 没有独立操作规则的小目录
2. 读取证据
至少检索：
find . -type f \( -name 'AGENTS.md' -o -name 'CLAUDE.md' \)rg --files 或同等文件清单- package/config 文件：
package.json、pyproject.toml、Cargo.toml、go.mod、Makefile、CI workflow 等
- 现有 README、docs、测试目录和主要入口文件
- 最近或局部的团队约束：formatter、lint、typecheck、test、build、dev server
如果需要通用模板，读取 references/agents-md-pattern.md。不要把模板当事实；模板只提供结构，内容必须来自项目证据。
3. 写分层 AGENTS.md
根目录建议覆盖：
- Scope：本文件适用范围和子目录覆盖关系
- Project Map：只列 agent 定位必需的目录
- Commands：安装、格式化、lint、typecheck、test、build 的最小可靠命令
- Workflows：修改前检索、测试优先、验证门槛、文档同步规则
- Code Rules：本项目特有技术栈、依赖、样式、状态管理、API 约定
- Safety：必须询问的动作，例如删除大量文件、安装重依赖、推送、迁移生产数据
- PR/Done：完成前需要的检查项
子目录 AGENTS.md 只写：
- 与父级不同的命令、测试、代码风格或权限
- 当前目录的关键入口和反例
- 当前目录特有的依赖边界
- “继承父级，其余只覆盖以下内容”这类明确说明
避免：
- “写高质量代码”“保持简洁”这类无法执行的空话
- 复制父级整段规则
- 记录一次性任务日志
- 无证据的命令、版本或架构判断
- 长篇背景故事
4. 创建 CLAUDE.md 软链接
每个创建或更新 AGENTS.md 的目录，都创建同级软链接：
uv run python skills/dev-create-agents-md/scripts/link_claude_to_agents.py <dir> [<dir> ...]
脚本会拒绝覆盖已有普通文件或指向其他位置的软链接；如确实要替换，先向用户说明风险，再使用 --force。
5. 复查
完成前检查：
AGENTS.md 内容是否能追溯到真实文件、命令或用户指令- 子目录规则是否只保留差异
CLAUDE.md 是否为相对软链接 AGENTS.md- 是否更新了项目要求同步的上层 AGENTS/CLAUDE 文档
- 是否运行了可用验证命令；没运行必须说明原因
输出要求
最终回复列出创建/更新的目录、软链状态和验证命令。不要把完整 AGENTS.md 内容贴回聊天，除非用户要求审阅全文。
