claude-code-guide

Purpose

Fetch the latest Claude Code documentation from code.claude.com and help update your configuration files based on current best practices.

Usage

/claude-code-guide <topic>

Topics

Topic	Description	Doc URLs	Config Files
memory	CLAUDE.md configuration	/memory, /best-practices	CLAUDE.md, CLAUDE.local.md
skills	Skills system	/skills	.claude/skills/*.md
hooks	Hooks configuration	/hooks, /hooks-guide	.claude/hooks/, settings.json
agents	Custom subagents	/sub-agents	.claude/agents/*.md
settings	Settings.json config	/settings	settings.json, settings.local.json
mcp	MCP servers	/mcp	settings.json mcpServers
plugins	Plugin system	/plugins, /plugin-marketplaces	plugins/
cli	CLI reference	/cli-reference	N/A (reference)
overview	Features overview	/features-overview	N/A (reference)
all	Full documentation	All above	All config files

---

Embedded Best Practices

Memory (CLAUDE.md)

File Locations & Precedence (highest to lowest):

1. Managed policy: /Library/Application Support/ClaudeCode/CLAUDE.md (macOS) - org-wide
2. Project memory: ./CLAUDE.md or ./.claude/CLAUDE.md - team-shared
3. Project rules: ./.claude/rules/*.md - modular topic-specific rules
4. User memory: ~/.claude/CLAUDE.md - personal across all projects
5. Project local: ./CLAUDE.local.md - personal project-specific (gitignored)

Best Practices:

• Be specific: "Use 2-space indentation" beats "Format code properly"
• Use structure: Format memories as bullet points under descriptive markdown headings
• Review periodically: Update as project evolves
• Use imports: @path/to/file syntax to include other files
• Path-specific rules: Use YAML frontmatter with paths field for conditional rules

Example CLAUDE.md:

# Project Standards

- Use TypeScript strict mode
- Follow ESLint airbnb config
- Write tests for all new functions

# Commands

- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

# Architecture

- React components in src/components/
- API routes in src/api/
- Shared utilities in src/utils/

Modular Rules (.claude/rules/):

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All endpoints must include input validation
- Use standard error response format
- Include OpenAPI documentation comments

---

Skills

Location: .claude/skills/<skill-name>/SKILL.md

Frontmatter Fields:

Field	Required	Description
name	No	Display name (defaults to directory name)
description	Recommended	When to use this skill
argument-hint	No	Hint for arguments, e.g., [filename]
disable-model-invocation	No	true = only user can invoke
user-invocable	No	false = only Claude can invoke
allowed-tools	No	Restrict tools available
model	No	Model override
context	No	fork = run in subagent
agent	No	Subagent type when context: fork

Example Skill:

---
name: code-review
description: Reviews code for quality and best practices. Use after code changes.
allowed-tools: Read, Grep, Glob
---

When reviewing code:
1. Check for code clarity and readability
2. Look for potential bugs
3. Verify error handling
4. Check test coverage
5. Note security concerns

Provide feedback organized by priority:
- Critical (must fix)
- Warnings (should fix)
- Suggestions (consider)

Supporting Files: Skills can include additional files (templates, scripts, examples) referenced from SKILL.md.

String Substitutions:

• $ARGUMENTS - User-provided arguments
• ${CLAUDE_SESSION_ID} - Current session ID

---

Hooks

Configuration Location: settings.json under hooks key

Available Hook Events:

Event	When	Matcher
SessionStart	Session begins	startup, resume, clear, compact
UserPromptSubmit	User submits prompt	-
PreToolUse	Before tool execution	Tool name
PermissionRequest	Permission dialog	Tool name
PostToolUse	After tool succeeds	Tool name
PostToolUseFailure	After tool fails	Tool name
SubagentStart	Subagent spawns	Agent type
SubagentStop	Subagent finishes	Agent type
Stop	Claude finishes	-
PreCompact	Before compaction	manual, auto
SessionEnd	Session terminates	-

Hook Configuration Structure:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Exit Codes:

• 0: Success (stdout shown in verbose mode)
• 2: Blocking error (stderr fed back to Claude)
• Other: Non-blocking error

Environment Variables:

• CLAUDE_PROJECT_DIR: Project root path
• CLAUDE_ENV_FILE: (SessionStart only) File for persisting env vars

---

Agents (Subagents)

Location: .claude/agents/<agent-name>.md or ~/.claude/agents/

Built-in Agents:

• Explore: Fast, read-only, uses Haiku
• Plan: Research for plan mode, inherits model
• general-purpose: Full tools, complex tasks

Frontmatter Fields:

Field	Required	Description
name	Yes	Unique identifier
description	Yes	When to delegate
tools	No	Allowed tools (inherits all if omitted)
disallowedTools	No	Tools to deny
model	No	sonnet, opus, haiku, or inherit
permissionMode	No	default, acceptEdits, dontAsk, bypassPermissions, plan
skills	No	Skills to preload
hooks	No	Lifecycle hooks

Example Agent:

---
name: code-reviewer
description: Expert code review. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer ensuring high standards.

When invoked:
1. Run git diff to see changes
2. Focus on modified files
3. Review for quality, security, performance

Provide feedback by priority:
- Critical (must fix)
- Warnings (should fix)
- Suggestions (consider)

---

Settings

File Locations (precedence highest to lowest):

1. Managed: System-level managed-settings.json
2. CLI arguments: Session overrides
3. Local project: .claude/settings.local.json
4. Project: .claude/settings.json
5. User: ~/.claude/settings.json

Key Settings:

Key	Description
permissions	Allow/deny/ask rules for tools
hooks	Hook configurations
env	Environment variables
model	Default model override
attribution	Git commit/PR attribution
mcpServers	MCP server configurations
enabledPlugins	Plugin enable/disable

Permissions Example:

{
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test:*)"],
    "deny": ["Bash(curl:*)", "Read(./.env)"],
    "additionalDirectories": ["../docs/"]
  }
}

---

MCP Servers

Adding Servers:

# HTTP transport (recommended for remote)
claude mcp add --transport http <name> <url>

# SSE transport (deprecated)
claude mcp add --transport sse <name> <url>

# Stdio transport (local)
claude mcp add --transport stdio <name> -- <command> [args...]

Scopes:

• local (default): Current project, private
• project: Shared via .mcp.json
• user: All your projects

Example .mcp.json:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "db": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DB_URL}"]
    }
  }
}

Commands:

• claude mcp list - List servers
• claude mcp get <name> - Get details
• claude mcp remove <name> - Remove server
• /mcp - Check status (in Claude Code)

---

Plugins

Plugin Structure:

my-plugin/
├── .claude-plugin/
│   └── plugin.json      # Required manifest
├── skills/              # Skills with SKILL.md
├── agents/              # Agent definitions
├── hooks/
│   └── hooks.json       # Hook configs
└── .mcp.json            # MCP servers

plugin.json Manifest:

{
  "name": "my-plugin",
  "description": "Plugin description",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

Testing Plugins:

claude --plugin-dir ./my-plugin

Installing from Marketplace:

/plugin install <plugin-name>@<marketplace>

---

Workflow

Step 1: Fetch Fresh Documentation

For the requested topic, fetch from https://code.claude.com/docs/en/<topic>:

For memory:

• WebFetch https://code.claude.com/docs/en/memory
• WebFetch https://code.claude.com/docs/en/best-practices

For skills:

• WebFetch https://code.claude.com/docs/en/skills

For hooks:

• WebFetch https://code.claude.com/docs/en/hooks
• WebFetch https://code.claude.com/docs/en/hooks-guide

For agents:

• WebFetch https://code.claude.com/docs/en/sub-agents

For settings:

• WebFetch https://code.claude.com/docs/en/settings

For mcp:

• WebFetch https://code.claude.com/docs/en/mcp

For plugins:

• WebFetch https://code.claude.com/docs/en/plugins
• WebFetch https://code.claude.com/docs/en/plugin-marketplaces

For cli:

• WebFetch https://code.claude.com/docs/en/cli-reference

For overview:

• WebFetch https://code.claude.com/docs/en/features-overview

Step 2: Read Current Configuration

For memory:

• Read ~/.claude/CLAUDE.md
• Read ./CLAUDE.md
• Read ./CLAUDE.local.md
• Glob .claude/rules/*.md

For skills:

• Glob .claude/skills/*/SKILL.md
• Read each skill file

For hooks:

• Read ~/.claude/settings.json (hooks section)
• Read .claude/settings.json
• Read .claude/settings.local.json

For agents:

• Glob ~/.claude/agents/*.md
• Glob .claude/agents/*.md

For settings:

• Read ~/.claude/settings.json
• Read .claude/settings.json
• Read .claude/settings.local.json

For mcp:

• Read settings.json mcpServers section
• Read .mcp.json

For plugins:

• Read .claude/plugins/ directory

Step 3: Compare & Recommend

• Identify differences from documentation best practices
• Note deprecated patterns
• Suggest improvements
• Highlight missing recommended configurations

Step 4: Apply Updates

Ask user which recommendations to apply, then:

• Edit existing config files
• Create new config files if needed
• Validate changes

Notes

• Documentation is fetched fresh each time for up-to-date guidance
• No changes made without user approval
• Respects existing patterns while suggesting improvements