Claude-Code-Everything-You-Need-to-Know

The ultimate all-in-one guide to mastering Claude Code. From setup, prompt engineering, commands, hooks, workflows, automation, and integrations, to MCP servers, tools, and the BMAD method—packed with step-by-step tutorials, real-world examples, and expert strategies to make this the global go-to repo for Claude mastery.

📖 Recommended Tool
For the best reading experience with these documents, we recommend installing Obsidian. It provides excellent visualization and navigation for markdown files.

🧵 What We Covered:

Fundamentals:

• What are LLMs, and how do they differ from AI tools like Claude Code? Why should we use AI tools?
• What is Claude Code?
• Claude Code Setup: Get up and running seamlessly with a clean, optimized installation.

Core Features:

• Prompt Engineering Deep Dive
• Claude Commands Mastery: Extract the best possible results by leveraging Claude's command capabilities to their fullest.
• Claude Skills: Transform complex workflows into reusable slash commands
• AI Agents: Harness agents, sub-agents, and worktrees to structure intelligence with precision.
• Hooks That Work: Discover the power of Claude Hooks and learn how to implement them for maximum impact.
• What are MCP servers and how to use them?

2026 Updates:

• Claude Opus 4.6: The most capable model with 1M context window (API), adaptive thinking, and 128K output
• Fast Mode: 2.5x faster responses for rapid development (toggle with /fast)
• Agent Teams: Multi-agent collaboration for complex projects (experimental)
• MCP Registry: Live registry at https://registry.modelcontextprotocol.io/ with searchable server catalog
• New Commands: /fast, /auth, /debug, /teleport, /rename, /hooks
• Enhanced Pricing: Pro plan ($20/mo) now includes ALL models (Opus 4.6, Sonnet 4.5, Haiku 4.5)

Advanced Topics:

• Software Development Life Cycle (SDLC)
• Workflow Design: Build fully customized, high-performance workflows tailored to your project goals.
• Hands-On Demo: Full App Development Through the SDLC, Step by Step!
• Super Claude: Unlock advanced capabilities and push beyond standard limits.
• The BMAD Method: Apply a proven, systematic approach to deliver consistent, high-quality outcomes.

What are LLMs, and how do they differ from AI tools like Claude Code?

LLM (Large Language Model):

• This is the underlying AI technology/engine
• Think of it like a car engine - it's the core component that makes everything work
• Examples: GPT-4, Claude 4.5/4.6 (Opus 4.6, Sonnet 4.5, Haiku 4.5), Gemini (the actual AI models)

Products built with LLMs: These are the applications and tools that use LLMs to provide specific services:

Claude Code:

• A command-line tool that uses Claude's LLM
• Specifically designed for developers to code from their terminal
• It's like putting the Claude engine into a developer-focused interface

ChatGPT:

• A web/app interface that uses GPT models
• Designed for general conversations and tasks

Google Bard/Gemini:

• Google's chat interface that uses their Gemini LLM
• Note: "Gemini" refers both to Google's LLM and their chat product

Analogy:

• LLM = Car engine
• Claude Code = A pickup truck (built for specific work)
• ChatGPT = A family sedan (built for general use)
• Google Bard = A racing car The LLM is the "brain" that understands and generates language, while products like Claude Code are specialized interfaces that make that brain accessible for particular use cases.

---

What is Claude Code?

Claude Code is a command-line tool that lets developers work with Claude directly from their terminal or command prompt. Think of it as having an AI coding assistant that lives right in your development environment.

Here's what makes it useful in simple terms:

What it does:

• You can ask Claude to write code, fix bugs, or explain programming concepts without leaving your terminal
• It can read and work with files in your project directory
• You can delegate entire coding tasks to Claude and it will work through them step-by-step

Why developers like it:

• No need to copy-paste code back and forth between a web browser and your code editor
• Claude can see your actual project files and understand the context of what you're working on
• It fits naturally into existing development workflows
• You can automate repetitive coding tasks

Example use cases:

• "Claude, add error handling to this function"
• "Write unit tests for my new feature"
• "Help me refactor this messy code"
• "Explain what this legacy code does" It's essentially like having a very pair programming partner who can jump in and help with coding tasks whenever you need it.

---

Claude Opus 4.6: The Latest Powerhouse

Claude Opus 4.6 is the most capable model in the Claude family (as of February 2026), offering advanced reasoning and coding capabilities.

Key Specifications

| Feature | Specification | |---------|--------------| | Model ID | claude-opus-4-6 | | Context Window | 200K tokens (1M beta via API) | | Max Output | 128K tokens | | Availability | Pro, Max, and API plans | | Fast Mode | ✅ Yes (2.5x faster, 6x pricing) |

Advanced Capabilities

1. Extended Context Window

• Standard: 200K tokens (available to all Pro/Max subscribers)
• Beta: 1M tokens (API only, not in subscriptions at launch)
• Best for: Analyzing entire large codebases, extensive documentation

2. Adaptive Thinking

• Dynamic reasoning based on task complexity
• Automatically scales computational effort
• Better problem-solving for complex coding challenges

