name	claude-code-best-practices
description	Configure Claude Code projects with production-ready patterns from an Anthropic hackathon winner. Use when: (1) Setting up a new project with Claude Code, (2) Adding agents, commands, rules, or hooks to an existing project, (3) Optimizing context window management, (4) Implementing multi-agent workflows, (5) Creating CLAUDE.md for a new project. Triggers: "set up claude code", "configure agents", "add slash commands", "context window", "CLAUDE.md setup", "hooks configuration", "multi-agent workflow", "claude code best practices", "vibe coding setup", "agent configuration"

name

claude-code-best-practices

description

Configure Claude Code projects with production-ready patterns from an Anthropic hackathon winner. Use when: (1) Setting up a new project with Claude Code, (2) Adding agents, commands, rules, or hooks to an existing project, (3) Optimizing context window management, (4) Implementing multi-agent workflows, (5) Creating CLAUDE.md for a new project. Triggers: "set up claude code", "configure agents", "add slash commands", "context window", "CLAUDE.md setup", "hooks configuration", "multi-agent workflow", "claude code best practices", "vibe coding setup", "agent configuration"

Claude Code Best Practices

Production-ready patterns for Claude Code configuration.

Version: 1.0.0 | Changelog | GitHub

🚀 Interactive Setup Wizard

When this skill is activated, guide the user through setup with these questions:

Step 1: Identify User Goal

Ask the user (use AskUserQuestion tool):

What would you like to do?

1. 🆕 **Quick Start** - I'm new to Claude Code CLI, set up everything for me
2. 🔧 **Agent SDK Patterns** - I'm building production agents, show me advanced architecture
3. ➕ **Add Specific Config** - I want to add a specific agent/rule/command/hook
4. 📖 **Just Explore** - Show me what's available, I'll decide later

Step 2: Based on User Choice

If "Quick Start" (Option 1):

Ask about their environment:

Let's set up your Claude Code environment!

What's your primary tech stack?
- React/Next.js (Frontend)
- Node.js/Express (Backend)
- Python/FastAPI (Backend)
- Full-stack TypeScript
- Other (please specify)

Then ask about installation scope:

How would you like to install the starter kit?

1. **Full Install** - All 9 agents, 8 rules, 10 commands, hooks (Recommended for new users)
2. **Minimal Install** - Core only: planner, code-reviewer, /plan, /tdd, security rules
3. **Custom Install** - Let me choose which configs to install

Then execute the appropriate installation:

Full Install:

cp -r ~/.claude/skills/claude-code-best-practices/assets/starter-kit/* ~/.claude/
cp ~/.claude/skills/claude-code-best-practices/assets/examples/CLAUDE.md ./CLAUDE.md

Minimal Install:

# Core agents
cp ~/.claude/skills/claude-code-best-practices/assets/starter-kit/agents/planner.md ~/.claude/agents/
cp ~/.claude/skills/claude-code-best-practices/assets/starter-kit/agents/code-reviewer.md ~/.claude/agents/

# Core commands
cp ~/.claude/skills/claude-code-best-practices/assets/starter-kit/commands/plan.md ~/.claude/commands/
cp ~/.claude/skills/claude-code-best-practices/assets/starter-kit/commands/tdd.md ~/.claude/commands/

# Core rules
cp ~/.claude/skills/claude-code-best-practices/assets/starter-kit/rules/security.md ~/.claude/rules/
cp ~/.claude/skills/claude-code-best-practices/assets/starter-kit/rules/coding-style.md ~/.claude/rules/

# CLAUDE.md template
cp ~/.claude/skills/claude-code-best-practices/assets/examples/CLAUDE.md ./CLAUDE.md

Custom Install: Show the available configs and let user select.

Finally, ask about optional features:

Enable optional features?

☐ Memory Persistence Hooks - Remember context across sessions
☐ Strategic Compact Hooks - Smart context window management
☐ MCP Server Configs - Pre-configured MCP servers (GitHub, Supabase, etc.)

If "Agent SDK Patterns" (Option 2):

Ask which patterns they need:

Which Agent SDK patterns do you need? (Select all that apply)

☐ Source/MCP Integration - Build MCP server configs from sources
☐ Credential Manager - Multi-backend secret storage with priority resolution
☐ Permission Mode System - Safe/ask/allow-all permission levels
☐ Headless Execution - Non-interactive automation for CI/scripts
☐ Session-Scoped Tools - Tools with UI callbacks and execution pause

Then load the relevant section from references/advanced-architecture.md and explain the pattern with code examples.

If "Add Specific Config" (Option 3):

Ask what they want to add:

What type of config do you want to add?

1. 🤖 **Agent** - Specialized subagent for delegated tasks
2. 📏 **Rule** - Always-follow guidelines
3. ⚡ **Command** - Slash command for quick execution
4. 🪝 **Hook** - Automated trigger-based actions
5. 🎯 **Skill** - Domain knowledge module
6. 🎭 **Context** - Mode switching profile

Then provide the appropriate template and guide them through customization.

If "Just Explore" (Option 4):

Show the full catalog and let them browse:

Load references/all-configs.md for the complete list
Explain the config type decision tree
Offer to dive deeper into any specific area

Step 3: Post-Setup Verification

After any installation, verify and summarize:

✅ Setup Complete!

Installed:
- X agents in ~/.claude/agents/
- X rules in ~/.claude/rules/
- X commands in ~/.claude/commands/
- Hooks configured in ~/.claude/settings.json

Next steps:
1. Edit ./CLAUDE.md to customize for your project
2. Try `/plan` to create an implementation plan
3. Try `/tdd` to start test-driven development

Need help? Ask me about any specific config or pattern!

Manual Quick Start (New Project)

# 1. Copy starter kit to your Claude config
cp -r ~/.claude/skills/claude-code-best-practices/assets/starter-kit/* ~/.claude/

# 2. Copy project CLAUDE.md template
cp ~/.claude/skills/claude-code-best-practices/assets/examples/CLAUDE.md ./CLAUDE.md

# 3. Customize for your stack (edit CLAUDE.md, remove unused configs)

Config Type Decision Tree

Need	Config Type	Location	When to Use
Always-follow rules	`rules/*.md`	`~/.claude/rules/`	Security, style guides, invariants
Delegated specialist	`agents/*.md`	`~/.claude/agents/`	Complex tasks needing focused context
Quick user command	`commands/*.md`	`~/.claude/commands/`	Repeatable workflows (e.g., `/plan`, `/tdd`)
Automated triggers	`hooks.json`	`~/.claude/settings.json`	Pre/post tool actions, guardrails
Domain knowledge	`skills/*.md`	`~/.claude/skills/`	Frameworks, APIs, project-specific knowledge
Project context	`CLAUDE.md`	Project root	Build commands, architecture, conventions

Critical: Context Window Management

The 200k Problem: Your 200k context window can shrink to 70k with too many MCPs/tools enabled.

Rules:

Keep under 10 MCPs enabled per project
Under 80 tools active total
Use disabledMcpServers in project .claude.json to disable unused MCPs
Compact strategically at logical breakpoints

Signs of Context Bloat:

Claude forgetting earlier conversation
Repeated questions about already-discussed topics
Slower responses

See references/context-management.md for detailed strategies.

Creating Each Config Type

Agents

Specialized subagents for delegated tasks with limited scope.

---
name: agent-name
description: What this agent does. When to use it.
tools: Read, Grep, Glob, Bash  # Limit tools!
model: opus  # or sonnet
---

You are a [role] specialist...

## Your Role
- Specific responsibility 1
- Specific responsibility 2

## Process
1. Step 1
2. Step 2

Template: assets/templates/agent-template.md

Rules

Always-follow guidelines loaded into every session.

# Rule Name

## Mandatory Checks
- [ ] Check 1
- [ ] Check 2

## Examples
[Good and bad examples]

Template: assets/templates/rule-template.md

Commands

Slash commands for quick execution (/command-name).

---
description: What this command does in one line.
---

# Command Name

## What This Command Does
[Explanation]

## When to Use
[Triggers]

## Process
[Steps]

Template: assets/templates/command-template.md

Hooks

Trigger-based automations in ~/.claude/settings.json.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "tool == \"Bash\" && tool_input.command matches \"pattern\"",
        "hooks": [{ "type": "command", "command": "#!/bin/bash\n..." }],
        "description": "What this hook does"
      }
    ]
  }
}

Hook Types: PreToolUse, PostToolUse, PreCompact, SessionStart, Stop

Template: assets/templates/hooks-template.json

Patterns Worth Adopting

1. Agent-First Delegation

Complex tasks go to specialized agents, not the main session.

User: Implement user authentication
Claude: I'll use the planner agent to create an implementation plan first.
[Delegates to planner agent]

Key agents: planner (plan before code), code-reviewer (quality), architect (design), tdd-guide (tests)

2. Parallel Task Execution

Independent operations run simultaneously.

# GOOD: Parallel
Launch 3 agents in parallel:
1. Security analysis of auth.ts
2. Performance review of cache
3. Type checking of utils

# BAD: Sequential when unnecessary
First agent 1, then 2, then 3

3. Plan-Before-Execute

Use /plan command before implementing complex features.

/plan I need to add real-time notifications when markets resolve

The planner agent creates a phased implementation plan and WAITS for confirmation.

4. TDD Workflow

Tests before implementation via /tdd command.

Define interfaces first
Write failing tests (RED)
Implement minimal code (GREEN)
Refactor (IMPROVE)
Verify coverage

5. Hooks for Guardrails

Automate quality checks:

Block dev servers outside tmux
Warn about console.log statements
Auto-format after edits
TypeScript check after .ts edits

Starter Kit Contents

The starter kit (assets/starter-kit/) includes:

Type	Files	Purpose
Agents (9)	`planner.md`, `architect.md`, `tdd-guide.md`, `code-reviewer.md`, `security-reviewer.md`, `build-error-resolver.md`, `e2e-runner.md`, `refactor-cleaner.md`, `doc-updater.md`	Full delegation suite
Rules (8)	`security.md`, `coding-style.md`, `agents.md`, `git-workflow.md`, `hooks.md`, `patterns.md`, `performance.md`, `testing.md`	Complete guardrails
Commands (10)	`plan.md`, `tdd.md`, `code-review.md`, `build-fix.md`, `e2e.md`, `learn.md`, `refactor-clean.md`, `test-coverage.md`, `update-codemaps.md`, `update-docs.md`	All workflows
Hooks	`hooks.json`, `memory-persistence/`, `strategic-compact/`	Automated checks + memory
Contexts (3)	`dev.md`, `research.md`, `review.md`	Mode switching
Skills (8)	`backend-patterns.md`, `frontend-patterns.md`, `coding-standards.md`, `clickhouse-io.md`, `project-guidelines-example.md`, `lsp-integration.md`, `tdd-workflow/`, `security-review/`	Domain knowledge

Additional Assets

assets/mcp-servers.json - MCP server configurations (GitHub, Supabase, Vercel, Railway, etc.)
assets/examples/statusline.json - Custom status line configuration

Reference Files

Load these when you need deeper context:

references/config-types.md - Deep dive on each config type with full examples
references/context-management.md - MCP limits, tool management, compaction strategies
references/all-configs.md - Full catalog of all available configs with descriptions
references/advanced-architecture.md - Production patterns from Craft Agents (Source/MCP integration, Credentials, Permissions, Headless, Session-scoped tools)
references/plugins.md - Plugin ecosystem, marketplaces, and installation guide

Related Skills

Built-in Skills (Recommended)

feature-dev - Guided feature development with codebase understanding
code-simplifier - Simplify and refine code for clarity and maintainability

Third-Party Skills (Marketplace)

Available through Claude Code Marketplace - use /marketplace to install:

Vercel Skills:

frontend-design - Production-grade frontend interfaces with high design quality
react-best-practices - React and Next.js performance optimization guidelines
agent-browser - Automate browser interactions for web testing and data extraction

Anthropic Skills:

ralph-loop - Agentic coding loops for iterative development
hookify - Hook management and automation utilities

Cloud Deployment

cf-deploy - Deploy to Cloudflare Workers/Containers/Sandbox
agent-ui - Build real-time AI agent interfaces with AG-UI protocol

Source

These patterns are from everything-claude-code by @affaanmustafa, an Anthropic hackathon winner. Check the repo for updates and additional configs.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Claude Code Best Practices

🚀 Interactive Setup Wizard

Step 1: Identify User Goal

Step 2: Based on User Choice

If "Quick Start" (Option 1):

If "Agent SDK Patterns" (Option 2):

If "Add Specific Config" (Option 3):

If "Just Explore" (Option 4):

Step 3: Post-Setup Verification

Manual Quick Start (New Project)

Config Type Decision Tree

Critical: Context Window Management

Creating Each Config Type

Agents

Rules

Commands

Hooks

Patterns Worth Adopting

1. Agent-First Delegation

2. Parallel Task Execution

3. Plan-Before-Execute

4. TDD Workflow

5. Hooks for Guardrails

Starter Kit Contents

Additional Assets

Reference Files

Related Skills

Built-in Skills (Recommended)

Third-Party Skills (Marketplace)

Cloud Deployment

Source

FilesExpand file tree

SKILL.md

Latest commit

History

SKILL.md

File metadata and controls

Claude Code Best Practices

🚀 Interactive Setup Wizard

Step 1: Identify User Goal

Step 2: Based on User Choice

If "Quick Start" (Option 1):

If "Agent SDK Patterns" (Option 2):

If "Add Specific Config" (Option 3):

If "Just Explore" (Option 4):

Step 3: Post-Setup Verification

Manual Quick Start (New Project)

Config Type Decision Tree

Critical: Context Window Management

Creating Each Config Type

Agents

Rules

Commands

Hooks

Patterns Worth Adopting

1. Agent-First Delegation

2. Parallel Task Execution

3. Plan-Before-Execute

4. TDD Workflow

5. Hooks for Guardrails

Starter Kit Contents

Additional Assets

Reference Files

Related Skills

Built-in Skills (Recommended)

Third-Party Skills (Marketplace)

Cloud Deployment

Source