Claude Code Mastery

Expert skill for Claude Code CLI -- CLAUDE.md optimization, skill authoring, subagent creation, hooks automation, and context engineering.

Keywords

claude-code, claude-cli, CLAUDE.md, skill-authoring, subagents, hooks, context-window, token-budget, MCP-servers, worktrees, permission-modes, prompt-engineering, context-engineering, slash-commands

Quick Start

Scaffold a new skill package

python scripts/skill_scaffolder.py my-new-skill --domain engineering --description "Brief description"

Analyze and optimize an existing CLAUDE.md

python scripts/claudemd_optimizer.py path/to/CLAUDE.md

Estimate context window usage across a project

python scripts/context_analyzer.py /path/to/project

All tools support JSON output

python scripts/claudemd_optimizer.py CLAUDE.md --json

Tools

Skill Scaffolder

Generates a skill directory with SKILL.md template, scripts/, references/, assets/ directories, and YAML frontmatter.

python scripts/skill_scaffolder.py my-skill --domain engineering --description "Does X"

Parameter Description

skill_name

Name for the skill (kebab-case)

--domain, -d

Domain category

--description

Brief description for frontmatter

--version

Semantic version (default: 1.0.0)

--license

License type (default: MIT)

--output, -o

Parent directory for skill folder

--json

Output as JSON

CLAUDE.md Optimizer

Analyzes a CLAUDE.md file and produces optimization recommendations.

python scripts/claudemd_optimizer.py CLAUDE.md --token-limit 4000 --json

Output includes: line count, token estimate, section completeness, redundancy detection, missing sections, scored recommendations.

Context Analyzer

Scans a project to estimate context window consumption by file category.

python scripts/context_analyzer.py /path/to/project --max-depth 4 --json

Output includes: token estimates per category, percentage of context consumed, largest files, budget breakdown, reduction recommendations.

Workflow 1: Optimize a CLAUDE.md

• Audit -- Run python scripts/claudemd_optimizer.py CLAUDE.md and capture the score.

• Structure -- Reorganize into these sections:

Project Purpose -- What the project is

Architecture Overview -- Directory structure, key patterns

Development Environment -- Build, test, setup commands

Key Principles -- 3-7 non-obvious rules

Anti-Patterns to Avoid -- Things that look right but are wrong

Git Workflow -- Branch strategy, commit conventions

• Compress -- Convert paragraphs to bullets (saves ~30% tokens). Use code blocks for commands. Remove generic advice Claude already knows.

• Hierarchize -- Move domain details to child CLAUDE.md files: project/ ├── CLAUDE.md # Global: purpose, architecture, principles ├── frontend/CLAUDE.md # Frontend-specific: React patterns, styling ├── backend/CLAUDE.md # Backend-specific: API patterns, DB conventions └── .claude/CLAUDE.md # User-specific overrides (gitignored)

• Validate -- Run python scripts/claudemd_optimizer.py CLAUDE.md --token-limit 4000 and confirm score improved.

Workflow 2: Author a New Skill

• Scaffold -- python scripts/skill_scaffolder.py my-skill -d engineering --description "..."

• Write SKILL.md in this order:

• YAML frontmatter (name, description with trigger phrases, license, metadata)

• Title and one-line summary

• Quick Start (3-5 copy-pasteable commands)

• Tools (each script with usage and parameters table)

• Workflows (numbered step-by-step sequences)

• Reference links

• Optimize the description for auto-discovery: description: >- This skill should be used when the user asks to "analyze performance", "optimize queries", "profile memory", or "benchmark endpoints". Use for performance engineering and capacity planning.

• Build Python tools -- standard library only, argparse CLI, --json flag, module docstring, error handling.

• Verify -- Confirm the skill triggers on expected prompts and tools run without errors.

Workflow 3: Create a Subagent

• Define scope -- One narrow responsibility per agent.

• Create agent YAML at .claude/agents/agent-name.yaml : name: security-reviewer description: Reviews code for security vulnerabilities model: claude-sonnet-4-20250514 allowed-tools:

  • Read
  • Glob
  • Grep
  • Bash(git diff*) custom-instructions: | For every change:
  1. Check for hardcoded secrets
  2. Identify injection vulnerabilities
  3. Verify auth patterns
  4. Flag insecure dependencies Output a structured report with severity levels.

• Set tool access -- read-only (Read, Glob, Grep ), read+commands (+ Bash(npm test*) ), or write-capable (+ Edit, Write ).

• Invoke -- /agents/security-reviewer Review the last 3 commits

• Validate -- Confirm the agent stays within scope and produces structured output.

Workflow 4: Configure Hooks

Hooks run custom scripts at lifecycle events without user approval.

Hook Fires When Blocking

PreToolUse

Before tool executes Yes (exit 1 blocks)

PostToolUse

After tool completes No

Notification

Claude sends notification No

Stop

Claude finishes turn No

• Add hook config to .claude/settings.json : { "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "prettier --write "$CLAUDE_FILE_PATH" 2>/dev/null || true" }] } ], "PreToolUse": [ { "matcher": "Bash", "hooks": [{ "type": "command", "command": "bash .claude/hooks/validate.sh" }] } ] } }

• Test -- Trigger the relevant tool and confirm the hook fires.

• Iterate -- Add matchers for additional tools as needed.

Workflow 5: Manage Context Budget

• Audit -- python scripts/context_analyzer.py /path/to/project

• Apply budget targets:

Category Budget Purpose

System prompt + CLAUDE.md 5-10% Project configuration

Skill definitions 5-15% Active skill content

Source code (read files) 30-50% Files Claude reads

Conversation history 20-30% Messages and responses

Working memory 10-20% Reasoning space

• Reduce overhead -- Keep root CLAUDE.md under 4000 tokens. Use hierarchical loading. Avoid reading entire large files. Use /compact after completing subtasks.

• Validate -- Re-run context analyzer and confirm overhead dropped.

Quick Reference

Slash Commands

Command Description

/compact

Summarize conversation to free context

/clear

Clear conversation history

/model

Switch model mid-session

/agents

List and invoke custom agents

/permissions

View and modify tool permissions

/cost

Show token usage and cost

/doctor

Diagnose configuration issues

/init

Generate CLAUDE.md for current project

Permission Modes

Mode Behavior Best For

Default Asks permission for writes Normal development

Allowlist Auto-approves listed tools Repetitive workflows

Yolo Auto-approves everything Trusted automation

{ "permissions": { "allow": ["Read", "Glob", "Grep", "Bash(npm test*)"], "deny": ["Bash(rm -rf*)", "Bash(git push*)"] } }

CLAUDE.md Loading Order

• ~/.claude/CLAUDE.md -- user global, always loaded

• /project/CLAUDE.md -- project root, always loaded

• /project/.claude/CLAUDE.md -- project config, always loaded

• /project/subdir/CLAUDE.md -- subdirectory, loaded when files accessed

MCP Servers

Server Purpose

server-filesystem

File access beyond project

server-github

GitHub API (issues, PRs)

server-postgres

Database queries

server-memory

Persistent key-value store

server-brave-search

Web search

server-puppeteer

Browser automation

Reference Documentation

Document Path

Skill Authoring Guide references/skill-authoring-guide.md

Subagent Patterns references/subagent-patterns.md

Hooks Cookbook references/hooks-cookbook.md

Skill Template assets/skill-template.md

Agent Template assets/agent-template.md