I was wrong about Agent Skills and how I refactor them

I was wrong about Agent Skills and how I refactor them

What Happened

Agent Skills dropped October 16th. I started building them immediately. Within two weeks, I had a cloudflare skill at 1,131 lines, a shadcn-ui skill at 850 lines, and a nextjs skill at 900 lines, chrome-devtools skill with >1,200 lines. Every time Claude Code activated multiple related skills, I'd see context window grows dramatically. Loading 5-7 skills meant 5,000-7,000 lines flooding the context window immediately.

I thought this was just how it had to be. Put everything in one giant SKILL.md file so the agent has all the information upfront. More information = better results, right?

Wrong.

The Brutal Truth

This is embarrassing because the solution was staring me in the face the whole time. I was treating agent skills like documentation dumps instead of what they actually are: context engineering problems.

The frustrating part is that I even documented the "progressive disclosure" principle in the skill-creator skill itself. I wrote it down. I just didn't understand what it actually meant in practice.

Here's what really pisses me off: I wasted two weeks debugging "context growing" issues and slow activation times when the problem was entirely self-inflicted. Every single one of those massive SKILL.md files was loading irrelevant information 90% of the time.

Technical Details

Before: The Disaster

.claude/skills/
├── cloudflare/           1,131 lines
├── cloudflare-workers/   ~800 lines
├── nextjs/               ~900 lines
├── shadcn-ui/            ~850 lines
├── chrome-devtools/      ~1,200 lines
└── (30 more similarly bloated files)

Total: ~15,000 lines across 36 skills (Approximately 120K to 300K tokens)

Problem: Activating the devops context (Cloudflare or Docker or GCloud continuously) meant loading 2,500+ lines immediately. Most of it was never used.

After: Progressive Disclosure Architecture

I refactored using a 3-tier loading system:

Tier 1: Metadata (always loaded)

• YAML frontmatter only
• ~100 words
• Just enough for Claude to decide if the skill is relevant

Tier 2: SKILL.md entry point (loaded when skill activates)

• ~200 lines max
• Overview, quick start, navigation map
• Points to references but doesn't include their content

Tier 3: Reference files & scripts (loaded on-demand)

• 200-300 lines each
• Detailed documentation Claude reads only when needed
• Modular and focused on single topics

The Numbers

claude-code skill refactor:

• Before: 870 lines in one file
• After: 181 lines + 13 reference files
• Reduction: 79% (4.8x better token efficiency)

Complete Phase 1 & 2 reorganization:

• Before: 15,000 lines across 36 individual skills
• After: Consolidated into 20 focused skill groups (2,200 lines initial load + 45 reference files)
  • devops (Cloudflare, Docker, GCloud - 14 tools)
  • web-frameworks (Next.js, Turborepo, RemixIcon)
  • ui-styling (shadcn/ui, Tailwind, canvas-design)
  • databases (MongoDB, PostgreSQL)
  • ai-multimodal (Gemini API - 5 modalities)
  • media-processing (FFmpeg, ImageMagick)
  • chrome-devtools, code-review, sequential-thinking, docs-seeker, mcp-builder,...
• Reduction: 85% on initial activation

Real impact:

• Activation time: ~500ms → <100ms
• Context overflow: Fast → Slow
• Relevant information ratio: ~10% → ~90%

Root Cause Analysis

The fundamental mistake: I confused "available information" with "loaded information".

But again, there's a deeper misunderstanding: Agent skills aren't documentation.

They're specific abilities and knowledge for development workflows. Each skill represents a capability:

• devops isn't "Cloudflare documentation" - it's the ability to deploy serverless functions
• ui-styling isn't "Tailwind docs" - it's the ability to design consistent interfaces
• sequential-thinking isn't a guide - it's a problem-solving methodology

I had 36 individual skills because I treated each tool as needing its own documentation dump. Wrong. Skills should be organized by workflow capabilities, not by tools.

That's why consolidation worked:

• 36 tool-specific skills → 20 workflow-capability groups
• "Here's everything about Cloudflare" → "Here's how to handle DevOps deployment with Cloudflare, GCloud, Docker, Vercel."
• Documentation mindset → Development workflow mindset

The 200-line limit isn't arbitrary. It's based on how much context an LLM can efficiently scan to decide what to load next. Keep the entry point under ~200 lines, and Claude can quickly:

• Understand what the skill offers
• Decide which reference file to read
• Load just that file (another ~200-300 lines)

Total: 400-700 lines of highly relevant context instead of 1,131 lines of mixed relevance.

This is context engineering 101 and I somehow missed it.

Lessons Learned

1. The 200-line rule matters - It's not a suggestion. It's the difference between fast navigation and context sludge.

2. Progressive disclosure isn't optional - Every skill over 200 lines should be refactored. No exceptions. If you can't fit the core instructions in 200 lines, you're putting too much in the entry point.

3. References are first-class citizens - I treated references/ as "optional extra documentation." Wrong. References are where the real work happens. SKILL.md is just the map.

4. Test the cold start - Clear your context, activate the skill, and measure. If it loads more than 500 lines on first activation, you're doing it wrong.

5. Metrics don't lie - 4.8x token efficiency isn't marginal improvement. It's the difference between "works sometimes" and "works reliably."

The pattern is validated.

In conclusion

Skills ≠ Documentation

Skills are capabilities that activate during specific workflow moments:

• Writing tests → activate code-review
• Debugging production → activate sequential-thinking
• Deploying infrastructure → activate devops
• Building UI → activate ui-styling + web-frameworks

Each skill teaches Claude how to perform a specific development task, not what a tool does.

That's why treating them like documentation failed. Documentation is passive reference material. Skills are active workflow knowledge.

Progressive disclosure works because it matches how development actually happens:

1. Scan metadata → Is this capability relevant to current task?
2. Read entry point → What workflow patterns does this enable?
3. Load specific reference → Get implementation details for current step

Each step is small, focused, and purposeful. That's how you build skills that actually help instead of overwhelming.

The painful part isn't that I got it wrong initially—Agent Skills are brand new (3 weeks old). The painful part is that I documented the solution myself without understanding it.

Two weeks of confusion. One weekend of refactoring. Lesson learned: context engineering isn't about loading more information. It's about loading the right information at the right time.

If you want to see the repo, check this out:

• Before (another branch):
• After (main branch):