Guide · Agent skill

How to use the CLAUDE.md Writer agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The claude-md skill is an agent skill that helps an AI coding agent create, update or audit a CLAUDE.md file, the project instruction file Claude reads at the start of sessions in a codebase. It is aimed at developers setting up a repository for AI agents, teams trimming a bloated CLAUDE.md, and anyone who wants an audit without changes. After this guide you will know what the skill does, how to install it, and how to ask for each of its three modes.

CLAUDE.md Writerluongnv89/claude-howto · MIT Download the skill

Quick start

1Download the skill ZIP. Get the claude-md ZIP from the page. It contains a single SKILL.md file.
2Unzip into the skills folder. Place the skill in ~/.claude/skills/ for personal use, or in .claude/skills/ inside a project for that repository only.
3Or upload it in the Claude apps. Open Settings, choose Capabilities, then Skills, and upload the skill.
4Ask for the mode you need. Request create, update or audit in plain language, and optionally name a path such as src/api/CLAUDE.md.
5Review the draft or report. For create and update, check the proposed changes. The skill writes files only after you approve them. Audit makes no changes.
6Verify commands yourself. The skill's checklist says commands must be checked before inclusion, so run each build and test command in your project to confirm it works.

What is an agent skill and what does claude-md do?

An agent skill is a folder with a SKILL.md file that gives an AI agent specific instructions for a task. When the skill is installed, the agent can follow its workflow when a matching request comes up.

The claude-md skill tells the agent to analyze your project first: the stack, the structure, and existing documentation such as README.md and package.json. It then works in one of three modes: create a new CLAUDE.md, update an existing one, or audit one and report on it without changing the file.

Keep the file short, with a target under about 200 lines.
Include only information that applies to every session.
Leave out style rules and code snippets; point to deterministic tools and files instead.
Optionally move detailed material into separate docs, such as an agent_docs/ folder.
Cover AGENTS.md handling for newer Claude Code versions.

Install the claude-md skill

Download the ZIP for the skill from the page. It contains SKILL.md. Unzip it so the skill folder lands in your personal skills directory, ~/.claude/skills/, or in a project's .claude/skills/ folder if you want it only for one repository.

Alternatively, in the Claude apps, open Settings, then Capabilities, then Skills, and upload the skill there.

Personal install: ~/.claude/skills/
Project install: .claude/skills/ inside your repository
Claude apps: Settings → Capabilities → Skills, then upload

How to trigger the skill with natural requests

You do not need a special command. Ask in plain language for a CLAUDE.md task, and say which mode you want. The skill's instructions recognize three modes: create, update and audit. You can also name a specific path, such as src/api/CLAUDE.md for instructions that apply to one directory.

If you give no mode, the skill defaults to create, which means it drafts a file, shows you the draft for review, and writes it only after you approve.

"Create a CLAUDE.md for this repository."
"Update my CLAUDE.md and make it shorter."
"Audit the CLAUDE.md in this project and give me a report. Do not change anything."
"Write a CLAUDE.md for src/api/ with only the rules that apply there."

What the three modes produce

Create follows a fixed sequence: analyze the project, draft the file using the standard sections (project name, tech stack, project structure only for monorepos or complex layouts, development commands, critical conventions, known pitfalls), show the draft, and save it after approval.

Update reads the existing file and audits it against the same practices. It identifies content to remove, such as style rules, code snippets and task-specific instructions, content to shorten, and important missing information. It shows the changes for review before applying them.

Audit reads the file and produces a report with the current line count compared with the target, the share of content that applies to every session, a list of anti-patterns found, and recommendations. It does not modify the file.

Examples of what the skill checks

The skill's checklist asks whether each line applies to all sessions, whether commands have been verified to work, whether critical pitfalls are documented, and whether the file duplicates README.md. It also flags code snippets and tells you to use file:line references instead, to avoid stale context.

For large projects the skill recommends a agent_docs/ folder with files such as building_the_project.md, running_tests.md, code_conventions.md and architecture_decisions.md, linked from CLAUDE.md with a sentence such as: For detailed build instructions, refer to agent_docs/building_the_project.md.

Flag: style or formatting rules (suggest a linter such as prettier or eslint instead).
Flag: copied code examples (replace with file references).
Flag: task-specific instructions (move to separate files).
Flag: content that repeats package.json or README.md.

agent_docs/
  |- building_the_project.md
  |- running_tests.md
  |- code_conventions.md
  |- architecture_decisions.md

Handling AGENTS.md

If you ask for an AGENTS.md file, the skill explains that from Claude Code v2.1.277 the tool reads AGENTS.md directly as project instructions, but only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the working directory or any parent. The behavior is set by Project instructions in /config. Older versions, and some setups such as Bedrock, Vertex, Foundry, LLM gateways or disabled telemetry, need a fallback: import AGENTS.md from CLAUDE.md with @AGENTS.md, or make CLAUDE.md a symbolic link to it.

The skill notes that subagents are defined separately in .claude/agents/*.md, not in AGENTS.md.

@AGENTS.md

What people use it for

Setting up a new repository so an AI coding agent gets a short, accurate project overview on its first session.
Cutting a bloated CLAUDE.md down to a focused file by removing style rules and copied code.
Getting an audit report on an existing CLAUDE.md, with line count, anti-patterns and recommendations, without touching the file.
Writing a directory-level CLAUDE.md for one part of a monorepo, such as src/api/.

Frequently asked questions

Is the claude-md skill free to use?

The source states the skill is licensed under MIT. It does not list prices, so check the repository and the Claude plan you use for any cost of the tool itself.

What do I need to run the claude-md skill?

The source lists no specific requirements. It has no scripts and makes no network calls, and it is a single SKILL.md file. The output is specific to a code repository, so it is most useful when you have a project.

Does the skill write CLAUDE.md automatically?

No. The skill's own guidance says CLAUDE.md should be written by hand, and in create mode it shows a draft for review and saves only after approval. That is why it is not suited to projects that want fully automatic generation.

Can I use claude-md for AGENTS.md too?

Yes, the skill covers AGENTS.md handling. It explains that newer Claude Code versions read AGENTS.md directly when no CLAUDE.md is present, and gives a fallback for older versions using @AGENTS.md or a symbolic link.

Why does the skill want my CLAUDE.md under 200 lines?

The skill says the most capable LLMs can follow roughly 150 to 200 instructions, and Claude Code's system prompt already uses about 50. A shorter file leaves more room, and content that applies only to some tasks belongs in separate files.

How is claude-md different from just asking the agent to write a CLAUDE.md?

The skill gives the agent a fixed workflow: analyze the project, apply the same length, scope and anti-pattern rules, and offer create, update or audit modes. Without it, the agent has no defined checklist to follow.

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

Use claude-md if you are setting up a repository for AI coding agents, want to trim a long CLAUDE.md, or want a read-only audit. Skip it if you want instructions generated automatically, or if you do not have a code project, since the output is specific to a repository. The instructions are written in Ukrainian, so non-Ukrainian readers should expect that when reading the skill's own text.

Download the skill