claude-code-mastery（Claude 代码 mastery）

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"

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

1. Audit -- Run python scripts/claudemd_optimizer.py CLAUDE.md and capture the score.
2. 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
3. Compress -- Convert paragraphs to bullets (saves ~30% tokens). Use code blocks for commands. Remove generic advice Claude already knows.
4. 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)
5. Validate -- Run python scripts/claudemd_optimizer.py CLAUDE.md --token-limit 4000 and confirm score improved.

Workflow 2: Author a New Skill

1. Scaffold -- python scripts/skill_scaffolder.py my-skill -d engineering --description "..."
2. 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

1. 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.
2. Build Python tools -- standard library only, argparse CLI, --json flag, module docstring, error handling.
3. Verify -- Confirm the skill triggers on expected prompts and tools run without errors.

Workflow 3: Create a Subagent

1. Define scope -- One narrow responsibility per agent.
2. 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.
3. Set tool access -- read-only (Read, Glob, Grep), read+commands (+ Bash(npm test*)), or write-capable (+ Edit, Write).
4. Invoke -- /agents/security-reviewer Review the last 3 commits
5. 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.

1. 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"}]}]}}
2. Test -- Trigger the relevant tool and confirm the hook fires.
3. Iterate -- Add matchers for additional tools as needed.

Workflow 5: Manage Context Budget

1. Audit -- python scripts/context_analyzer.py /path/to/project
2. 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
3. Reduce overhead -- Keep root CLAUDE.md under 4000 tokens. Use hierarchical loading. Avoid reading entire large files. Use /compact after completing subtasks.
4. Validate -- Re-run context analyzer and confirm overhead dropped.

Quick Reference

Slash Commands

Permission Modes

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

CLAUDE.md Loading Order

1. ~/.claude/CLAUDE.md -- user global, always loaded
2. /project/CLAUDE.md -- project root, always loaded
3. /project/.claude/CLAUDE.md -- project config, always loaded
4. /project/subdir/CLAUDE.md -- subdirectory, loaded when files accessed

MCP Servers

Reference Documentation

Troubleshooting

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

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:

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:

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:

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}.