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 行要强烈考虑拆分

工作模式

先判断用户需求属于哪一类：

1. 问答模式：解释格式、章节、层级、AGENTS.md 和 CLAUDE.md 区别、最佳实践。
2. 诊断模式：用户已有文件，希望指出问题、违反的实践和改进建议。
3. 优化模式：用户明确要求修改、重写、压缩、整理或“执行优化”。
4. 创建模式：用户还没有文件，或希望根据描述生成 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: 读取必要参考

• 回答最佳实践问题：读 references/best-practices.md
• 审查或评分已有文件：读 references/review-rubric.md
• 创建或重写文件：读 references/templates.md
• 需要追溯资料依据时：读 references/source-notes.md

Step 3: 读取项目上下文

诊断或创建文件前，先读取最小必要上下文：