3. Agent Teams (Experimental)

• Multi-agent collaboration within single session
• Team leads coordinate multiple specialist agents
• Enable with: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

4. Top Performance

• Leading scores on Terminal-Bench 2.0
• Superior code generation and debugging
• Enhanced context understanding

When to Use Opus 4.6

✅ Best For:

• Complex architectural decisions
• Large-scale refactoring
• Debugging intricate issues
• Multi-file analysis
• Production-critical code

💡 Consider Sonnet 4.5 or Haiku 4.5 for:

• Simple code changes
• Documentation updates
• Quick questions
• Budget-conscious projects

Pricing & Access

Subscription Plans:

• Pro ($20/mo): Full access to Opus 4.6
• Max 5x ($100/mo): 5x usage capacity
• Max 20x ($200/mo): 20x usage capacity

API Pricing:

• Standard: $5 input / $25 output per MTok
• Fast Mode: $30 input / $150 output per MTok (6x)

---

Claude Code Setup

---

Prompt Engineering Deep Dive

📖 Claude Initialization Run the /init command to automatically generate a CLAUDE.md file. Your CLAUDE.md files become part of Claude's prompts, so they should be refined like any frequently used prompt. A common mistake is adding extensive content without iterating on its effectiveness. Take time to experiment and determine what produces the best instruction following from the model.

1. Explore → Plan → Code → Commit

Versatile workflow for complex problems.

• Explore: Read relevant files/images/URLs; use subagents for verification. Do not code yet.
• Plan: Ask Claude to make a plan. Use "think", "think hard", "think harder", or "ultrathink" to increase computation time. Optionally save plan for future reference.
• Code: Implement the solution; verify reasonableness as you go.
• Commit: Commit results, create pull requests, update READMEs/changelogs.
• Claude has two default modes: Plan Mode and Accept Edits Mode. You can toggle between them using the Shift + Tab keys.

💡 Pro Tip: Research & planning first significantly improves performance for complex tasks.

---

2. Test-Driven Workflow (Write Tests → Code → Commit)

Ideal for changes verifiable with unit/integration tests.

• Write Tests: Create tests based on expected inputs/outputs; mark as TDD.
• Run & Fail Tests: Confirm they fail; no implementation yet.
• Commit Tests: Commit once satisfied.
• Write Code: Implement code to pass tests; iterate with verification via subagents.
• Commit Code: Final commit after all tests pass.

🔹 Clear targets (tests, mocks) improve iteration efficiency.

---

3. Visual Iteration (Code → Screenshot → Iterate → Commit)

• Provide screenshots or visual mocks.
• Implement code, take screenshots, iterate until outputs match mock.
• Commit once satisfied.

🔹 Iteration significantly improves output quality (2-3 rounds usually enough).

---

Claude Commands

Built-in slash commands

| Command | Purpose | | ------------------------- | -------------------------------------------------------------------------------------------------------- | | /add-dir | Add additional working directories | | /agents | Manage custom AI subagents for specialized tasks | | /auth login | Authenticate with your Anthropic account (new Feb 2026) | | /auth status | Check authentication status (new Feb 2026) | | /auth logout | Sign out from your account (new Feb 2026) | | /bug | Report bugs (sends conversation to Anthropic) | | /clear | Clear conversation history | | /compact [instructions] | Compact conversation with optional focus instructions | | /config | View/modify configuration | | /cost | Show token usage statistics | | /debug | Troubleshoot current session and configuration (new Feb 2026) | | /doctor | Checks the health of your Claude Code installation | | /fast | Toggle Fast Mode for 2.5x faster Opus 4.6 responses (6x pricing) (new Feb 2026) | | /help | Get usage help | | /hooks | Interactive menu for hook configuration (new Feb 2026) | | /init | Initialize project with CLAUDE.md guide | | /login | Switch Anthropic accounts (use /auth login instead) | | /logout | Sign out from your Anthropic account (use /auth logout instead) | | /mcp | Manage MCP server connections and OAuth authentication | | /memory | Edit CLAUDE.md memory files | | /model | Select or change the AI model (Opus 4.6, Sonnet 4.5, Haiku 4.5) | | /permissions | View or update permissions | | /pr_comments | View pull request comments | | /rename | Auto-generate descriptive session names (new Feb 2026) | | /review | Request code review | | /status | View account and system statuses | | /teleport | Send current session to claude.ai/code for web access (new Feb 2026) | | /terminal-setup | Install Shift+Enter key binding for newlines (built-in since 2026, zero setup needed) | | /vim | Enter vim mode for alternating insert and command modes |

Custom slash commands

📖 Note: Custom slash commands allow you to define frequently-used prompts as Markdown files that Claude Code can execute. Commands are organized by scope (project-specific or personal) and support namespacing through directory structures.

mkdir -p .claude/commands
echo "Analyze this code for performance issues and suggest optimizations:" > .claude/commands/optimize.md

Example

