Quickstart

Get up and running with Claude Code best practices in under 10 minutes. This guide walks you through exploring the reference repository, running a complete orchestration workflow, and creating your first custom command.

Prerequisites

Before you begin, ensure you have Claude Code installed and authenticated:

# Install Claude Code
npm install -g @anthropic/claude

# Authenticate
claude login

If you don’t have Claude Code yet, visit code.claude.com for installation instructions.

What you’ll accomplish

By the end of this quickstart, you’ll:

Understand the .claude/ directory structure
Run a complete Command → Agent → Skill orchestration workflow
Create your first custom command
Know where to go next for advanced patterns

Clone the repository

Start by cloning the Claude Code best practices repository:

git clone https://github.com/shanraisshan/claude-code-best-practice.git
cd claude-code-best-practice

This repository serves as a reference implementation demonstrating:

Commands, agents, and skills working together
Cross-platform hooks for voice feedback
MCP server integrations
Real-world configuration patterns

Explore the .claude/ directory

The .claude/ directory contains all Claude Code customizations. Let’s explore its structure:

.claude/
├── commands/           # Entry-point prompts (invoke with /command-name)
├── agents/             # Custom subagents with specialized tools and permissions
├── skills/             # Reusable workflows and domain knowledge
├── hooks/              # Event-driven scripts (PreToolUse, PostToolUse, etc.)
└── settings.json       # Project-level configuration

View key configuration files

settings.json - Project-level settings for permissions, hooks, and output style:

{
  "permissions": {
    "allow": ["Edit(*)", "Write(*)", "Bash"],
    "deny": [],
    "ask": ["Bash(rm *)", "Bash(git *)"]
  },
  "outputStyle": "Explanatory",
  "plansDirectory": "./reports"
}

CLAUDE.md - Project memory that Claude reads on every session:

# Repository Overview

This is a best practices repository for Claude Code configuration,
demonstrating patterns for skills, subagents, hooks, and commands.

## Key Components

- Weather System: Command → Agent → Skill orchestration example
- Hooks: Cross-platform sound notifications
- Subagents: Feature-specific agents with preloaded skills

Keep your CLAUDE.md file under 150 lines for reliable adherence. Use multiple CLAUDE.md files in monorepos with ancestor and descendant loading.

Run the weather orchestration example

Now let’s run the weather orchestration workflow, which demonstrates the Command → Agent → Skill pattern:

# Start Claude Code in the repository
claude

# Run the weather orchestrator command
/weather-orchestrator

Here’s what happens behind the scenes:

---
description: Fetch weather data for Dubai and create an SVG weather card
model: haiku
---

# Weather Orchestrator Command

## Workflow

### Step 1: Ask User Preference
Use the AskUserQuestion tool to ask the user whether they want 
the temperature in Celsius or Fahrenheit.

### Step 2: Fetch Weather Data
Use the Task tool to invoke the weather agent:
- subagent_type: weather-agent
- prompt: Fetch the current temperature for Dubai

### Step 3: Create SVG Weather Card
Use the Skill tool to invoke the weather-svg-creator skill

---
name: weather-agent
description: Use this agent PROACTIVELY when you need to fetch weather data
tools: WebFetch, Read, Write, Edit
model: sonnet
color: green
skills:
  - weather-fetcher
---

# Weather Agent

Execute the weather workflow by following the instructions 
from your preloaded skill.

---
name: weather-fetcher
description: Instructions for fetching current weather temperature data
user-invocable: false
---

# Weather Fetcher Skill

Fetch the current temperature for Dubai, UAE using the Open-Meteo API.

For Celsius:
- URL: https://api.open-meteo.com/v1/forecast?latitude=25.2048&longitude=55.2708&current=temperature_2m&temperature_unit=celsius

Subagents cannot invoke other subagents via bash commands. Always use the Task tool for subagent orchestration.

The workflow produces:

orchestration-workflow/weather.svg - An SVG weather card
orchestration-workflow/output.md - Temperature summary

Create your first custom command

Let’s create a simple command to automate commit message generation:

# Create the commands directory if it doesn't exist
mkdir -p .claude/commands

# Create a new command file
cat > .claude/commands/smart-commit.md << 'EOF'
---
description: Generate a commit message from staged changes and create the commit
model: sonnet
allowed-tools: Bash(git *)
---

# Smart Commit Command

Generate a concise, meaningful commit message from the currently staged changes.

## Workflow

1. **Check staged changes**: Run `git diff --staged` to see what's being committed
2. **Analyze changes**: Determine the nature (feature, fix, refactor, docs, etc.)
3. **Draft message**: Create a commit message following this format:
   - First line: Brief summary (50 chars or less)
   - Blank line
   - Detailed explanation focusing on "why" rather than "what"
4. **Create commit**: Run `git commit -m "your message"`

## Requirements

- Only commit if there are staged changes
- Follow conventional commits style (feat:, fix:, docs:, etc.)
- Make the message specific and actionable
EOF

Now test your new command:

# Stage some changes
git add .

# Run your command
/smart-commit

Advanced: Add argument support

You can make commands accept arguments using $ARGUMENTS or $N:

---
description: Fix a GitHub issue by number
argument-hint: [issue-number]
---

# Fix Issue Command

Fix GitHub issue $0 following our coding standards.

## Context
- Issue details: !`gh issue view $0`

## Steps
1. Read the issue description from argument: $ARGUMENTS[0]
2. Implement the fix
3. Create a commit referencing issue #$0

Next steps

Congratulations! You’ve successfully:

Explored the .claude/ directory structure
Run a complete orchestration workflow
Created your first custom command

Core concepts

Deep dive into commands, agents, and skills

Commands

Learn about frontmatter fields and invocation patterns

Subagents

Build specialized subagents with tools and permissions

Skills

Create reusable workflows and domain knowledge

Additional resources

Claude Code Documentation - Official documentation
Best Practices Repository - Reference implementation
Changelog - Latest features and updates

Key takeaways

Commands are entry points that orchestrate workflows. Agents fetch data and execute specialized tasks using their preloaded skills. Skills are reusable knowledge blocks that can be invoked independently or preloaded into agents.

The weather example demonstrates two skill patterns:

Agent skill (weather-fetcher): Preloaded into the agent as domain knowledge
Skill (weather-svg-creator): Invoked independently via the Skill tool

This separation of concerns enables:

Cleaner code organization
Progressive disclosure of context
Reusable components across workflows

Common pitfalls to avoid

Don’t let CLAUDE.md exceed 150 lines - it impacts adherence
Always use the Task tool for subagent orchestration, never bash commands
Perform manual /compact at ~50% context usage
Start with plan mode (/plan) for complex tasks
Commit often - as soon as a task is completed

Update Claude Code daily and start your day by reading the changelog. The CLI is evolving rapidly with new features.

Get Started

Core Concepts

Best Practices

Workflows & Patterns

Implementation Examples

Prerequisites

What you’ll accomplish

Core concepts

Commands

Subagents

Skills

Recommended reading order

Additional resources

Key takeaways

Common pitfalls to avoid

​Prerequisites

​What you’ll accomplish

Core concepts

Commands

Subagents

Skills

​Recommended reading order

​Additional resources

​Key takeaways

​Common pitfalls to avoid

Prerequisites

What you’ll accomplish

Recommended reading order

Additional resources

Key takeaways

Common pitfalls to avoid