| name | agent-md-advisor |
| description | AGENTS.md / CLAUDE.md 最佳实践顾问。用于用户询问 agents markdown、AGENTS.md、CLAUDE.md、Claude Code memory、AI coding agent 指令文件的格式、结构、最佳实践；也用于审查、诊断、重写、优化或从零创建 AGENTS.md、CLAUDE.md、CLAUDE.local.md、.claude/rules 等 agent 指令文件。不适用于通用 README 写作，除非目标是给 AI coding agent 提供项目上下文。 |
Agent Markdown Advisor
帮助用户回答、审查、优化和创建 AI coding agent 指令文件，重点覆盖 AGENTS.md 与 CLAUDE.md。
设计模式
本 skill 主要采用：
- Advisor：回答格式、结构、放什么/不放什么等最佳实践问题
- Reviewer：诊断已有
AGENTS.md / CLAUDE.md 是否违反最佳实践
- Generator：根据项目和用户描述创建新的指令文件
- Editor：用户明确要求执行优化时，直接修改相关文件
Gotchas
- 不要把
AGENTS.md / CLAUDE.md 写成项目百科、README 复制品或完整 API 文档
- 不要把
AGENTS.md / CLAUDE.md 写成人设说明书、口号墙或愿望清单；它应该像给资深工程师的技术简报
- 不要把 linter、formatter、类型检查器能确定执行的规则改写成大量自然语言
- 不要写实际密钥、token、生产连接串、客户数据或内部安全细节；只写密钥位置和访问方式
- 不要凭空发明命令；先看
package.json、pyproject.toml、Makefile、CI workflow、README 等可验证来源
- 不要默认建议复杂
.claude/agents、hooks、MCP、skills；先判断项目是否真的需要
- 如果用户只要求诊断，不要直接改文件；如果用户说“优化、重写、创建、执行”，可以落地修改
- 保持文件短而可执行：
AGENTS.md 理想上 150 行以内，CLAUDE.md 优先压到 80-120 行，超过 200 行要强烈考虑拆分
工作模式
先判断用户需求属于哪一类：
- 问答模式：解释格式、章节、层级、AGENTS.md 和 CLAUDE.md 区别、最佳实践。
- 诊断模式：用户已有文件，希望指出问题、违反的实践和改进建议。
- 优化模式：用户明确要求修改、重写、压缩、整理或“执行优化”。
- 创建模式：用户还没有文件，或希望根据描述生成
AGENTS.md / CLAUDE.md。
使用流程
复制此清单并跟踪进度：
处理进度：
- [ ] 步骤 1：识别模式和目标文件
- [ ] 步骤 2：读取必要参考资料
- [ ] 步骤 3：读取项目上下文或用户提供内容
- [ ] 步骤 4：给出诊断、方案或草稿
- [ ] 步骤 5：如用户要求落地，修改文件并验证
Step 1: 识别模式和目标文件
优先判断目标：
- 跨工具、Codex、Copilot、Cursor、通用 AI coding agent：优先
AGENTS.md
- Claude Code 项目记忆、Claude 专属规则：优先
CLAUDE.md
- 每个项目都会重复的工作偏好：优先放 global/user 级配置
- 当前项目、技术栈、架构和命令：优先放 repo 内
AGENTS.md / CLAUDE.md
- 个人本地偏好：优先
CLAUDE.local.md 或用户级 memory，不要提交到团队共享文件
- Monorepo 或多技术栈：考虑根目录文件 + 子目录嵌套文件
如果用户没有指定文件名：
- 想要通用标准：建议
AGENTS.md
- 主要使用 Claude Code：建议
CLAUDE.md
- 同时使用多种工具：建议以
AGENTS.md 为主，并视工具支持情况用 CLAUDE.md 或符号链接兼容
Step 2: 读取必要参考
Step 3: 读取项目上下文
诊断或创建文件前，先读取最小必要上下文：
- 目标文件：
AGENTS.md、CLAUDE.md、CLAUDE.local.md
- 项目概览：
README.md
- 技术栈和命令：
package.json、pyproject.toml、Makefile、justfile、Taskfile.yml、pnpm-workspace.yaml
- 测试和 CI：
.github/workflows/、pytest.ini、vitest.config.*、tsconfig.json
- 现有 AI 配置：
.claude/、.cursor/rules/、.github/copilot-instructions.md
只读与判断有关的文件。不要为了写指令文件而扫描整个仓库。
Step 4: 输出方式
问答模式
用简洁中文回答，并给出可操作判断：
结论：...
推荐结构：
- ...
注意事项：
- ...
诊断模式
必须明确给结论和优先级：
# Agent 指令文件诊断
结论：优秀 / 基本可用 / 需要重构 / 风险较高
成熟度：L0-L6 中的某一级
## 主要问题
1. [P1] ...
2. [P2] ...
## 做得好的地方
- ...
## 优化建议
1. ...
2. ...
## 建议改法
- 保留：...
- 删除：...
- 拆分：...
- 新增：...
如果能定位具体行，引用文件路径和行号。问题要围绕“会不会让 agent 更可靠”判断，不要只做文字润色。
优化模式
先快速诊断，再直接编辑。编辑原则：
- 保留真实、稳定、全局适用的信息
- 删除空泛、重复、过期、过细、容易从代码推断的信息
- 把长 SOP、API 文档、风格指南改成“Read when”引用
- 把命令改成可复制的真实命令
- 把硬规则压缩成能阻止具体错误的清单，
MUST / MUST NOT 只留给少数关键约束
- 把安全边界和高风险操作写清楚
完成后说明改了什么，并建议用户实际跑一次常见任务来验证。
创建模式
根据用户描述和项目上下文生成文件。信息不足时先创建保守的最小可用版本，不要臆造复杂规则。
创建时优先包含：
- 项目一句话上下文
- 技术栈
- 常用命令
- 架构地图 / 代码放置规则
- 硬规则和非默认约定
- 测试和完成标准
- 安全和权限边界
- 参考文档及 Read when 触发条件
审查原则
- 每一行都要回答：“删掉这行，agent 会更容易犯错吗？”
- 写项目特有的、非显然的、可执行的规则
- 用精确命令替代“运行测试”“正常构建”等模糊说法
- 用文件路径和好/坏示例指向真实代码模式
- 用渐进披露承载长内容：根文件只做路由和关键约束
- 把 Global / Project / Local 三层分开，避免把个人习惯和项目事实混在同一个共享文件里
- 在 agent 反复犯同一种错误后再补规则，避免一开始写成巨型说明书
- 把确定性检查交给工具，把策略、边界和例外写给 agent
- Treat instruction files as code：随项目变化审查、修剪和提交
