Claude Expert Skill

Expert guidance for Claude prompting techniques, Claude Code extensibility, and agent architecture.

Quick Reference

Argument Routing

If $ARGUMENTS is "self-update": Read and execute [cookbook/self-update.md](cookbook/self-update.md)

Otherwise: Continue with normal skill guidance below.

Core Principles

Prompting

• Use XML tags for structure (<context>, <instructions>, <constraints>)
• Be explicit rather than implicit
• Specify format to get formatted output
• Provide examples for complex tasks

Skills

• Skills = markdown files that extend Claude's capabilities
• Description is critical for auto-discovery
• Keep SKILL.md < 500 lines, split into reference files
• Use semantic XML tags in content
• MANDATORY: Every skill with external resources must include a self-update cookbook (see SKILLS.md Self-Update Pattern)

Hooks

• 30+ hook events covering the full lifecycle (Setup, SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PermissionRequest, PermissionDenied, PostToolBatch, TaskCreated/TaskCompleted, TeammateIdle, ConfigChange, CwdChanged, DirectoryAdded, FileChanged, Elicitation, etc.)
• Setup hook (claude --init) for repo initialization and dependency installation
• Can block, allow, or ask for confirmation
• Exit codes: 0=allow, 2=block, JSON output for decisions
• CLAUDEENVFILE for persisting env vars (Setup/SessionStart)

MCP

• Servers defined in ~/.claude.json, .mcp.json, or managed-mcp.json
• Provide external tools and resources
• Use stdio, SSE, or HTTP transport

Memory

• Auto memory: Claude automatically saves learnings to ~/.claude/projects/<project>/memory/
• MEMORY.md: First 200 lines loaded at startup; topic files loaded on-demand
• CLAUDE.md hierarchy: managed policy > project > user > local (more specific wins)
• Rules: .claude/rules/*.md with optional path-scoped frontmatter
• Agent memory: memory: user|project|local in agent frontmatter
• Toggle with /memory command or autoMemoryEnabled setting

Sub-agents & Agent Teams

• Sub-agents: Agent tool, isolated context, report back to parent; run in the background by default and fork the parent conversation by default in interactive sessions
• Nesting depth 3 (CLAUDECODEMAXSUBAGENTSPAWNDEPTH), 20 concurrent by default (CLAUDECODEMAXCONCURRENT_SUBAGENTS)
• Agent teams / cross-session messaging: implicit team per session; SendMessage/ListAgents also reach other local, Remote Control, and cloud sessions (@ to mention one)
• Default to single agents; use multi-agent only for context protection, parallelization, or specialization
• Custom agents in .claude/agents/ or ~/.claude/agents/

Workflows

• Variables at top for constants
• Instructions for rules/constraints
• Step-by-step workflow section
• Report template at end

Commands

• Quick-access prompts in .claude/commands/
• Can restrict tools and specify model
• Support argument passing

When to Read Reference Files

Read PROMPTING.md when:

• User asks to write a prompt or system message
• Optimizing an existing prompt
• Structuring complex instructions

Read SKILLS.md when:

• Creating a new skill
• Editing skill YAML frontmatter
• Debugging skill discovery
• Understanding cookbook/prompts patterns

Read WORKFLOWS.md when:

• Building multi-step workflow prompts
• Defining variables and instructions
• Creating orchestrated workflows
• Handling parallel execution

Read COMMANDS.md when:

• Creating /command shortcuts
• Setting up prime or install commands
• Understanding command vs skill differences

Read CLI.md when:

• Looking up a claude CLI flag or its exact syntax
• Choosing between print, bare, safe-mode, worktree, cloud, or background mode
• Scripting Claude Code (stream-json I/O, structured output, budget caps, fallback models)
• Understanding flag interactions (e.g. system-prompt vs system-prompt-file, --bare auth, --tools vs --allowedTools)
• Looking up a claude subcommand (mcp, agents, plugin, auth, project purge, ultrareview, …)

Read HOOKS.md when:

• Setting up security validation
• Adding notifications or logging
• Configuring PreToolUse patterns
• Setting up claude --init (Setup hook)
• Configuring SessionStart context injection
• Understanding hook-specific flow control and blocking

Read MCP.md when:

• Adding external tool servers
• Configuring MCP resources
• Troubleshooting MCP connections

Read MEMORY.md when:

• Setting up auto memory or CLAUDE.md files
• Configuring memory hierarchy (managed, project, user, local)
• Creating path-specific rules in .claude/rules/
• Enabling agent memory for custom agents
• Understanding CLAUDE.md import syntax
• Disabling or configuring auto memory settings

Read SUBAGENTS.md when:

• Creating custom agents
• Configuring agent tools/permissions
• Understanding Agent tool options
• Setting up parallel agent execution
• Managing multi-agent safety
• Using agent teams (multi-session orchestration)
• Deciding between subagents vs agent teams
• Understanding multi-agent orchestration principles
• Building team-based validation (builder/validator pattern)
• Understanding the meta-agent pattern

Read STATUS-LINES.md when:

• Creating custom terminal status displays
• Showing context window usage, cost, tokens
• Integrating session data into status lines
• Adding agent naming or custom metadata

Read DESKTOP.md when:

• User asks about Claude Desktop app features
• Discussing scheduled tasks, cowork mode, or Desktop-specific capabilities
• Comparing Claude Desktop vs Claude Code features
• Troubleshooting the Desktop app

Read OUTPUT-STYLES.md when:

• Creating custom response formatting
• Setting up GenUI (HTML generation) style
• Understanding output style configuration
• Building domain-specific output formats