Skip to main content
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
1

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
2

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
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.
3

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
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
4

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
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
5

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
  1. Commands - Entry-point prompts for workflows
  2. Subagents - Custom agents with specialized capabilities
  3. Skills - Reusable knowledge and procedures
  4. Orchestration workflow - Command → Agent → Skill patterns
  5. Hooks - Event-driven automation

​
Additional resources

​
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us