claude-md — Skill para CLAUDE.md Otimizado
WaiYanNyeinNaing/claude-md-skill
Disciplina para CLAUDE.md lean e projetos agentic multi-sessão
Ver no GitHubSkill que ensina como escrever CLAUDE.md enxuto e eficiente, mantendo apenas linhas que importam para o contexto de sessões com Claude Code. Inclui módulos para projetos agentic de longa duração com gestão de estado entre sessões e context compaction.
Instalação
npx convez-ai WaiYanNyeinNaing/claude-md-skill1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Auditar e otimizar CLAUDE.md existentes para reduzir consumo de tokens
- Estruturar CLAUDE.md com WHY → WHAT → HOW para máxima clareza
- Configurar projetos agentic que precisam manter estado entre múltiplas sessões
- Usar progressive disclosure com @imports e rules/ em monorepos
Veredito

Ferramenta essencial para quem trabalha com Claude Code em projetos reais. Resolve um problema concreto — context bloat — com disciplina prática e templates prontos para copiar. Recomendado para equipes que precisam escalar agentes de IA.
README
A tradução para o português deste README ainda está na fila.
claude-md — a Claude Code Skill
Best practices for writing, auditing, and maintaining
CLAUDE.mdcontext files — plus a module for agentic, long-running engineering.
A Claude Code skill that teaches the agent how to produce lean, high-signal CLAUDE.md files instead of bloated ones — and how to keep context alive across long, multi-session, agentic projects.
Why this exists
A CLAUDE.md is a context-injection file, not documentation. It is read into the context window at the start of every session, so every line spends budget that could otherwise go to the actual code. The most common failure is treating it like a wiki: a sprawling 250-line file buries the rules that matter, and Claude starts ignoring them.
This skill encodes the discipline that fixes that — and extends it to production AI systems and work that spans weeks or months, where state has to survive context compaction and fresh windows.
What it does
When active, the skill guides Claude to:
- Keep
CLAUDE.mdunder ~200 lines using the test for every line — "if I remove this, will Claude make a mistake?" - Structure the file WHY → WHAT → HOW (context → commands → structure → conventions → references).
- Apply progressive disclosure — push detail into
@imports,.claude/rules/*.md,.claude/skills/, anddocs/with "Read when" triggers, so it loads only when a task needs it. - Lay out monorepos correctly — shared conventions at the root, service-specific context in child directories.
- Run agentic / long-running projects — separate the harness memory from the shipped agent's memory, use the initializer + coding-agent harness (
feature_list.json,claude-progress.txt,init.sh, frequent commits), and survive context compaction by keeping durable state outside the conversation.
It ships with copy-ready templates and worked examples for all of the above.
Installation
Option A — Plugin marketplace (recommended)
Inside Claude Code:
/plugin marketplace add WaiYanNyeinNaing/claude-md-skill
/plugin install claude-md@claude-md-marketplace
Update later with /plugin marketplace update claude-md-marketplace.
Option B — Install script
Clone the repo and run the installer:
git clone https://github.com/WaiYanNyeinNaing/claude-md-skill.git
cd claude-md-skill
./install.sh # global → ~/.claude/skills/claude-md (all projects)
./install.sh .claude/skills # project-local → ./.claude/skills/claude-md (shareable with your team)
Then start a new Claude Code session — the skill is discovered automatically by its name and description.
Usage
The skill loads on demand when your request matches what it covers. Try prompts like:
- "Audit my CLAUDE.md."
- "Write a CLAUDE.md for this repo."
- "Trim my CLAUDE.md — Claude keeps ignoring the rules in it."
- "Set up Claude Code for a long-running agent project."
- "How do I keep context across sessions? My agent forgets things between runs."
You can also invoke it explicitly with /claude-md.
What's inside
skills/claude-md/
├── SKILL.md # the skill instructions + frontmatter
├── assets/
│ ├── claude-md-template.md # starter template for a standard project
│ ├── agentic-claude-md-template.md # template with a session/recovery protocol baked in
│ ├── feature_list.json # scope checklist for the long-running harness
│ ├── claude-progress.txt # running session-log template
│ ├── init.sh # environment-bootstrap / smoke-test target
│ └── rules-example.md # path-scoped .claude/rules/ example (globs frontmatter)
└── references/
├── examples.md # 3 worked examples (single project, monorepo, API integration)
└── agentic-engineering.md # full reference: memory layers, the harness, surviving compaction
How Agent Skills work
A skill is a self-contained folder with a SKILL.md file. Its YAML frontmatter (name + description) is always visible to Claude; the body and bundled files load only when the description matches the task — keeping the default context lean. Learn more:
Contributing
Issues and pull requests are welcome. If Claude makes a CLAUDE.md mistake this skill should have prevented, that's a great issue — it usually means a rule needs sharpening. Please keep changes aligned with the skill's own philosophy: lean, high-signal, and only what earns its place in context.
License
Apache-2.0 © Wai Yan Nyein Naing.
Acknowledgements
- Base
CLAUDE.mdpractices distilled from TurboDocx's "How to Write a CLAUDE.md File That Actually Works." - Agentic / long-running practices drawn from Anthropic's engineering writing — Effective harnesses for long-running agents, Effective context engineering for AI agents, and Writing tools for agents — and the Claude Code memory documentation. Full sources are listed in
skills/claude-md/references/agentic-engineering.md.