diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md new file mode 100644 index 0000000..fa55541 --- /dev/null +++ b/STYLE_GUIDE.md @@ -0,0 +1,630 @@ + + + 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](#file-and-folder-naming) +- [Document Structure](#document-structure) +- [Headings](#headings) +- [Text Formatting](#text-formatting) +- [Lists](#lists) +- [Tables](#tables) +- [Code Blocks](#code-blocks) +- [Links and Cross-References](#links-and-cross-references) +- [Diagrams](#diagrams) +- [Emoji Usage](#emoji-usage) +- [YAML Frontmatter](#yaml-frontmatter) +- [Images and Media](#images-and-media) +- [Tone and Voice](#tone-and-voice) +- [Commit Messages](#commit-messages) +- [Checklist for Authors](#checklist-for-authors) + +--- + +## 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 (`` 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: + +```markdown +--- + +## 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](#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: + +```markdown +> **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: + +```markdown +- 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: + +```markdown +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: + +```markdown +- **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 + +```markdown +| Column 1 | Column 2 | Column 3 | +|----------|----------|----------| +| Data | Data | Data | +``` + +### Common Table Patterns + +**Feature comparison (3-4 columns):** + +```markdown +| 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:** + +```markdown +| Do | Don't | +|----|-------| +| Use descriptive names | Use vague names | +| Keep files focused | Overload a single file | +``` + +**Quick reference:** + +```markdown +| 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 + +```bash +# 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: + +```bash +# Copy files to your project +cp 01-slash-commands/*.md .claude/commands/ +``` + +### Multi-step Workflows + +```bash +# 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: + +```markdown +[Slash Commands](01-slash-commands/) +[Skills Guide](03-skills/) +[Memory Architecture](02-memory/#memory-architecture) +``` + +From a lesson folder back to root or sibling: + +```markdown +[Back to main guide](../README.md) +[Related: Skills](../03-skills/) +``` + +### External Links (Absolute) + +Use full URLs with descriptive anchor text: + +```markdown +[Anthropic's official documentation](https://docs.anthropic.com/en/docs/claude-code) +``` + +- 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: + +```markdown +[Feature Catalog](#-feature-catalog) +[Best Practices](#best-practices) +``` + +### Related Guides Pattern + +End lessons with a related guides section: + +```markdown +## 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: + +```mermaid +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:** + +| 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 `
` 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) + +```yaml +--- +name: unique-identifier +description: What this feature does and when to use it +allowed-tools: Bash, Read, Grep +--- +``` + +### Optional Fields + +```yaml +--- +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 `` element for dark/light mode support: + +```html + + + Claude How To + +``` + +### 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](https://www.conventionalcommits.org/): + +``` +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: + +```markdown +--- +**Last Updated**: March 2026 +**Claude Code Version**: 2.1+ +**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.6, 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