Guide · Agent skill
How to use the CLAUDE.md Writer agent skill (claude-md)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The claude-md skill teaches an AI coding agent how to write and maintain CLAUDE.md, the project instruction file that the agent reads at the start of every session in a codebase. This guide is for developers and maintainers who want to install the skill, ask the agent to create, update or audit a CLAUDE.md, and review the result before anything is saved. By the end you will know what the skill does, how to install it, and how to phrase requests so the agent uses it correctly.
CLAUDE.md Writerluongnv89/claude-howto · MIT Download the skill Quick start
- 1Download and unzip. Download the claude-md ZIP from this page and unzip it. Confirm that SKILL.md is inside the folder.
- 2Choose the install location. Place the folder in ~/.claude/skills/ for all projects, or in the project's .claude/skills/ for one project. In the Claude apps, upload it under Settings, Capabilities, Skills.
- 3Open your project. Start your AI coding agent in the repository you want to document, so it can analyze the project files.
- 4Make a request. Ask for create, update, audit, or give a path such as a subfolder CLAUDE.md. Leave the input empty to get the default create behaviour.
- 5Review the draft. Read the proposed file or change list. The agent writes or applies changes only after you approve.
- 6Keep it short. Check the result against the 200-line target and remove anything that is not needed in every session.
What the claude-md skill makes the agent do
An agent skill is a folder containing a SKILL.md file with instructions that the agent loads when it is relevant. This skill's instructions cover how to write a CLAUDE.md: a short, focused file with build and test commands, key conventions and gotchas that every session can rely on.
Following its own rules, the agent first analyzes your project. It checks for existing CLAUDE.md files, identifies the technology stack and development tools, and reviews documents such as README.md and CONTRIBUTING.md. It then drafts a file organized around what the project is made of, why it is built that way, and how to work in it.
- Keeps the file under 200 lines, and shorter is better
- Includes only information that applies to every session
- Leaves out style and formatting rules, which belong in linters such as prettier or eslint
- Avoids copied code snippets and uses file references instead
- Avoids repeating what is already in package.json or README.md
- Never auto-generates the file; it asks you to review the draft first
Install the claude-md skill
Download the ZIP for the claude-md skill from this page and unzip it. The skill is a single file, SKILL.md, inside its folder. Put the folder in one of the two locations below, depending on whether you want the skill for all your projects or one project only.
If you use the Claude apps instead, you can upload the skill there under Settings, then Capabilities, then Skills.
- For all your projects: unzip into ~/.claude/skills/
- For one project only: unzip into the project's .claude/skills/ folder
- In the Claude apps: Settings → Capabilities → Skills, then upload the skill
Trigger the skill with a natural request
The skill reads what you type after it is invoked. It accepts one of four kinds of input: create, update, audit, or a specific path to create or update. If you give no input, it defaults to creating a new file.
Path inputs let you target directory-specific files. For example, a path to a CLAUDE.md inside a subfolder asks for instructions limited to that part of the codebase. The skill says these files should be even more focused than the root file.
- create: start a new CLAUDE.md from scratch for the project
- update: improve an existing CLAUDE.md
- audit: report on the quality of the current file without changing it
- A path such as a subfolder CLAUDE.md: create or update instructions for that directory only
What happens during create and update
For create, the agent analyzes the project, drafts the file, presents the draft for review, and writes it only after you approve. For update, it reads the existing file, audits it against the best practices, and lists what to remove, what to condense and what is missing. It presents those changes and applies them only after approval.
The skill suggests a standard set of sections: tech stack, project structure (only for monorepos or complex layouts), development commands, critical conventions, and known issues or gotchas. Include only sections that help an agent work in your project.
- Essential sections: Tech Stack, Project Structure, Development Commands, Critical Conventions, Known Issues / Gotchas
- For larger projects, the skill suggests putting detailed guides in an agent_docs/ folder and referencing them from CLAUDE.md
- Commands should be verified to work before they are included
Run a read-only audit of an existing CLAUDE.md
Use audit when you want a quality check without edits. The agent reads the current file and produces a report. The report includes the current line count compared with the target, the share of content that applies to every session, the anti-patterns it found, and recommendations.
Audit mode does not modify the file. This makes it a safe first step for teams whose CLAUDE.md has grown long.
- Line count against the 200-line target
- Percentage of universally applicable content
- List of anti-patterns found
- Recommendations for improvement
Use it for AGENTS.md files too
The skill includes guidance for AGENTS.md, a cross-tool project context file. It is the same kind of document as CLAUDE.md, used so that several coding agents can share one set of project conventions. The skill says to apply the same principles: stay focused, use progressive disclosure, and reference external docs instead of embedding them.
The skill also notes that subagents are defined separately in .claude/agents/*.md, not in AGENTS.md. Recent Claude Code behavior can read AGENTS.md directly when no CLAUDE.md exists in the working directory or in any directory above it. Where that is not available, the skill describes importing AGENTS.md from CLAUDE.md with @AGENTS.md, or symlinking CLAUDE.md to it.
- Keep AGENTS.md focused and concise
- Put build, test and lint commands, code conventions and repository layout in it
- Put subagent definitions in .claude/agents/*.md instead
Safety notes before you install
According to the skill's listing, it requires nothing beyond what is listed, it does not run scripts, and it does not use the network. The only file in the package is SKILL.md, so you can open it and read every instruction before installing.
The agent still writes to your repository when you approve a draft, so review the diff. Because the skill is MIT licensed, you can read, copy and modify it under the terms of that licence.
- Requires: nothing listed
- Runs scripts: no
- Uses network: no
- Files: SKILL.md only
What people use it for
- Setting up a new repository so the coding agent starts with the build, test and run commands
- Condensing a CLAUDE.md that has grown long and repetitive
- Running a read-only audit to spot style rules, copied code and task-specific instructions
- Adding a focused CLAUDE.md to a subfolder with its own conventions
- Writing an AGENTS.md so several coding agents share the same project conventions
Frequently asked questions
How do I install the claude-md skill?
Download the ZIP from this page and unzip it. Put the folder in ~/.claude/skills/ to use it across projects, or in a project's .claude/skills/ folder to use it in one project. In the Claude apps, you can upload it under Settings, then Capabilities, then Skills.
What do I need to run the claude-md skill?
The skill listing says it requires nothing beyond what is listed, runs no scripts and uses no network. The output is only useful to an AI coding agent that reads CLAUDE.md, so you need such an agent in your project.
Is the claude-md skill free?
The skill is published under the MIT licence, which the listing states. The source does not mention pricing, so check the page for current details on any cost.
Can the skill write the CLAUDE.md file automatically?
No. The skill explicitly discourages auto-generated files. It drafts the content, presents it for review, and writes it only after you approve.
What is the difference between create, update and audit?
Create builds a new CLAUDE.md from scratch. Update improves an existing file by removing, condensing and adding content after your approval. Audit reports on quality and does not modify the file.
What should I do if the skill does not respond as expected?
Check that the folder with SKILL.md is in one of the supported locations, and that you are working in the right project. The source does not list other troubleshooting steps, so check the file contents against the skill's instructions.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Choose this skill if you are setting up a repository for an AI coding agent or need to trim a bloated CLAUDE.md, and you want to review every change before it is written. Pick something else if you want fully automatic generation, or if you do not use an AI coding agent that reads CLAUDE.md.
Download the skill