Conventions and formatting rules for contributing to Claude How To. Follow this guide to keep content consistent, professional, and easy to maintain.

File and Folder Naming

Lesson Folders

Lesson folders use a two-digit numbered prefix followed by a kebab-case descriptor:

01-slash-commands/
02-memory/
03-skills/
04-subagents/
05-mcp/

The number reflects the learning path order from beginner to advanced.

File Names

Rules

• Use lowercase for all file and folder names (except top-level docs like README.md, CATALOG.md)
• Use hyphens (-) as word separators, never underscores or spaces
• Keep names descriptive but concise

Document Structure

Root README

The root README.md follows this order:

1. Logo (<picture> element with dark/light variants)
2. H1 title
3. Introductory blockquote (one-line value proposition)
4. "Why This Guide?" section with comparison table
5. Horizontal rule (---)
6. Table of Contents
7. Feature Catalog
8. Quick Navigation
9. Learning Path
10. Feature sections
11. Getting Started
12. Best Practices / Troubleshooting
13. Contributing / License

Lesson README

Each lesson README.md follows this order:

1. H1 title (e.g., # Slash Commands)
2. Brief overview paragraph
3. Quick reference table (optional)
4. Architecture diagram (Mermaid)
5. Detailed sections (H2)
6. Practical examples (numbered, 4-6 examples)
7. Best practices (Do's and Don'ts tables)
8. Troubleshooting
9. Related guides / Official documentation
10. Document metadata footer

Feature/Example File

Individual feature files (e.g., optimize.md, pr.md):

1. YAML frontmatter (if applicable)
2. H1 title
3. Purpose / description
4. Usage instructions
5. Code examples
6. Customization tips

Section Separators

Use horizontal rules (---) to separate major document regions:

---

## New Major Section

Place them after the introductory blockquote and between logically distinct parts of the document.

Headings

Hierarchy

Rules

• One H1 per document — the page title only
• Never skip levels — don't jump from H2 to H4
• Keep headings concise — aim for 2-5 words
• Use sentence case — capitalize first word and proper nouns only (exception: feature names stay as-is)
• Add emoji prefixes only on root README section headers (see Emoji Usage)

Text Formatting

Emphasis

Blockquotes for Callouts

Use blockquotes with bold prefixes for important notes:

> **Note**: Custom slash commands have been merged into skills since v2.0.

> **Important**: Never commit API keys or credentials.

> **Tip**: Combine memory with skills for maximum effectiveness.

Supported callout types: Note, Important, Tip, Warning.

Paragraphs

• Keep paragraphs short (2-4 sentences)
• Add a blank line between paragraphs
• Lead with the key point, then provide context
• Explain the "why" not just the "what"

Lists

Unordered Lists

Use dashes (-) with 2-space indentation for nesting:

- First item
- Second item
  - Nested item
  - Another nested item
    - Deep nested (avoid going deeper than 3 levels)
- Third item

Ordered Lists

Use numbered lists for sequential steps, instructions, and ranked items:

1. First step
2. Second step
   - Sub-point detail
   - Another sub-point
3. Third step

Descriptive Lists

Use bold labels for key-value style lists:

- **Performance bottlenecks** - identify O(n^2) operations, inefficient loops
- **Memory leaks** - find unreleased resources, circular references
- **Algorithm improvements** - suggest better algorithms or data structures

Rules

• Maintain consistent indentation (2 spaces per level)
• Add a blank line before and after a list
• Keep list items parallel in structure (all start with verb, or all are nouns, etc.)
• Avoid nesting deeper than 3 levels

Tables

Standard Format

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data     | Data     | Data     |

Common Table Patterns

Feature comparison (3-4 columns):

| Feature | Invocation | Persistence | Best For |
|---------|-----------|------------|----------|
| **Slash Commands** | Manual (`/cmd`) | Session only | Quick shortcuts |
| **Memory** | Auto-loaded | Cross-session | Long-term learning |

Do's and Don'ts:

| Do | Don't |
|----|-------|
| Use descriptive names | Use vague names |
| Keep files focused | Overload a single file |

Quick reference:

| Aspect | Details |
|--------|---------|
| **Purpose** | Generate API documentation |
| **Scope** | Project-level |
| **Complexity** | Intermediate |

Rules

• Bold table headers when they are row labels (first column)
• Align pipes for readability in source (optional but preferred)
• Keep cell content concise; use links for details
• Use code formatting for commands and file paths inside cells

Code Blocks

Language Tags

Always specify a language tag for syntax highlighting:

Conventions

# Comment explaining what the command does
claude mcp add notion --transport http https://mcp.notion.com/mcp

• Add a comment line before non-obvious commands
• Make all examples copy-paste ready
• Show both simple and advanced versions when relevant
• Include expected output when it aids understanding (use untagged code block)

Installation Blocks

Use this pattern for installation instructions:

# Copy files to your project
cp 01-slash-commands/*.md .claude/commands/

Multi-step Workflows

# Step 1: Create the directory
mkdir -p .claude/commands

# Step 2: Copy the templates
cp 01-slash-commands/*.md .claude/commands/

# Step 3: Verify installation
ls .claude/commands/

Links and Cross-References

Internal Links (Relative)

Use relative paths for all internal links:

[Slash Commands](01-slash-commands/)
[Skills Guide](03-skills/)
[Memory Architecture](02-memory/#memory-architecture)

From a lesson folder back to root or sibling:

[Back to main guide](../README.md)
[Related: Skills](../03-skills/)

External Links (Absolute)

Use full URLs with descriptive anchor text:

[Anthropic's official documentation](https://code.claude.com/docs/en/overview)

• Never use "click here" or "this link" as anchor text
• Use descriptive text that makes sense out of context

Section Anchors

Link to sections within the same document using GitHub-style anchors:

[Feature Catalog](#-feature-catalog)
[Best Practices](#best-practices)

Related Guides Pattern

End lessons with a related guides section:

## Related Guides

- [Slash Commands](../01-slash-commands/) - Quick shortcuts
- [Memory](../02-memory/) - Persistent context
- [Skills](../03-skills/) - Reusable capabilities

Diagrams

Mermaid

Use Mermaid for all diagrams. Supported types:

• graph TB / graph LR — architecture, hierarchy, flow
• sequenceDiagram — interaction flows
• timeline — chronological sequences

Style Conventions

Apply consistent colors using style blocks:

graph TB
    A["Component A"] --> B["Component B"]
    B --> C["Component C"]

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#fce4ec,stroke:#333,color:#333
    style C fill:#e8f5e9,stroke:#333,color:#333

Color palette:

Rules

• Use ["Label text"] for node labels (enables special characters)
• Use <br/> for line breaks within labels
• Keep diagrams simple (max 10-12 nodes)
• Add a brief text description below the diagram for accessibility
• Use top-to-bottom (TB) for hierarchies, left-to-right (LR) for workflows

Emoji Usage

Where Emojis Are Used

Emojis are used sparingly and purposefully — only in specific contexts:

Standard Emoji Set

Rules

• Never use emojis in body text or paragraphs
• Only use emojis in headers on the root README (not in lesson READMEs)
• Do not add decorative emojis — every emoji should convey meaning
• Keep emoji usage consistent with the table above

YAML Frontmatter

Feature Files (Skills, Commands, Agents)

---
name: unique-identifier
description: What this feature does and when to use it
allowed-tools: Bash, Read, Grep
---

Optional Fields

---
name: my-feature
description: Brief description
argument-hint: "[file-path] [options]"
allowed-tools: Bash, Read, Grep, Write, Edit
model: opus                        # opus, sonnet, or haiku
disable-model-invocation: true     # User-only invocation
user-invocable: false              # Hidden from user menu
context: fork                      # Run in isolated subagent
agent: Explore                     # Agent type for context: fork
---

Rules

• Place frontmatter at the very top of the file
• Use kebab-case for the name field
• Keep description to one sentence
• Only include fields that are needed

Images and Media

Logo Pattern

All documents that start with a logo use the <picture> element for dark/light mode support:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">
  <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">
</picture>

Screenshots

• Store in the relevant lesson folder (e.g., 01-slash-commands/pr-slash-command.png)
• Use kebab-case file names
• Include descriptive alt text
• Prefer SVG for diagrams, PNG for screenshots

Rules

• Always provide alt text for images
• Keep image file sizes reasonable (< 500KB for PNGs)
• Use relative paths for image references
• Store images in the same directory as the document that references them, or in assets/ for shared images

Tone and Voice

Writing Style

• Professional but approachable — technical accuracy without jargon overload
• Active voice — "Create a file" not "A file should be created"
• Direct instructions — "Run this command" not "You might want to run this command"
• Beginner-friendly — assume the reader is new to Claude Code, not new to programming

Content Principles

Vocabulary

• Use "Claude Code" (not "Claude CLI" or "the tool")
• Use "skill" (not "custom command" — legacy term)
• Use "lesson" or "guide" for the numbered sections
• Use "example" for individual feature files

Commit Messages

Follow Conventional Commits:

type(scope): description

Types

Scopes

Use the lesson name or file area as scope:

feat(slash-commands): Add API documentation generator
docs(memory): Improve personal preferences example
fix(README): Correct table of contents link
docs(skills): Add comprehensive code review skill

Document Metadata Footer

Lesson READMEs end with a metadata block:

---
**Last Updated**: March 2026
**Claude Code Version**: 2.1.97
**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.7, Claude Haiku 4.5

• Use month + year format (e.g., "March 2026")
• Update the version when features change
• List all compatible models

Checklist for Authors

Before submitting content, verify:

• File/folder names use kebab-case
• Document starts with H1 title (one per file)
• Heading hierarchy is correct (no skipped levels)
• All code blocks have language tags
• Code examples are copy-paste ready
• Internal links use relative paths
• External links have descriptive anchor text
• Tables are properly formatted
• Emojis follow the standard set (if used at all)
• Mermaid diagrams use the standard color palette
• No sensitive information (API keys, credentials)
• YAML frontmatter is valid (if applicable)
• Images have alt text
• Paragraphs are short and focused
• Related guides section links to relevant lessons
• Commit message follows conventional commits format

Last Updated: May 2, 2026 Claude Code Version: 2.1.126 Sources:

• https://code.claude.com/docs/en/overview
• https://code.claude.com/docs/en/changelog
• https://www.anthropic.com/news/claude-opus-4-7 Compatible Models: Claude Sonnet 4.6, Claude Opus 4.7, Claude Haiku 4.5