claude-code-mastery: A Meta-Skill for Getting More Out of Claude Code
84 stars and holding steady on SkillsMP, with the trend status marked as rising. For a skill that's essentially documentation tooling for other skills, that's a signal worth paying attention to. Either a lot of developers are hitting the same walls with Claude Code configuration, or borghei has built something genuinely useful. After digging through the SKILL.md and the underlying scripts, I think it's mostly the former — and this skill addresses it reasonably well.
What This Skill Actually Does
This is a meta-skill. It doesn't make Claude better at React, Terraform, or SQL. It makes Claude better at using Claude Code itself — specifically at the operational layer that most developers treat as an afterthought: CLAUDE.md files, context budgeting, subagent definitions, and lifecycle hooks.
Under the hood, it ships three Python scripts:
skill_scaffolder.py— generates a new skill package with the correct directory structure and YAML frontmatterclaudemd_optimizer.py— audits a CLAUDE.md file and returns scored recommendationscontext_analyzer.py— scans a project and estimates token consumption by file category
All three support --json output, which means they're pipeline-friendly. That's a small thing, but it tells you something about the author's intent: these are meant to be used in actual workflows, not just run once and forgotten.
Why This Exists (And Why It Matters)
Here's the honest problem: most developers who use Claude Code have a CLAUDE.md that's either empty, copied from a blog post, or a 3,000-word stream of consciousness that eats a significant chunk of their context window before Claude has read a single line of actual code.
The context window problem is real and it compounds. Every token you waste on a bloated CLAUDE.md is a token that isn't available for the files Claude needs to reason about. And because CLAUDE.md is loaded on every session, the waste is constant, not occasional.
The same applies to subagents. Claude Code supports custom agent definitions, but the documentation on how to structure them for narrow, reliable scope is scattered. Most people either don't use subagents at all, or they create ones that are too broad and produce inconsistent output.
This skill attempts to codify the operational best practices that experienced Claude Code users have figured out through trial and error. Whether it succeeds is a different question.
Key Capabilities Worth Calling Out
1. CLAUDE.md Optimizer with Scoring
This is the most immediately useful tool. You point it at an existing CLAUDE.md, it estimates token usage, checks for missing sections, flags redundancy, and returns recommendations with a score. The --token-limit flag lets you set a budget (the skill recommends 4,000 tokens for root CLAUDE.md files) and see whether you're over it.
I like that it produces scored recommendations rather than just a diff. It forces you to think about tradeoffs rather than blindly applying every suggestion.
2. Hierarchical CLAUDE.md Structure
The workflow documentation makes a strong case for splitting CLAUDE.md files across your project tree — a root file for global context, subdirectory files for domain-specific patterns. This isn't novel advice, but having it codified with a concrete directory layout and a tool that enforces the structure is useful. The scaffolder handles the directory creation so you don't have to think about it.
3. Context Budget Targets
Workflow 5 includes a token budget breakdown that I haven't seen written down anywhere else in this much detail:
- System prompt + CLAUDE.md: 5–10%
- Skill definitions: 5–15%
- Source code reads: 30–50%
- Conversation history: 20–30%
- Working memory: 10–20%
These are opinionated numbers, and I don't know how empirically derived they are, but having a starting framework is better than nothing. The context_analyzer.py script gives you actual numbers to compare against these targets.
4. Subagent YAML Templates
The subagent workflow is solid. The example security-reviewer agent definition is a good template — it demonstrates narrow tool access (Read, Glob, Grep, Bash(git diff*) only), structured output requirements, and a clear single responsibility. If you've been avoiding subagents because the setup felt unclear, this workflow will get you started in under 10 minutes.
5. Hooks Configuration
The hooks documentation covers PreToolUse, PostToolUse, Notification, and Stop events with a clear table showing which ones are blocking. The example of auto-running Prettier after every Edit/Write operation is exactly the kind of thing that should be in a hooks tutorial. Practical, not theoretical.
Who Should Install This
Install it if: - You're spending more than a few hours a week in Claude Code and haven't seriously optimized your CLAUDE.md - You're building your own skills for the SkillsMP marketplace and want a scaffolding tool - You're hitting context window limits mid-session and don't have a systematic way to diagnose why - You want to start using subagents but the official documentation hasn't clicked for you
Skip it if: - You're a casual Claude Code user who runs it occasionally for one-off tasks - Your CLAUDE.md is already well-structured and under 3,000 tokens - You're looking for domain-specific expertise (this skill doesn't make Claude better at any particular technology stack) - You want something that installs and works immediately with zero configuration — this requires you to run Python scripts and read output
How to Install
# Clone the specific skill into your Claude skills directory
git clone --depth=1 --filter=blob:none --sparse \
https://github.com/borghei/Claude-Skills.git /tmp/claude-skills
cd /tmp/claude-skills
git sparse-checkout set engineering/claude-code-mastery
cp -r engineering/claude-code-mastery ~/.claude/skills/claude-code-mastery
Or use the cs.py CLI if you've already cloned the full repo:
python scripts/cs.py install claude-code-mastery --agent claude
The scripts require Python 3.x with no external dependencies — standard library only. That's a deliberate design choice and I appreciate it. Nothing to pip install, nothing to break.
Concerns and Limitations
Let me be direct about a few things that gave me pause.
The description field is empty. The SKILL.md frontmatter has description: with nothing after it. For a skill that explicitly teaches you to write good skill descriptions — including a whole section on optimizing descriptions for auto-discovery — shipping with a blank description is an embarrassing oversight. It undermines confidence in the author's attention to detail.
The metadata date says 2026-03-31. Either this is a typo or the author is from the future. Either way, it's a data quality issue that makes me wonder what else wasn't proofread.
The recommendations are opinionated without much empirical backing. The 4,000 token limit for CLAUDE.md, the budget percentages, the "compress paragraphs to bullets saves ~30% tokens" claim — these feel like reasonable heuristics, but I don't know how rigorously they were tested. Treat them as starting points, not gospel.
The skill is self-referential in a way that can feel circular. It teaches you to author skills using a skill. If you're new to the Claude Skills ecosystem entirely, you may need to read the broader repo documentation before this one makes full sense.
No tests for the scripts. The Python tools are straightforward enough that this isn't a dealbreaker, but if you're running claudemd_optimizer.py as part of a CI pipeline, you're trusting code with no test coverage.
Verdict
This is a legitimate utility skill with a clear use case. The three Python tools are practical, the workflows are well-documented, and the hooks and subagent templates are worth having even if you only use them as reference material.
The empty description and future-dated metadata are sloppy, and I'd want to see the token budget recommendations backed by more than intuition. But neither of those issues breaks the core functionality.
If you're a serious Claude Code user who hasn't systematically optimized your configuration, install this, run claudemd_optimizer.py against your current CLAUDE.md, and see what it tells you. Worst case you spend 20 minutes and learn nothing new. Best case you recover meaningful context budget on every session going forward.
Rating: Install it, use the optimizer and context analyzer, treat the budget numbers as starting points.