# Claude Md

Create or update CLAUDE.md files following best practices for optimal AI agent onboarding

- Repository: https://github.com/luongnv89/claude-howto (46363 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-29
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add luongnv89/claude-howto --skill claude-md -g -a claude-code -y`
Codex: `npx skills add luongnv89/claude-howto --skill claude-md -g -a codex -y`
Cursor: `npx skills add luongnv89/claude-howto --skill claude-md -g -a cursor -y`
Gemini CLI: `npx skills add luongnv89/claude-howto --skill claude-md -g -a gemini-cli -y`

## Description

Create or update CLAUDE.md files following best practices for optimal AI agent onboarding

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

## User Input

```text
$ARGUMENTS
```

You **MUST** consider the user input before proceeding (if not empty). User may specify:
- `create` - Create new CLAUDE.md from scratch
- `update` - Improve existing CLAUDE.md
- `audit` - Analyze and report on current CLAUDE.md quality
- A specific path to create/update (e.g., `src/api/CLAUDE.md` for directory-specific instructions)

## Core Principles

**LLMs are stateless**: CLAUDE.md is the main project file loaded into every conversation (alongside auto memory and unscoped rules). It serves as the primary onboarding document for AI agents into your codebase.

### The Golden Rules

1. **Less is More**: Frontier LLMs can follow ~150-200 instructions. Claude Code's system prompt already uses ~50. Keep your CLAUDE.md focused and concise.

2. **Universal Applicability**: Only include information relevant to EVERY session. Task-specific instructions belong in separate files.

3. **Don't Use Claude as a Linter**: Style guidelines bloat context and degrade instruction-following. Use deterministic tools (prettier, eslint, etc.) instead.

4. **Never Auto-Generate**: CLAUDE.md is the highest leverage point of the AI harness. Craft it manually with careful consideration.

## Execution Flow

### 1. Project Analysis

First, analyze the current project state:

1. Check for existing CLAUDE.md files:
   - Root level: `./CLAUDE.md` or `.claude/CLAUDE.md`
   - Directory-specific: `**/CLAUDE.md`
   - Global user config: `~/.claude/CLAUDE.md`

2. Identify the project structure:
   - Technology stack (languages, frameworks)
   - Project type (monorepo, single app, library)
   - Development tools (package manager, build system, test runner)

3. Review existing documentation:
   - README.md
   - CONTRIBUTING.md
   - package.json, pyproject.toml, Cargo.toml, etc.

### 2. Content Strategy (WHAT, WHY, HOW)

Structure CLAUDE.md around three dimensions:

The rest: https://github.com/luongnv89/claude-howto/blob/HEAD/03-skills/claude-md/SKILL.md