• Create new file named pull-request.md in .claude/commands
• Add the following info to file

  # Create Pull Request Command
  
  Create a new branch, commit changes, and submit a pull request.
  
  ## Behavior
  - Creates a new branch based on current changes
  - Formats modified files using Biome
  - Analyzes changes and automatically splits into logical commits when appropriate
  - Each commit focuses on a single logical change or feature
  - Creates descriptive commit messages for each logical unit
  - Pushes branch to remote
  - Creates pull request with proper summary and test plan
  
  ## Guidelines for Automatic Commit Splitting
  - Split commits by feature, component, or concern
  - Keep related file changes together in the same commit
  - Separate refactoring from feature additions
  - Ensure each commit can be understood independently
  - Multiple unrelated changes should be split into separate commits
  

💡 Next Level: This is a basic custom slash command. For more sophisticated workflows, check out Claude Skills to learn how to build reusable, team-wide skills with advanced patterns.

---

Claude Skills

📖 Extensibility Layer: Claude Skills transform complex, multi-step workflows into reusable slash commands. Think of them as "macros for AI" — instead of repeating the same detailed instructions, encapsulate them once and invoke them with a simple /skill-name command.

📖 Terminology Note: "Skills" and "custom slash commands" are the same thing. This documentation uses "skills" as the primary term, but you may see both used interchangeably. They both refer to markdown files in .claude/commands/ that you invoke with /skill-name.

🚨 SECURITY WARNING: Skills execute with full access to your codebase and can run arbitrary commands. Only use skills from trusted sources. Review all third-party skills before adding them to your project. Skills from untrusted repositories can access files, execute commands, and potentially compromise your system.

Quickstart: Your First Skill (3 minutes)

Want to try skills immediately? Here's the fastest path:

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

# 2. Create a simple skill file
cat > .claude/commands/analyze.md << 'EOF'
# Code Analysis

Analyze the current code for:
- Potential bugs and edge cases
- Performance optimizations
- Code quality improvements
- Security vulnerabilities

Provide specific, actionable recommendations.
EOF

# 3. Start Claude Code (if not already running)
claude

# 4. Use your new skill
# Type: /analyze

That's it! You now have a working skill. Continue reading to learn how to create more sophisticated workflows.

---

What Are Claude Skills?

Claude Skills (also called "custom slash commands") are markdown files stored in .claude/commands/ that contain structured instructions for Claude Code to execute. When you type /skill-name, Claude loads the corresponding markdown file and applies its instructions to your current context.

Key Characteristics:

1. Single Responsibility — Each skill focuses on one workflow (e.g., PR creation, code review, TDD)
2. Reusable — Define once, invoke repeatedly across projects and sessions
3. Markdown-Based — Simple text files, easy to read, write, and version control
4. Customizable — Modify existing skills or create new ones to match your team's processes
5. Context-Aware — Skills combine their instructions with your current code, files, and conversation

📖 Quick Links: Built-in vs Custom Skills | Creating Skills | Troubleshooting | FAQ

Skills vs Regular Prompts:

📱 Mobile Users: View this comparison in landscape mode or on desktop for best readability.

| Aspect | Regular Prompts | Claude Skills | |--------|----------------|---------------| | Definition | Ad-hoc instructions typed each time | Reusable markdown files in .claude/commands/ | | Reusability | Manual copy-paste required | Instant invocation with /skill-name | | Complexity | Limited by chat input | Multi-step workflows with detailed checklists | | Sharing | Share via text/screenshots | Share via files in version control | | Evolution | Lost after session ends | Iteratively improved and committed to repo | | Discoverability | None | Auto-listed in Claude Code's skill registry |

💡 Accessing the Skill Registry: Skills are discovered automatically when you start Claude Code. To see available skills, start typing / in Claude Code and you'll see an autocomplete list of all available skills (both built-in and custom). You can also use /help to view all commands, which includes skills.

Built-in Skills vs Custom Skills

Built-in Skills (shipped with Claude Code):

| Skill | Purpose | Invocation | |-------|---------|------------| | keybindings-help | Customize keyboard shortcuts and modify ~/.claude/keybindings.json | /keybindings-help | | mermaid | Create entity relationship diagrams and flowcharts | /mermaid |

