Thank you for your interest in contributing to this project! This guide will help you understand how to contribute effectively.

About This Project

Claude How To is a visual, example-driven guide to Claude Code. We provide:

Types of Contributions

1. New Examples or Templates

Add examples for existing features (slash commands, skills, hooks, etc.):

2. Documentation Improvements

3. Feature Guides

Create guides for new Claude Code features:

4. Bug Reports

Report issues you encounter:

5. Feedback and Suggestions

Help improve the guide:

Getting Started

1. Fork and Clone

git clone YOUR_REPO
cd claude-howto

2. Create a Branch

Use a descriptive branch name:

git checkout -b add/feature-name
git checkout -b fix/issue-description
git checkout -b docs/improvement-area

3. Set Up Your Environment

Pre-commit hooks run the same checks as CI locally before every commit. All four checks must pass before a PR will be accepted.

Required dependencies:

# Python tooling (uv is the package manager for this project)
pip install uv
uv venv
source .venv/bin/activate
uv pip install -r scripts/requirements-dev.txt

# Markdown linter (Node.js)
npm install -g markdownlint-cli

# Mermaid diagram validator (Node.js)
npm install -g @mermaid-js/mermaid-cli

# Install pre-commit and activate hooks
uv pip install pre-commit
pre-commit install

Verify your setup:

pre-commit run --all-files

The hooks that run on every commit are:

Hook What it checks
markdown-lint Markdown formatting and structure
cross-references Relative links, anchors, code fences
mermaid-syntax All ```mermaid blocks parse correctly
link-check External URLs are reachable
build-epub EPUB generates without errors (on .md changes)

Directory Structure

├── 01-slash-commands/      # User-invoked shortcuts
├── 02-memory/              # Persistent context examples
├── 03-skills/              # Reusable capabilities
├── 04-subagents/           # Specialized AI assistants
├── 05-mcp/                 # Model Context Protocol examples
├── 06-hooks/               # Event-driven automation
├── 07-plugins/             # Bundled features
├── 08-checkpoints/         # Session snapshots
├── 09-advanced-features/   # Planning, thinking, backgrounds
├── 10-cli/                 # CLI reference
├── scripts/                # Build and utility scripts
└── README.md               # Main guide

How to Contribute Examples

Adding a Slash Command

  1. Create a .md file in 01-slash-commands/
  2. Include:
    • Clear description of what it does
    • Use cases
    • Installation instructions
    • Usage examples
    • Customization tips
  3. Update 01-slash-commands/README.md

Adding a Skill

  1. Create a directory in 03-skills/
  2. Include:
    • SKILL.md - Main documentation
    • scripts/ - Helper scripts if needed
    • templates/ - Prompt templates
    • Example usage in README
  3. Update 03-skills/README.md

Adding a Subagent

  1. Create a .md file in 04-subagents/
  2. Include:
    • Agent purpose and capabilities
    • System prompt structure
    • Example use cases
    • Integration examples
  3. Update 04-subagents/README.md

Adding MCP Configuration

  1. Create a .json file in 05-mcp/
  2. Include:
    • Configuration explanation
    • Required environment variables
    • Setup instructions
    • Usage examples
  3. Update 05-mcp/README.md

Adding a Hook

  1. Create a .sh file in 06-hooks/
  2. Include:
    • Shebang and description
    • Clear comments explaining logic
    • Error handling
    • Security considerations
  3. Update 06-hooks/README.md

Writing Guidelines

Markdown Style

Code Examples

Documentation

JSON/YAML

Diagrams

Commit Guidelines

Follow conventional commit format:

type(scope): description

[optional body]

Types:

Examples:

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

Before Submitting

Checklist

Local Testing

# Run all pre-commit checks (same checks as CI)
pre-commit run --all-files

# Review your changes
git diff

Pull Request Process

  1. Create PR with clear description:

    • What does this add/fix?
    • Why is it needed?
    • Related issues (if any)

  2. Include relevant details:

    • New feature? Include use cases
    • Documentation? Explain improvements
    • Examples? Show before/after

  3. Link to issues:

    • Use Closes #123 to auto-close related issues

  4. Be patient with reviews:

    • Maintainers may suggest improvements
    • Iterate based on feedback
    • Final decision rests with maintainers

Code Review Process

Reviewers will check:

Reporting Issues

Bug Reports

Include:

Feature Requests

Include:

Documentation Issues

Include:

Project Policies

Sensitive Information

Code Quality

Intellectual Property

Getting Help

Recognition

Contributors are recognized in:

Security

When contributing examples and documentation, please follow secure coding practices:

For security issues, see SECURITY.md for our vulnerability reporting process.

Code of Conduct

We are committed to providing a welcoming and inclusive community. Please read CODE_OF_CONDUCT.md for our full community standards.

In brief:

All contributors are expected to uphold this code and treat each other with kindness and respect.