/agent-md-advisor

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 提供项目上下文。

BOOST

chujianyun@chujianyun

GitHub

From plugin

chujianyun-skills

74536 skills1 command

Install

$ npx -y skills add chujianyun/skills --skill agent-md-advisor --agent claude-code

How it fires

How this skill gets triggered: by you, by Claude, or both.

Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/agent-md-advisor

Context preview

The summary Claude sees to decide when to auto-load this skill.

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 提供项目上下文。

SKILL.md

agent-md-advisor.SKILL.md

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

工作模式

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

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/best-practices.md)
审查或评分已有文件：读 [references/review-rubric.md](references/review-rubric.md)
创建或重写文件：读 [references/templates.md](references/templates.md)
需要追溯资料依据时：读 [references/source-notes.md](references/source-notes.md)

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 更可靠”判断，不要只做文字润色。