Custom Skills (in this repository's .claude/commands/):

Quick Reference:

| Skill | Category + Complexity | |-------|---------------------| | /pr | Workflow (High) | | /review | Quality (High) | | /test | Quality (Medium) | | /tdd | Workflow (High) | | /five | Persona (Low) | | /ux | Persona (Medium) | | /todo | Task (Low) |

Detailed Purpose:

| Skill | What It Does | |-------|--------------| | /pr | Automated pull request creation with branch management and commit splitting | | /review | Multi-perspective code review (PM, Dev, QA, Security, DevOps, UX) | | /test | Unit testing best practices checklist for LLM-driven test generation | | /tdd | Complete test-driven development workflow with Red-Green-Refactor cycle | | /five | Five Whys root cause analysis for debugging and problem-solving | | /ux | User experience designer persona for empathetic, user-centric design | | /todo | Task management in todos.md with due dates and completion tracking |

💡 Pro Tip: Start with simple skills (like /five or /todo) to understand the pattern, then progress to complex workflows (like /tdd or /review).

Available Skills Reference

🔹 Workflow & Process

/pr - Pull Request Creation

• Automatically creates feature branch from current changes
• Formats code using project linter (e.g., Biome)
• Intelligently splits changes into logical, atomic commits
• Generates descriptive commit messages for each unit of work
• Pushes to remote and creates PR with summary and test plan
• Perfect for: Teams requiring consistent PR quality and commit hygiene

/tdd - Test-Driven Development

• Enforces strict Red-Green-Refactor cycle
• Guides through: failing test → minimal implementation → refactoring
• Maintains feature notes in notes/features/ for long-term memory
• Ensures tests pass before commits, commits only when green
• Integrates with feature branch workflows
• Perfect for: Projects requiring high code quality and comprehensive test coverage

🔹 Quality & Review

/review - Multi-Perspective Code Review Six-role review framework:

1. Product Manager — Business value, user experience, strategic alignment
2. Developer — Code quality, maintainability, performance, best practices
3. QA Engineer — Test coverage, edge cases, regression risks
4. Security Engineer — Vulnerabilities, data handling, compliance (OWASP, GDPR)
5. DevOps — CI/CD integration, infrastructure, monitoring
6. UI/UX Designer — Visual consistency, usability, accessibility

• Enforces "fix now, not later" philosophy for all recommendations
• Posts comprehensive review directly to GitHub PR as a comment
• Perfect for: Critical PRs, production releases, architecture changes
• Note: When run on your own PR, this will post a review comment from your account

/test - Unit Testing Best Practices

• Comprehensive checklist for writing robust unit tests
• Focuses on testing internal logic, not API endpoints
• Covers context verification, test structure, test cases, isolation, assertions
• Includes strict guidance against over-mocking and framework bindings
• Encourages spawning sub-agents for complex test flows
• Perfect for: Ensuring consistent, maintainable test suites

🔹 Persona & Methodology

/five - Five Whys Root Cause Analysis

• Systematic investigation technique drilling from symptoms to root causes
• Iteratively asks "why" to uncover fundamental issues
• Validates findings by working backwards from root cause
• Proposes solutions addressing systemic problems, not just symptoms
• Handles both technical and process-related causes
• Perfect for: Debugging production incidents, understanding recurring bugs

/ux - User Experience Designer Persona Claude becomes an empathetic UX specialist:

• Conducts user research identifying needs, pain points, motivations
• Designs accessible, aesthetically pleasing interfaces
• Prioritizes user needs above all other considerations
• Creates thoughtful micro-interactions and anticipates edge cases
• Generates precise prompts for AI UI generation tools
• Perfect for: Design-first projects, prototyping, user-centric product development

🔹 Task Management

/todo - Project Task Manager

• Manages todos.md in project root with Active/Completed sections
• Supports due dates/times with smart sorting (due tasks prioritized)
• Commands: add, complete, remove, undo, list, past due, next
• Auto-numbers todos for easy reference
• Tracks completion timestamps
• Perfect for: Sprint planning, personal task tracking, session continuity

/mermaid - Diagram Generation

• Creates entity relationship diagrams from database schemas
• Generates flowcharts, sequence diagrams, and architecture visualizations
• Outputs valid Mermaid syntax for embedding in markdown
• Perfect for: Documentation, architecture discussions, onboarding

Using Skills in Your Workflow

Basic Invocation:

# In Claude Code CLI
/skill-name

# With arguments (for skills that accept them)
/todo add "Fix navigation bug"
/review https://github.com/user/repo/pull/123

Workflow Prerequisites:

Before using these workflow combinations, ensure you have:

• ✅ Git repository initialized (git init)
• ✅ Remote repository configured (git remote -v shows your repo)
• ✅ Commit permissions to your repository
• ✅ GitHub authentication configured (for /review and /pr skills)
• ✅ Skills installed in .claude/commands/ or ~/.claude/commands/
• ✅ Current working directory is your project root

Workflow Execution Notes:

• Skills execute sequentially - wait for each to complete before invoking the next
• Skills do NOT auto-chain - you must type each /skill-name command manually
• If a skill fails, address the error before proceeding to the next step
• Use /help to verify skill availability before running workflows

Example Workflow Combinations:

1. Complete Feature Development

# Start with TDD workflow
/tdd
# Claude guides through Red-Green-Refactor cycle

# Ensure tests pass
/test
# Validates test coverage and quality

# Create PR with automatic commit splitting
/pr
# Creates branch, commits, and opens PR

# Conduct comprehensive review (optional - creates PR comment)
/review

Common Issues:

• /tdd fails: Ensure tests are properly written; review test syntax
• /test reports failures: Fix failing tests before proceeding to /pr
• /pr merge conflicts: Resolve conflicts manually, then retry
• /review auth failure: Run gh auth login to configure GitHub CLI
• No Biome configured: /pr assumes Biome formatter; install or modify skill

2. Bug Investigation & Resolution

# Identify root cause
/five
# Five Whys analysis to find systemic issues

# Implement fix using TDD
/tdd
# Write failing test, implement fix, refactor

# Verify with unit tests
/test
# Ensure all tests pass

# Submit PR
/pr
# Create and push PR

Common Issues:

• /five identifies unfixable issue: Root cause may require architecture changes
• Bug in dependency: Report upstream; consider workaround or fork
• /tdd tests pass but bug persists: Review test coverage; bug may be in untested code

3. UX-Focused Development

# Start with user-centric design
/ux
# Claude adopts UX designer persona

# Implement with tests
/test
# Build with test coverage

# Review for accessibility and usability
/review
# Multi-perspective review including UX

Common Issues:

• /ux suggestions conflict with brand: Provide brand guidelines as context
• /review finds accessibility violations: Address WCAG issues before merge
• Performance issues with new UI: Use browser profiling tools; optimize assets

Workflow FAQs:

Q: How long do skill workflows typically take?

• Simple skills (5-20 lines): 10-30 seconds
• Medium skills (20-100 lines): 1-3 minutes
• Complex skills like /tdd: 5-15 minutes depending on implementation size

Q: Can I cancel a running skill midway?

• Press Ctrl+C to interrupt Claude Code execution
• Some changes may be partially applied; review with git status

Q: What if a skill modifies files I didn't expect?

• Review changes with git diff before committing
• Use git checkout -- <file> to revert unwanted changes
• Report unexpected behavior to skill author

Q: Can I run skills in parallel?

• No - skills execute sequentially in a single Claude Code session
• For parallel work, open multiple terminals with separate Claude Code sessions

💡 Workflow Tips:

• Chain skills sequentially - Skills execute one at a time; wait for completion before invoking the next
• Combine with hooks for automatic skill invocation on events (see Hooks section)
• Use /todo at session start to maintain context across interruptions
• Run /review on your own PRs before requesting human review (note: posts as a PR comment from your account)
• Skills don't auto-chain - Each /skill must be invoked manually; they don't automatically call other skills

Skills FAQ

Q: What's the difference between "skills" and "custom slash commands"?

A: They're the same thing. This documentation uses "skills" as the primary term, but both refer to markdown files in .claude/commands/ that you invoke with /skill-name. You may see both terms used interchangeably.

Q: Are skills safe to use from third-party repositories?

A: Treat skills like executable code - review them before running. Skills can:

• Read and modify files in your project
• Execute commands via Claude Code
• Access your GitHub/API credentials if configured

Always review .claude/commands/ files from cloned repositories before invoking skills.

Q: How do I know if a skill is working correctly?

A:

1. Check skill autocomplete: Type / and your skill name should appear
2. Test with simple input: Invoke the skill with basic arguments
3. Review Claude's response: Skill instructions should be reflected in output
4. Check for errors: Run claude --debug to see detailed execution logs

Q: Can I modify built-in skills?

A: No. Built-in skills (/keybindings-help, /mermaid) are shipped with Claude Code and cannot be modified. You can create your own custom skills with similar names (e.g., /my-mermaid) for custom behavior.

Q: How do I share skills with my team?

A:

1. Create skills in .claude/commands/ (project directory)
2. Commit skill files to version control: git add .claude/commands/
3. Document skills in your project README
4. Team members get skills automatically when they clone the repo

Q: Do skills work offline?

A: Yes. Skills are local markdown files read by Claude Code. No network connection is required to invoke skills, though the AI model execution requires internet access.

Q: What happens if I have two skills with the same name?

A: Project skills (.claude/commands/) take precedence over global skills (~/.claude/commands/). The project-level skill will execute.

Q: Can skills accept arguments?

A: Yes. Type arguments after the skill name:

/todo add "Fix navigation bug"
/review https://github.com/user/repo/pull/123

Claude automatically sees your arguments as context - no special syntax needed.

Creating Custom Skills

🚨 SECURITY NOTE: When creating global skills (~/.claude/commands/), remember they will execute in ALL your projects. Only add skills you trust completely. For team projects, use project-specific skills (.claude/commands/) and commit them to version control for team review.

💡 New to Skills? Review What Are Claude Skills and Available Skills Reference before creating your first skill.

Skill File Requirements

File Format:

• Extension: Must be .md (markdown files only)
• Encoding: UTF-8 (required; UTF-16 not supported)
• Line endings: Both LF (Unix) and CRLF (Windows) supported
• File size: Recommended maximum 50KB per skill (larger files may cause performance issues)
• Naming: Lowercase with hyphens (e.g., my-skill.md → /my-skill)

File System:

• Symlinks: Supported (.claude/commands/ can contain symlinks to skill files)
• Permissions: Files must be readable by your user account
• Location: Must be in .claude/commands/ (project) or ~/.claude/commands/ (global)

Execution Context:

• Git requirement: None - skills work in any directory (git or non-git)
• Network requirement: None - skills execute locally without network access
• Offline support: ✅ Full support - skills are read from local files

Step-by-step guide to building your first skill:

1. Create the skill file

# Project-specific skill (recommended for team projects)
# The .claude/commands/ directory will be created automatically if it doesn't exist
mkdir -p .claude/commands
touch .claude/commands/my-skill.md

# Global skill (available in all projects - use with caution)
mkdir -p ~/.claude/commands
touch ~/.claude/commands/my-skill.md

💡 Tip: Always use project-specific skills (.claude/commands/) for team workflows to ensure team members can review changes through version control.

2. Define the skill structure

Skills use markdown with structured sections:

# Skill Name

Brief description of what this skill does.

## Behavior
- Bullet list of what Claude should do
- Specific actions to take
- Expected outcomes

## Guidelines (optional)
- Best practices to follow
- Constraints or requirements
- Formatting rules

## Examples (optional)
### Example 1: Use case description
[Show example input/output or workflow]

3. Example: Simple Skill (Complete File)

Complete contents of .claude/commands/five.md:

# Five Whys Analysis

Apply the Five Whys root cause analysis technique to investigate issues.

## Steps
1. Start with the problem statement
2. Ask "Why did this happen?" and document the answer
3. For each answer, ask "Why?" again
4. Continue for at least 5 iterations or until root cause is found
5. Validate the root cause by working backwards
6. Propose solutions that address the root cause

## Notes
- Don't stop at symptoms; keep digging for systemic issues
- Multiple root causes may exist - explore different branches

💡 Tip: This is a complete, working skill file. Copy this exactly to .claude/commands/five.md to use it immediately.

4. Example: Complex Skill (Complete File)

Complete contents of .claude/commands/pr.md:

# Create Pull Request Command

Create a new branch, commit changes, and submit a pull request.

## Behavior
- Creates a new branch based on current changes
- Formats modified files using Biome
- Analyzes changes and automatically splits into logical commits when appropriate
- Each commit focuses on a single logical change or feature
- Creates descriptive commit messages for each logical unit
- Pushes branch to remote
- Creates pull request with proper summary and test plan

## Guidelines for Automatic Commit Splitting
- Split commits by feature, component, or concern
- Keep related file changes together in the same commit
- Separate refactoring from feature additions
- Ensure each commit can be understood independently
- Multiple unrelated changes should be split into separate commits

💡 Tip: This is a complete, working skill file. Copy this exactly to .claude/commands/pr.md to use it immediately.

5. Skill Scope: Project vs Global

| Location | Scope | Use Case | |----------|-------|----------| | .claude/commands/ | Project-specific | Team workflows, project conventions, domain-specific tasks | | ~/.claude/commands/ | Global (all projects) | Personal preferences, universal patterns, cross-project utilities |

6. Test your skill

# Start Claude Code in your project
claude

# Invoke your skill
/my-skill

# Observe Claude's behavior and iterate on the skill file

💡 Creation Tips:

• Start simple — A 10-line skill is better than none
• Be specific — Vague instructions yield vague results
• Use examples — Show Claude what good output looks like
• Iterate — Skills improve with use; refine based on results
• Version control — Commit skills to .claude/commands/ for team sharing

Troubleshooting Skills

💡 Still stuck? Check the Skills FAQ for common questions or review Skills Best Practices.

Common Issues:

1. /skill-name not recognized

• Cause: Skill file doesn't exist or wrong location
• Solution: Verify file exists in .claude/commands/skill-name.md

2. Skill not executing

• Cause: File permissions issue
• Solution: Run chmod +r .claude/commands/skill-name.md

3. Wrong skill executes

• Cause: Name collision between project and global skills
• Solution: Project skills (.claude/commands/) take precedence over global (~/.claude/commands/)

4. Skill content ignored

• Cause: Markdown formatting errors
• Solution: Validate markdown syntax, ensure proper heading levels

5. Unexpected behavior

• Cause: Skill instructions unclear
• Solution: Make instructions more explicit and specific

6. Changes not reflected

• Cause: Old session cache
• Solution: Restart Claude Code session to reload skill files

Debugging Tips:

1. Test in isolation - Create a minimal test skill to verify the system works
2. Check file paths - Use absolute paths: ls -la .claude/commands/ to verify files exist
3. Review logs - Run claude --debug to see detailed execution logs
4. Validate markdown - Use a markdown validator to check file syntax
5. Start fresh - Close and restart Claude Code session after creating/modifying skills

Error Messages:

• "Command not found" - Skill file doesn't exist at expected path
• "Permission denied" - Skill file not readable; check permissions
• No error but skill doesn't work - Instructions may be too vague; add specific steps

Version Requirements:

• Claude Code Version: Skills are available in Claude Code v1.0+ (released 2024)
• No special installation needed - Skills work out of the box with any Claude Code installation
• All plans supported - Available in Free, Pro, and Max plans
• All models supported - Works with Opus 4.6, Sonnet 4.5, and Haiku 4.5

Edge Cases and Special Scenarios:

| Scenario | Behavior | Notes | |----------|----------|-------| | File without .md extension | Not recognized as skill | Only .md files are loaded as skills | | Symlinked skill files | ✅ Supported | .claude/commands/ can contain symlinks | | Skill in non-git directory | ✅ Works normally | Skills don't require git | | Running skills offline | ✅ Fully supported | Skills are local files, no network needed | | CRLF line endings (Windows) | ✅ Supported | Both Unix (LF) and Windows (CRLF) work | | UTF-16 encoded file | ❌ May fail | Use UTF-8 encoding for compatibility | | Skill file > 100KB | ⚠️ Performance impact | Keep skills focused; split large workflows | | Circular skill references | ⚠️ User must break loop | Skills don't auto-execute; user types each command |

Skills Best Practices

✅ Do:

1. Give skills descriptive names — Use kebab-case: create-api-endpoint.md, not command.md
2. Focus on one workflow — Split complex processes into composable skills
3. Include examples — Show expected input/output patterns
4. Document arguments — Skills can accept arguments passed after the slash command

Passing Arguments to Skills:

# Single argument
/todo add "Fix navigation bug"

# Multiple words (use quotes)
/review https://github.com/user/repo/pull/123

# URL or file path
/analyze src/components/Button.tsx

Accessing Arguments in Skills: Arguments are automatically available to Claude as context. In your skill file, reference them naturally:

# Code Review Skill

Analyze the code at the provided file path or URL.

## Steps
1. Read the provided argument (file path or URL)
2. Perform code review...

Note: There is no special $ARGUMENTS variable syntax - Claude automatically sees the text you type after /skill-name as part of the request context.

1. Test with edge cases — Invoke skills with missing/invalid inputs
2. Share with your team — Commit to .claude/commands/ and document in README
3. Use structured sections — Behavior, Guidelines, Examples, Notes
4. Leverage existing skills — Reference other skills in workflows (e.g., "Run /test after implementation")

❌ Don't:

1. Overload skills — A skill doing 10 things is 10 skills in disguise
2. Use ambiguous language — "Make it better" → "Refactor for readability: extract functions >20 lines"
3. Duplicate built-in commands — Check existing commands first with /help
4. Forget to test — Always run skills in real scenarios before sharing
5. Ignore naming conventions — Consistent naming improves discoverability
6. Hardcode project paths — Use relative paths or variables
7. Skip documentation — Future you (and teammates) will need context
8. Run untrusted skills — Always review third-party skills before executing them
9. Grant excessive permissions — Skills should request only the minimum permissions needed

Advanced Patterns:

Skill Composition — Reference other skills within a skill:

## Workflow
1. Run `/five` to identify root cause
2. Create feature branch
3. Implement fix using `/tdd`
4. Submit with `/pr`

⚠️ Circular Reference Prevention: Skills can reference other skills in their workflows, but be cautious:

• Avoid circular calls: Don't create skill A that calls skill B that calls skill A
• No automatic chaining: Each /skill-name must be invoked manually; skills don't auto-execute other skills
• Claude interprets references: When a skill says "Run /test", Claude sees this as an instruction, not automatic execution
• Manual workflow: Users still need to type each skill command themselves

Conditional Logic — Guide Claude's decision-making:

## Behavior
- If tests exist: Run tests first
- If no tests: Create tests following `/test` guidelines
- If tests fail: Fix code, do not modify tests

Subagent Coordination — Delegate complex tasks:

## Implementation
1. Spawn 4 subagents (Task tool) for parallel work:
   - Agent 1: Generate test cases
   - Agent 2: Implement core logic
   - Agent 3: Create documentation
   - Agent 4: Review security implications
2. Integrate results into cohesive implementation

Performance Considerations:

| Complexity | Token Usage | Response Time | Best For | |------------|-------------|---------------|----------| | Simple (5-20 lines) | Lower token usage | Faster response | Single-step tasks, checklists | | Medium (20-100 lines) | Moderate token usage | Moderate response | Multi-step workflows, personas | | Complex (100+ lines) | Higher token usage | Slower response | Comprehensive reviews, TDD cycles |

Note: Actual performance varies based on skill content, model selection, server load, and network conditions. Token counts and response times are approximate guidelines only.

🎯 Optimization Tips:

• Use subagents for parallelizable work within complex skills
• Split mega-skills into smaller, composable units
• Cache common patterns as skills instead of re-prompting
• Use Fast Mode (see Fast Mode section) when running skill-heavy workflows for 2.5x faster responses

---

Fast Mode ↯

Fast Mode delivers 2.5x faster responses using Claude Opus 4.6, ideal for rapid iteration and time-sensitive development work.

How It Works

• Toggle on/off instantly with /fast command
• Only available for Opus 4.6 (not Sonnet or Haiku)
• Visual indicator: ↯ icon appears in session when active
• Same model quality, just optimized for speed

Pricing

Fast Mode uses 6x standard pricing:

| Mode | Input (per MTok) | Output (per MTok) | |------|------------------|-------------------| | Standard Opus 4.6 | $5 | $25 | | Fast Mode Opus 4.6 | $30 | $150 |

When to Use Fast Mode

✅ Best For:

• Rapid prototyping and iteration
• Live debugging sessions
• Time-sensitive deployments
• Quick code reviews
• Interactive pair programming
• Emergency hotfixes

❌ Skip For:

• Long background tasks
• Budget-conscious projects
• Non-urgent documentation work
• Batch processing
• Learning/exploration sessions

Usage Example

# Enable Fast Mode for rapid iteration
/fast

# Your prompts now process 2.5x faster
> Fix the authentication bug in login.ts

# Disable when you're done with urgent work
/fast

Best Practices

1. Toggle strategically - Turn on only when you need speed
2. Monitor costs - Use /cost to track Fast Mode usage
3. Time-box sessions - Use for focused sprints, not entire workdays
4. Combine with /model - Switch to Haiku for simple tasks to save costs

---

AI Agents

Git worktree

📖 Git Worktree: Worktrees allow multiple copies of the same Git repository on your local environment, each on a different branch.

• Single repo limitation: Normally, a Git repository can only be on one branch in one folder.
• Worktrees: Enable working on multiple branches simultaneously in separate folders.
• Isolation: Changes in one worktree do not interfere with others. Example
  • Main repo folder: branch main
  • Worktree folder: branch feature-x
  • You can edit both simultaneously without switching branches.

1. Create worktrees

   • git worktree add -b feature-a ../feature-a
   • Create additional worktrees as needed (repeat steps 1 in new terminal tabs)
   • Ex: Three separate terminal tabs, each linked to its own branch and worktree

2. Launch Claude in each worktree

   • cd ../feature-a && claude
   • Ex: three Claude code sessions to manage each branch

3. General Agents

   📖 Agent System: Claude Code's agent system — a powerful feature that lets you create specialized AI assistants for different coding tasks. Think of agents as specialized team members, each with their own expertise, tools, and focus area. Instead of having one general-purpose Claude handle everything, you can create focused agents for specific roles.

   • Example: Each agent can span multiple sub-agents to accelerate the process:

     - Analyze the implementation of the payment feature
     - Span 5 subagents to accelerate work
     - Ultrathink
     

   • Subagents executing multiple tasks in parallel, coordinated through a to-do list:
     

4. Specialized Agents

   • Traditional approach:

     • One Claude tries to be everything
     • Generic feedback covering all areas
     • Context gets mixed between different types of reviews

   • Agent approach:

     • Specialized expertise for each task
     • Focused, deep feedback in specific areas
     • Clean separation of concerns
     • Each agent "remembers" previous conversations in their domain

   • Let's do it, step by step

   View Agent Creation Workflow

   Security Reviewer Prompt

   Security Reviewer Description

5. General Agent orchestrate collaboration between Specialized Agents

   Get the **backend-engineer** to suggest changes for improving the UI of our app. Then, get the **backend-engineer** to implement those changes. Then, get the **code-reviewer** to review the changes made by the **backend-engineer**. Finally, get the **backend-engineer** to fix up any issues pointed out by the reviewer.
   

💡 Tip:

• Use consistent naming conventions for worktrees
• Maintain one terminal tab per worktree
• Use Tmux to create a session for each terminal, allowing you to detach and keep processes running in the background
• Use separate IDE windows for different worktrees
• Clean up when finished: git worktree remove ../feature-a

---

Agent Teams (Experimental - 2026)

Agent Teams is an experimental feature that enables multi-agent collaboration within a single Claude Code session. Instead of one agent handling everything, you can coordinate multiple specialist agents working together on complex tasks.

What Are Agent Teams?

Agent Teams introduce a hierarchical structure where:

• Team Lead: The main agent that coordinates and delegates work
• Teammates: Specialist agents that handle specific subtasks
• Shared Task List: All agents can view and update a common to-do list
• Parallel Execution: Multiple agents can work simultaneously

Think of it as having a development team where:

• The lead architect makes high-level decisions
• Specialists (frontend dev, backend dev, QA tester) work on their areas
• Everyone stays synchronized through shared task tracking

How to Enable Agent Teams

Agent Teams is currently experimental and requires an environment variable:

# Enable Agent Teams
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# Launch Claude Code
claude

# Agent Teams will now be available

Permanent Setup (Recommended):

Add to your shell configuration (~/.bashrc, ~/.zshrc, or equivalent):

# For bash/zsh
echo 'export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1' >> ~/.zshrc
source ~/.zshrc

# Verify it's set
echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS  # Should output: 1

Team Structure & Roles

Team Lead (You/Main Agent):

• Creates and assigns tasks
• Monitors overall progress
• Makes architectural decisions
• Coordinates between teammates
• Reviews completed work

Teammates (Specialist Agents):

• Focus on assigned tasks
• Report progress and blockers
• Can request help from other teammates
• Update shared task list
• Work in parallel when possible

Shared Task List:

• Central coordination point
• Visible to all team members
• Tracks dependencies between tasks
• Shows task status (pending, in progress, completed)
• Prevents duplicate work

Multi-Agent Collaboration Patterns

1. Parallel Development