Claude Code Mastery

March 30, 2026 · View on GitHub

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

Troubleshooting

Problem	Cause	Solution
CLAUDE.md changes not picked up	Claude loads CLAUDE.md at session start	Start a new conversation or use `/clear` to reload configuration
Skill not triggering on expected prompts	Description field in YAML frontmatter missing trigger phrases	Add quoted user phrases to the `description` field (e.g., `"optimize queries"`, `"profile memory"`)
Context window exhausted mid-task	Root CLAUDE.md too large or too many files read	Run `context_analyzer.py` to audit token usage, then move domain content to child CLAUDE.md files
Hook not firing after tool use	Matcher in `.claude/settings.json` does not match the tool name	Verify the `matcher` regex matches the exact tool name (e.g., `Edit\|Write`, not `edit\|write`)
Subagent exceeds scope and edits unrelated files	`allowed-tools` list is too permissive	Restrict to read-only tools (`Read, Glob, Grep`) and add write tools only when necessary
Scaffolder fails with "Directory already exists"	Target skill directory already present on disk	Remove or rename the existing directory, or choose a different skill name
Optimizer reports low score despite good structure	Token count exceeds the default 6000 limit	Pass `--token-limit` matching your actual budget (e.g., `--token-limit 10000`)

Success Criteria

CLAUDE.md optimizer score of 80+ on all project CLAUDE.md files
Root CLAUDE.md stays under 4000 tokens (verified by claudemd_optimizer.py --token-limit 4000)
Auto-loaded configuration (all CLAUDE.md files combined) consumes less than 10% of the context window
Every new skill scaffolded passes the optimizer with zero "critical" missing sections
Subagents stay within their declared allowed-tools scope during testing
Hooks execute in under 500ms to avoid perceptible delay on tool use
Context analyzer shows 50%+ of the context window available for source code and reasoning

Scope & Limitations

This skill covers:

Authoring, structuring, and optimizing CLAUDE.md files for any project
Scaffolding new skill packages with correct directory layout and frontmatter
Creating and configuring Claude Code subagents with scoped tool access
Analyzing and managing context window token budgets across a codebase

This skill does NOT cover:

Writing application source code or implementing business logic (see senior-fullstack, senior-backend)
MCP server development or custom transport protocols (see mcp-server-builder)
Advanced prompt engineering techniques for LLM applications (see senior-prompt-engineer)
CI/CD pipeline configuration or deployment automation (see senior-devops, ci-cd-pipeline-builder)

Integration Points

Skill	Integration	Data Flow
senior-architect	Architecture decisions inform CLAUDE.md structure sections	Architecture diagrams and patterns feed into the Architecture Overview section of CLAUDE.md
code-reviewer	Subagent creation for automated code review	Claude Code Mastery creates the agent YAML; Code Reviewer provides the review logic
senior-prompt-engineer	Prompt optimization for skill descriptions and agent instructions	Prompt engineering techniques improve YAML frontmatter trigger phrases and agent `custom-instructions`
doc-drift-detector	Detects when CLAUDE.md drifts out of sync with the codebase	Context Analyzer output feeds drift detection; drift findings trigger CLAUDE.md optimization
context-engine	Advanced context management strategies	Context Analyzer provides token budgets; Context Engine applies compression and prioritization
senior-secops	Security hooks and permission mode configuration	SecOps policies define which tools to deny; Claude Code Mastery configures the permission allowlists

Tool Reference

1. Skill Scaffolder (`scripts/skill_scaffolder.py`)

Purpose: Generate a complete skill package directory with SKILL.md template, starter Python script, reference document, and proper YAML frontmatter.

Usage:

python scripts/skill_scaffolder.py <skill_name> [options]

Parameters:

Parameter	Type	Required	Default	Description
`skill_name`	positional	Yes	--	Name for the skill in kebab-case (e.g., `my-new-skill`)
`--domain, -d`	string	No	`engineering`	Domain category. Options: `engineering`, `marketing`, `product`, `project-management`, `c-level`, `ra-qm`, `business-growth`, `finance`, `standards`, `development-tools`
`--description`	string	No	auto-generated	Brief description for YAML frontmatter, optimized for auto-discovery
`--version`	string	No	`1.0.0`	Semantic version for metadata
`--license`	string	No	`MIT`	License type for frontmatter
`--category`	string	No	same as domain	Skill category for metadata
`--output, -o`	string	No	`.` (current dir)	Parent directory for the skill folder
`--json`	flag	No	off	Output results in JSON format

Example:

python scripts/skill_scaffolder.py api-analyzer -d engineering --description "API analysis and optimization" --json

Output Formats:

Human-readable (default): Prints skill name, domain, version, location, directory tree, and next-steps checklist.
JSON (--json): Returns { success, path, name, domain, version, directories_created, files_created }.

2. CLAUDE.md Optimizer (`scripts/claudemd_optimizer.py`)

Purpose: Analyze a CLAUDE.md file for structure completeness, token efficiency, redundancy, and verbosity. Produces a scored report with prioritized optimization recommendations.

Usage:

python scripts/claudemd_optimizer.py <file_path> [options]

Parameters:

Parameter	Type	Required	Default	Description
`file_path`	positional	Yes	--	Path to the CLAUDE.md file to analyze
`--token-limit`	integer	No	`6000`	Maximum recommended token count for the file
`--json`	flag	No	off	Output results in JSON format

Example:

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

Output Formats:

Human-readable (default): Displays score (0-100), file metrics (lines, words, tokens), section breakdown with per-section token estimates, section completeness checklist (critical/high/medium), redundancy issues, and prioritized recommendations (HIGH/MEDIUM/LOW).
JSON (--json): Returns { success, file, metrics, sections, completeness, redundancies, recommendations, score }.

3. Context Analyzer (`scripts/context_analyzer.py`)

Purpose: Scan a project directory to estimate how much of Claude Code's context window is consumed by CLAUDE.md files, skill definitions, source code, and configuration. Produces a token budget breakdown with reduction recommendations.

Usage:

python scripts/context_analyzer.py <project_path> [options]

Parameters:

Parameter	Type	Required	Default	Description
`project_path`	positional	Yes	--	Path to the project directory to analyze
`--max-depth`	integer	No	`5`	Maximum directory traversal depth
`--context-window`	integer	No	`200000`	Total context window size in tokens
`--json`	flag	No	off	Output results in JSON format

Example:

python scripts/context_analyzer.py /path/to/project --max-depth 3 --context-window 200000 --json

Output Formats:

Human-readable (default): Displays project summary (files scanned, total tokens, auto-loaded tokens), context budget breakdown with visual bar chart, per-category breakdown (Claude Configuration, Skill Definitions, Reference Documents, Source Code, Config & Build, Documentation) with largest files listed, top 20 largest files, and prioritized recommendations.
JSON (--json): Returns { success, project_path, context_window, summary, categories, budget, largest_files, recommendations }.