Run any Skill in Manus with one click

claude-md-authoring

Stars25

Forks4

UpdatedMay 4, 2026 at 21:55

Best practices for writing effective CLAUDE.md files. Use when creating, updating, or auditing CLAUDE.md files for projects or directories.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

crouton-labs

crouton-labs/crouton-kit

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name	claude-md-authoring
description	Best practices for writing effective CLAUDE.md files. Use when creating, updating, or auditing CLAUDE.md files for projects or directories.
user-invocable	false
paths	["**/CLAUDE.md"]

Writing Effective CLAUDE.md Files

Philosophy

CLAUDE.md is a curated set of guardrails and pointers, not a comprehensive manual. Every line is scarce real estate. Focus on constraints and gotchas — things Claude would get wrong without guidance.

What to Include

Prioritize in order:

Critical constraints and gotchas — non-obvious rules, what breaks if ignored
Key commands — build, test, lint (the 80% cases)
Architecture overview — how major components relate, 2-3 sentences max
Conventions that differ from defaults — only what's surprising

What to Exclude

Anything Claude can infer from reading code
Standard language/framework conventions
Detailed API documentation (link to docs instead)
Long explanations or tutorials
File-by-file codebase descriptions
Information that changes frequently

Writing Rules

Short declarative bullets > paragraphs
Never write "Never X" without the preferred alternative
When referencing other docs, pitch when/why to read them (e.g., "For FooError, see docs/foo.md")
If guidance exceeds ~5 lines, it belongs in a skill or rule instead

Root vs Subdirectory

Root (~100-200 lines): Project-wide constraints, build/test commands, architecture. Loaded every session.

Subdirectory (<50 lines): Only create when:

Directory has >5 files or >3 subdirectories
Local conventions differ from project standards
Non-obvious constraints specific to this directory

Don't repeat parent CLAUDE.md content. Don't explain what's obvious from the directory name.

When to Use Something Else

>5 lines of domain knowledge → Skill (loaded on-demand, not every session)
File-type-specific constraints → Rule with paths frontmatter
Deterministic enforcement → Hook (can't be ignored)

Auditing Existing CLAUDE.md

For each line, ask: "Would Claude's behavior change if I removed this?" If no, cut it.

Signs of bloat:

300 lines
Claude ignores rules despite them being there (context dilution)
Generic best practices Claude already knows
Duplicated information from parent CLAUDE.md files

When adding content, always propose pruning alongside additions. The file should get tighter over time, not longer.

More from this repository

same repository

prompting-effectively

crouton-labs/crouton-kit

Structure Claude prompts for clarity and better results using roles, explicit instructions, context, positive framing, and strategic organization. Use when crafting prompts for complex tasks, long documents, tool workflows, or code generation.

2026-06-1125

humanloop

crouton-labs/crouton-kit

Pause agent execution to have the human validate decisions, choose between options, answer freetext, or comment on a document — via the `hl` CLI. Every interaction is a kickoff that returns a job handle immediately; collect the human's answer later with `hl job result`. Use for material design decisions, approval gates, picks between meaningful alternatives, and markdown doc review. Not for trivial yes/no confirmations the agent should decide itself.

2026-05-2825

review-design

crouton-labs/crouton-kit

Validate technical designs against requirements for coverage, feasibility, and architectural soundness. Use after creating a design.

2026-05-1225

review-plan

crouton-labs/crouton-kit

Validate implementation plans against requirements and design. Use after creating a plan to ensure full coverage and no ambiguities.

2026-05-1225

review-requirements

crouton-labs/crouton-kit

Validate requirements documents for EARS compliance, completeness, and consistency. Use after creating requirements.

2026-05-1225

cli-design

crouton-labs/crouton-kit

Design CLIs for humans and LLM agents — subcommand shape, output streams, exit codes, JSON modes, TTY-aware color, structured errors, mutation safety. Use when building or refactoring a CLI, adding machine-readable output, writing --help, deciding stdout vs stderr, or making a tool agent-friendly.

2026-05-1225

name	claude-md-authoring
description	Best practices for writing effective CLAUDE.md files. Use when creating, updating, or auditing CLAUDE.md files for projects or directories.
user-invocable	false
paths	["**/CLAUDE.md"]

Writing Effective CLAUDE.md Files

Philosophy

What to Include

Prioritize in order:

Critical constraints and gotchas — non-obvious rules, what breaks if ignored
Key commands — build, test, lint (the 80% cases)
Architecture overview — how major components relate, 2-3 sentences max
Conventions that differ from defaults — only what's surprising

What to Exclude

Anything Claude can infer from reading code
Standard language/framework conventions
Detailed API documentation (link to docs instead)
Long explanations or tutorials
File-by-file codebase descriptions
Information that changes frequently

Writing Rules

Short declarative bullets > paragraphs
Never write "Never X" without the preferred alternative
When referencing other docs, pitch when/why to read them (e.g., "For FooError, see docs/foo.md")
If guidance exceeds ~5 lines, it belongs in a skill or rule instead

Root vs Subdirectory

Root (~100-200 lines): Project-wide constraints, build/test commands, architecture. Loaded every session.

Subdirectory (<50 lines): Only create when:

Directory has >5 files or >3 subdirectories
Local conventions differ from project standards
Non-obvious constraints specific to this directory

Don't repeat parent CLAUDE.md content. Don't explain what's obvious from the directory name.

When to Use Something Else

>5 lines of domain knowledge → Skill (loaded on-demand, not every session)
File-type-specific constraints → Rule with paths frontmatter
Deterministic enforcement → Hook (can't be ignored)

Auditing Existing CLAUDE.md

For each line, ask: "Would Claude's behavior change if I removed this?" If no, cut it.

Signs of bloat:

300 lines
Claude ignores rules despite them being there (context dilution)
Generic best practices Claude already knows
Duplicated information from parent CLAUDE.md files

When adding content, always propose pruning alongside additions. The file should get tighter over time, not longer.