Expert skill for Claude Code CLI -- CLAUDE.md optimization, skill authoring, subagent creation, hooks automation, and context engineering.
.claude/agents/<name>.md files with a tools allowlist and a Markdown-body system prompt.PreToolUse/PostToolUse/Stop lifecycle scripts via .claude/settings.json.Before scaffolding or optimizing, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.
skill_scaffolder.py vs claudemd_optimizer.py vs context_analyzer.py).--token-limit and what counts as over-budget).Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.
# Score a CLAUDE.md for structure, token cost and redundancy (default budget 6000 tokens)
python scripts/claudemd_optimizer.py CLAUDE.md --token-limit 4000
# Estimate how much of the context window a project's files would take, by category
python scripts/context_analyzer.py . --max-depth 4 --context-window 200000
# Scaffold a skill package into an existing parent directory
python scripts/skill_scaffolder.py my-skill -d engineering -o /tmp --description "Scores API specs for breaking changes"All three accept --json. Full flags and output fields: references/tool-reference.md.
claudemd_optimizer.py reports a 0–100 score, the token estimate against --token-limit, duplicated or vague sections, and concrete cuts.context_analyzer.py defaults to a 200K window as a conservative floor. Pass the real window of the model you run, or the percentages will overstate the pressure.skill_scaffolder.py creates <-o DIR>/<skill-name>/ with SKILL.md, scripts/, references/ and assets/. -o (--output) is the parent directory, which must already exist; it defaults to the current directory, so pass -o to keep the scaffold out of the repo you are standing in. If the description has no "Use when" clause it appends a placeholder so you fill in the triggers before shipping.Exit codes (all three): 0 report or scaffold written; 2 missing file or path, output directory that does not exist, or a skill folder that already exists. They are advisory, not gates: an over-budget CLAUDE.md still exits 0.
Done when: the CLAUDE.md fits its budget and every line is something the model could not infer from the code; a new skill's description says what it does and when to use it in under 240 characters; a hook has been triggered once on purpose and blocked or passed as intended.
Mistake: Pasting architecture essays, full style guides and onboarding notes into CLAUDE.md.
Why it happens: It is the one file the agent always reads, so everything lands there.
Instead: Keep commands, conventions and traps the code does not reveal; link to longer docs and let the agent read them when needed. Every line costs tokens on every turn.
Mistake: A PreToolUse guard that exits 1 on a violation and assumes the tool call was blocked.
Why it happens: Exit 1 means "error" in most CLIs.
Instead: A PreToolUse hook blocks only on exit 2 (stderr goes back to the model). Test the hook against a real violating command before relying on it. See references/hooks-cookbook.md.
Mistake: A review subagent with no tools allowlist, so it can edit files and run shell commands.
Why it happens: Omitting tools is the shortest working file.
Instead: Give each subagent the smallest tool list its job needs; a reviewer gets read and search tools only.
scripts/claudemd_optimizer.py, scripts/context_analyzer.py, scripts/skill_scaffolder.py — the three CLIs above.assets/skill-template.md, assets/agent-template.md — starting files for a skill and a subagent.references/ — playbooks, quick reference, tool reference, skill authoring, subagent patterns, hooks cookbook.Load the reference that matches the task — keep this file lean and pull detail on demand:
Templates: assets/skill-template.md, assets/agent-template.md
This skill covers:
This skill does NOT cover: