Claude Code

Purpose

Help users install, configure, troubleshoot, and extend Claude Code CLI -- Anthropic's agentic coding tool with skills, hooks, MCP servers, and slash commands.

When to Use

• •Setting up Claude Code for the first time
• •Troubleshooting hooks that don't fire or produce errors
• •Diagnosing MCP server connection failures
• •Understanding or resolving context window limits
• •Creating or modifying slash commands and agent skills
• •Configuring settings (model, allowed tools, output style)

When NOT to Use

• •Writing application code -- use feature-implementation, debugging, or refactoring skills
• •Creating MCP servers from scratch -- use mcp-builder skill
• •Managing existing MCP connections -- use mcp-management skill

Workflow

Step 1: Identify Problem Category

Step 2A: Setup

1. •Check prerequisites: Node.js 18+, npm
2. •Verify authentication: claude auth status
3. •Verify project detection: check for CLAUDE.md in project root

Step 2B: Hook Issues

1. •Read the hook file causing issues
2. •Check hook event type matches expected trigger
3. •Verify hook script is executable with correct shebang
4. •Check .claude/settings.json for hook registration
5. •Test hook in isolation with mock input

Common fixes:

• •Hook not firing: wrong event name or tool matcher pattern
• •Hook errors: script not finding dependencies (check relative paths)
• •Hook blocks unexpectedly: PreToolUse returning { "decision": "block" } incorrectly

Step 2C: MCP Issues

1. •Check .mcp.json for server configuration
2. •Verify the MCP server process can start manually
3. •Check environment variables (API keys in .env.local)
4. •Test connectivity: claude mcp list

Step 2D: Context Issues

1. •Check current context usage
2. •Suggest /compact command if approaching limit
3. •Review if large files are being read unnecessarily
4. •Verify session-resume.cjs hook for session continuity

Step 2E: Extensibility

1. •For skills: read references/agent-skills.md for structure
2. •For commands: create .claude/commands/{name}.md
3. •Verify SKILL.md frontmatter has required fields (name, version, description)

Step 2F: Configuration

1. •Settings locations: .claude/settings.json (project), ~/.claude/settings.json (user)
2. •IMPORTANT: Never modify settings without user approval

Output Format

## Claude Code: [Issue/Task Summary]

### Problem
[What was wrong or what was requested]

### Solution
[Step-by-step fix or setup instructions]

### Files Changed
[List any config files modified]

### Verification
[How to confirm the fix works]

Reference Guide

Load references as needed for specific topics:

Related Skills

• •mcp-builder -- creating new MCP servers
• •mcp-management -- managing MCP connections
• •skill-creator -- creating new agent skills

IMPORTANT Task Planning Notes (MUST FOLLOW)

• •Always plan and break work into many small todo tasks
• •Always add a final review todo task to verify work quality and identify fixes/enhancements