Skip to content

STYLE_GUIDE.md

Latest commit

 

History

History
640 lines (465 loc) · 16.5 KB

STYLE_GUIDE.md

File metadata and controls

640 lines (465 loc) · 16.5 KB
Raw
Claude How To

Style Guide

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

Table of Contents

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

Type Convention Examples
Lesson README README.md 01-slash-commands/README.md
Feature file Kebab-case .md code-reviewer.md, generate-api-docs.md
Shell script Kebab-case .sh format-code.sh, validate-input.sh
Config file Standard names .mcp.json, settings.json
Memory file Scope-prefixed project-CLAUDE.md, personal-CLAUDE.md
Top-level docs UPPER_CASE .md CATALOG.md, QUICK_REFERENCE.md, CONTRIBUTING.md
Image assets Kebab-case pr-slash-command.png, claude-howto-logo.svg

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

Level Use Example
# H1 Page title (one per document) # Slash Commands
## H2 Major sections ## Best Practices
### H3 Subsections ### Adding a Skill
#### H4 Sub-subsections (rare) #### Configuration Options

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

Style When to Use Example
Bold (**text**) Key terms, labels in tables, important concepts **Installation**:
Italic (*text*) First use of a technical term, book/doc titles *frontmatter*
Code (`text`) File names, commands, config values, code references `CLAUDE.md`

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:

Language Tag Use For
Shell bash CLI commands, scripts
Python python Python code
JavaScript javascript JS code
TypeScript typescript TS code
JSON json Configuration files
YAML yaml Frontmatter, config
Markdown markdown Markdown examples
SQL sql Database queries
Plain text (no tag) Expected output, directory trees

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
Loading

Color palette:

Color Hex Use For
Light blue #e1f5fe Primary components, inputs
Light pink #fce4ec Processing, middleware
Light green #e8f5e9 Outputs, results
Light yellow #fff9c4 Configuration, optional
Light purple #f3e5f5 User-facing, UI

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:

Context Emojis Example
Root README section headers Category icons ## 📚 Learning Path
Skill level indicators Colored circles 🟢 Beginner, 🔵 Intermediate, 🔴 Advanced
Do's and Don'ts Check/cross marks ✅ Do this, ❌ Don't do this
Complexity ratings Stars ⭐⭐⭐

Standard Emoji Set

Emoji Meaning
📚 Learning, guides, documentation
⚡ Getting started, quick reference
🎯 Features, quick reference
🎓 Learning paths
📊 Statistics, comparisons
🚀 Installation, quick commands
🟢 Beginner level
🔵 Intermediate level
🔴 Advanced level
✅ Recommended practice
❌ Avoid / anti-pattern
⭐ Complexity rating unit

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

Principle Example
Show, don't tell Provide working examples, not abstract descriptions
Progressive complexity Start simple, add depth in later sections
Explain the "why" "Use memory for... because..." not just "Use memory for..."
Copy-paste ready Every code block should work when pasted directly
Real-world context Use practical scenarios, not contrived examples

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

Type Use For
feat New feature, example, or guide
fix Bug fix, correction, broken link
docs Documentation improvements
refactor Restructuring without changing behavior
style Formatting changes only
test Test additions or changes
chore Build, dependencies, CI

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 9, 2026 Claude Code Version: 2.1.138 Sources: