Claude Code

Summary

• Load reference files on-demand per topic (10 reference docs available)
• Never modify settings without user approval
• For app code use

  feature

  /

  debug

  skills, not this one

Purpose

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

  ,

  debug

  , 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

• 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/skills/{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

references/getting-started.md

references/agent-skills.md

references/hooks-comprehensive.md

references/configuration.md

references/troubleshooting.md

references/ide-integration.md

references/cicd-integration.md

references/advanced-features.md

references/api-reference.md

references/best-practices.md

Related Skills

• mcp-builder

  -- creating new MCP servers

• mcp-management

  -- managing MCP connections

• skill-plan

  -- creating new agent skills

• 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