agent-md-advisor

Original：🇨🇳 Chinese

Translated

Best Practice Advisor for AGENTS.md / CLAUDE.md. It is used when users ask about the format, structure, and best practices of agents markdown, AGENTS.md, CLAUDE.md, Claude Code memory, and AI coding agent instruction files; it also supports reviewing, diagnosing, rewriting, optimizing, or creating agent instruction files such as AGENTS.md, CLAUDE.md, CLAUDE.local.md, and .claude/rules from scratch. It is not suitable for general README writing unless the goal is to provide project context for AI coding agents.

10installs

Sourcechujianyun/skills

Added on2026-05-24

NPX Install

npx skill4agent add chujianyun/skills agent-md-advisor

SKILL.md Content (Chinese)

View Translation Comparison →

Agent Markdown Advisor

Helps users answer, review, optimize, and create AI coding agent instruction files, with a focus on

AGENTS.md

and

CLAUDE.md

.

Design Patterns

This skill mainly adopts:

Advisor: Answers best practice questions about format, structure, what to include/exclude, etc.
Reviewer: Diagnoses whether existing
```
AGENTS.md
```
/
```
CLAUDE.md
```
violate best practices
Generator: Creates new instruction files based on projects and user descriptions
Editor: Directly modifies relevant files when users explicitly request optimization

Gotchas

Don't write
```
AGENTS.md
```
/
```
CLAUDE.md
```
as project encyclopedias, README duplicates, or complete API documentation
Don't write
```
AGENTS.md
```
/
```
CLAUDE.md
```
as persona manuals, slogan walls, or wish lists; it should read like a technical briefing for senior engineers
Don't rewrite rules that can be enforced by linters, formatters, or type checkers into large amounts of natural language
Don't write actual secrets, tokens, production connection strings, customer data, or internal security details; only write the location of secrets and access methods
Don't invent commands out of thin air; first check verifiable sources like
```
package.json
```
,
```
pyproject.toml
```
,
```
Makefile
```
, CI workflows, README, etc.
Don't default to suggesting complex
```
.claude/agents
```
, hooks, MCP, skills; first determine if the project actually needs them
If users only request diagnosis, don't directly modify files; if users say "optimize, rewrite, create, execute", you can implement modifications
Keep files short and actionable:
```
AGENTS.md
```
should ideally be within 150 lines,
```
CLAUDE.md
```
should be prioritized to 80-120 lines, and strongly consider splitting if it exceeds 200 lines

Working Modes

First determine which category the user's request falls into:

Q&A Mode: Explains format, sections, hierarchy, differences between AGENTS.md and CLAUDE.md, and best practices.
Diagnosis Mode: Users have existing files and want to identify issues, violated practices, and improvement suggestions.
Optimization Mode: Users explicitly request modification, rewriting, compression, organization, or "execute optimization".
Creation Mode: Users don't have files yet, or want to generate
```
AGENTS.md
```
/
```
CLAUDE.md
```
based on descriptions.

Usage Flow

Copy this checklist and track progress:

text

Processing Progress:
- [ ] Step 1: Identify mode and target files
- [ ] Step 2: Read necessary reference materials
- [ ] Step 3: Read project context or user-provided content
- [ ] Step 4: Provide diagnosis, solution, or draft
- [ ] Step 5: If user requests implementation, modify files and verify

Step 1: Identify Mode and Target Files

Prioritize judging the target:

Cross-tool, Codex, Copilot, Cursor, general AI coding agents: Prioritize
```
AGENTS.md
```
Claude Code project memory, Claude-specific rules: Prioritize
```
CLAUDE.md
```
Work preferences repeated across projects: Prioritize placing in global/user-level configurations
Current project, tech stack, architecture, and commands: Prioritize placing in repo-level
```
AGENTS.md
```
/
```
CLAUDE.md
```
Personal local preferences: Prioritize
```
CLAUDE.local.md
```
or user-level memory, do not submit to team-shared files
Monorepo or multi-tech stack: Consider root directory files + subdirectory nested files

If users don't specify a file name:

Want general standards: Recommend
```
AGENTS.md
```
Mainly use Claude Code: Recommend
```
CLAUDE.md
```
Use multiple tools simultaneously: Recommend focusing on
```
AGENTS.md
```
, and use
```
CLAUDE.md
```
or symbolic links for compatibility depending on tool support

Step 2: Read Necessary References

Answering best practice questions: Read references/best-practices.md
Reviewing or scoring existing files: Read references/review-rubric.md
Creating or rewriting files: Read references/templates.md
When needing to trace source basis: Read references/source-notes.md

Step 3: Read Project Context

Before diagnosing or creating files, first read the minimum necessary context:

Target files:
```
AGENTS.md
```
,
```
CLAUDE.md
```
,
```
CLAUDE.local.md
```
Project overview:
```
README.md
```

Tech stack and commands:

package.json

,

pyproject.toml

,

Makefile

,

justfile

,

Taskfile.yml

,

pnpm-workspace.yaml

Testing and CI:

.github/workflows/

,

pytest.ini

,

vitest.config.*

,

tsconfig.json

Existing AI configurations:

.claude/

,

.cursor/rules/

,

.github/copilot-instructions.md

Only read files relevant to the judgment. Don't scan the entire repository just to write instruction files.

Step 4: Output Methods

Q&A Mode

Answer in concise English and provide actionable judgments:

markdown

Conclusion: ...

Recommended Structure:
- ...

Notes:
- ...

Diagnosis Mode

Must clearly provide conclusions and priorities:

markdown

# Agent Instruction File Diagnosis

Conclusion: Excellent / Basically Usable / Needs Refactoring / High Risk
Maturity Level: One level from L0-L6

## Key Issues
1. [P1] ...
2. [P2] ...

## Strengths
- ...

## Optimization Suggestions
1. ...
2. ...

## Recommended Changes
- Keep: ...
- Remove: ...
- Split: ...
- Add: ...

If specific lines can be located, reference the file path and line numbers. Issues should be judged based on "Will removing this line make the agent more likely to make mistakes?", not just text polishing.

Optimization Mode

First perform a quick diagnosis, then directly edit. Editing principles:

Retain real, stable, globally applicable information
Remove vague, repetitive, outdated, overly detailed, or easily inferable information from code
Rewrite long SOPs, API documentation, and style guides into "Read when" references
Replace commands with copyable real commands
Compress hard rules into checklists that can prevent specific errors; reserve
```
MUST
```
/
```
MUST NOT
```
only for a few key constraints
Clearly write security boundaries and high-risk operations

After completion, explain what was changed and suggest users run common tasks to verify.

Creation Mode

Generate files based on user descriptions and project context. If information is insufficient, first create a conservative minimal viable version, don't invent complex rules.

Prioritize including the following when creating:

One-sentence project context
Tech stack
Common commands
Architecture map / code placement rules
Hard rules and non-default conventions
Testing and completion standards
Security and permission boundaries
Reference documents and "Read when" trigger conditions

Review Principles

For every line, ask: "If I delete this line, will the agent be more likely to make mistakes?"
Write project-specific, non-obvious, actionable rules
Replace vague statements like "run tests" "build normally" with precise commands
Point to real code patterns using file paths and good/bad examples
Use progressive disclosure for long content: Root files only handle routing and key constraints
Separate Global / Project / Local layers, avoid mixing personal habits and project facts in the same shared file
Only add rules after the agent repeatedly makes the same mistake, avoid writing a giant manual at the start
Leave deterministic checks to tools, write strategies, boundaries, and exceptions for agents
Treat instruction files as code: Review, prune, and commit as the project changes