Skip to content
Get packs

Guide · Agent skill

How to use the CLAUDE.md Authoring Guide agent skill

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, update and audit a CLAUDE.md file, the short instruction file an agent reads at the start of sessions in a project. This guide explains what a skill is, how to install this one, how to ask for it in plain language and what to check before you approve the result. It is written for readers who have not used agent skills before.

CLAUDE.md Authoring Guideluongnv89/claude-howto · MIT

Quick start

  1. 1Download the ZIP. Get the claude-md ZIP file from this page.
  2. 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for all projects, or into the project's .claude/skills/ folder for one repository.
  3. 3Or upload in the Claude apps. If you use the Claude apps, go to Settings, then Capabilities, then Skills, and upload the ZIP.
  4. 4Ask in plain language. Request a create, update or audit of your CLAUDE.md, naming a path if the file is for a subdirectory.
  5. 5Review the draft. Read the proposed file and remove any line that is not needed in every session.
  6. 6Verify commands. Run each listed command yourself to confirm it works before you approve the file.

What an agent skill is and what claude-md does

An agent skill is a folder of instructions that an AI agent loads when a task matches the skill's description. The skill in this package is named claude-md and its description is to create or update CLAUDE.md files following best practices for AI agent onboarding.

Once installed, the agent analyzes your project first. It looks for existing CLAUDE.md files, identifies the tech stack and project type, and reviews existing docs such as README.md, CONTRIBUTING.md and package files. It then drafts a concise file covering the stack, commands and non-obvious conventions, and shows the draft to you for review before writing anything.

  • create: write a new CLAUDE.md from scratch
  • update: improve an existing CLAUDE.md
  • audit: analyze the current file and produce a report without changing it
  • a specific path, such as src/api/CLAUDE.md for directory-level instructions

Install the claude-md skill

Download the ZIP file from this page. Unzip it into one of two locations, depending on how you want to use the skill. To make it available across all your projects, unzip it into ~/.claude/skills/. To limit it to one repository, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

  • Personal (all projects): ~/.claude/skills/
  • Single project: the .claude/skills/ folder inside the repository
  • Claude apps: Settings → Capabilities → Skills, then upload

Trigger the skill with natural requests

You do not need special syntax. Describe what you want in plain language, and name the file or action if you have one in mind. The skill's guidance covers creating, updating and auditing these files, so requests that mention CLAUDE.md with one of those actions are the best fit.

If you already have a file, asking for an audit first is a safe choice, because the audit mode only reports problems and does not change anything.

  • Set up a CLAUDE.md for this repository from scratch.
  • Audit my CLAUDE.md and tell me what to remove.
  • Update the CLAUDE.md, it has grown long and some of it is out of date.
  • Create a CLAUDE.md for the src/api directory with only the instructions that apply there.

What the skill checks and produces

The guidance aims for a file of fewer than 200 lines that applies to every session. It leaves out code style rules, since the skill says those belong in deterministic tools such as prettier or eslint. It also leaves out task-specific instructions, copied code snippets and content already in package.json or the README.

For larger projects, the skill suggests an agent_docs/ folder with separate topic files, referenced from CLAUDE.md. It recommends file:line references instead of code snippets, because snippets go stale. A good file usually has sections for Tech Stack, Project Structure (monorepos or complex layouts only), Development Commands, Critical Conventions and Known Issues or Gotchas.

  • Under 200 lines
  • No style or formatting rules
  • No copied code snippets; use file references
  • No duplication of README or package.json content
  • Commands verified to work before they are included
For detailed build instructions, refer to `agent_docs/building_the_project.md`

Review and approve before anything is saved

The skill advises against fully automatic generation. CLAUDE.md is described as one of the most influential points in an AI harness, so the draft should be built and reviewed by hand. Read the proposed file line by line, and reject any line that does not apply to every session.

For update requests, the skill first reads the existing file and identifies what to delete, what to condense and which required information is missing, then shows those changes for approval.

  • Check that each line applies to every session.
  • Confirm each command actually runs in your environment.
  • Remove anything that repeats your README.
  • Keep the file short; when in doubt, leave it out.

What people use it for

  • Setting up Claude Code or another agent in a new repository with a concise instruction file.
  • Trimming a CLAUDE.md that has grown long, duplicated or outdated.
  • Writing separate instruction files for subdirectories in a monorepo.
  • Auditing an existing file for task-specific content, code snippets and style rules without changing it.

Frequently asked questions

Is the claude-md skill free?

The source material says the skill is released under the MIT licence. It does not list any price, so check the licence text on this page for the terms.

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

The skill lists no specific requirements. It is aimed at projects with a codebase that uses build, test and package tooling, so it is not meant for projects without code.

Does the claude-md skill run scripts or use the network?

No. The skill is listed as not running scripts and not using the network. It works through instructions the agent follows.

Can the skill write my CLAUDE.md automatically?

It can draft a file, but it shows the draft for your approval before saving. The skill itself advises against generating a full file without review.

Where should I put the skill folder?

Use ~/.claude/skills/ to make it available in all projects, or the project's .claude/skills/ folder to limit it to one repository. In the Claude apps, upload the ZIP under Settings, Capabilities, Skills.

Should I use this skill or a linter for code style?

Use a linter or formatter such as prettier or eslint for code style. The skill says style rules belong in those tools and should not be placed in CLAUDE.md.

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

This skill suits developers setting up an agent in a new repository, teams whose CLAUDE.md has become long or stale, and monorepo maintainers who want clear per-directory files. It is not a good fit for non-developers, for projects without a codebase, or for anyone who wants the agent to enforce code style or generate a full file with no review.

Download the skill