The proper format for a Claude Code command file is flexible: store a concise, human‑readable *.md* file (typically under `.claude/commands/`) that describes the task in natural language, optionally prefixed with an `@command.md
- Use `.md` files in a `.claude/commands/` folder.
- Keep descriptions short, clear, and written in natural language.
- Optional header `@command.md
` can clarify intent. - Markdown can be used for headings, lists, or examples.
- No strict syntax; readability is the priority.
Claude Code Command File Format – Quick Guide
1. What the format is (and isn’t)
- There is no mandatory syntax for Claude Code command files. The system accepts any markdown file that clearly describes the desired action 129.
- The emphasis is on clarity and human‑readability rather than a rigid schema 12.
2. Recommended file location & naming
| Aspect | Recommendation | Reason |
|---|---|---|
| Directory | ./.claude/commands/ (project‑root) |
Keeps all commands together and lets Claude discover them automatically 149 |
| File extension | .md (Markdown) |
Allows natural‑language text plus optional markdown formatting 49 |
| File name | Descriptive name of the command, e.g., build.md, lint-code.md |
The filename itself acts as the command identifier 49 |
.claude/
└── commands/
├── lint-code.md
├── build.md
└── deploy.md
3. Content structure
Natural‑language description – Write what you want Claude to do in plain English (or any language you prefer).
Example: “Run ESLint across the project and report any style violations.” 24Markdown formatting (optional) – Use headings, bullet points, or code fences to improve readability.
# Lint the project with ESLint - Run `eslint . --ext .js,.ts` - Output results to `eslint-report.txt`Optional command header – Some users prepend a line like
@command.md Lint the projectto make the intent explicit; it is not required but can be helpful 19.Additional helpers (optional)
4. Example command files
Simple command (lint-code.md)
# Lint the current project using ESLint
Run the ESLint command to check for code style issues and potential errors.
More detailed command with optional header (format-python.md)
@command.md Format Python files with Black
# Format Python files with Black
Use the `black` formatter to automatically format all `.py` files in the repository according to PEP 8.
5. Best‑practice checklist
- Store files under
.claude/commands/. - Use the
.mdextension. - Keep the description concise and in natural language.
- Add markdown headings or lists for readability.
- Include an
@command.mdheader only if you find it useful.
Following these guidelines ensures Claude can locate, understand, and execute your commands reliably while keeping the files easy for humans to maintain.