Refactoring Agent Skills: The Day My Context Window Died There’s a specific kind of pain you only experience once: You’re in Claude Code, you trigger a couple of “helpful” Skills, and suddenly, the model is chewing through thousands of lines of markdown + snippets it didn’t ask for. thousands of lines Your “AI co-pilot” stops feeling like a co-pilot and starts feeling like a browser tab you can’t close. This piece is a practical rewrite (and upgrade) of a popular Claude Code community refactor story: a developer thought “more info = better,” built Skills like mini-wikis, and accidentally created a context explosion. The fix wasn’t a clever prompt. It was an architectural refactor. The result: dramatically leaner initial context and much better token efficiency. context explosion Let’s steal the playbook. 1. The Root Cause: Treating Skills Like Docs ============================================ The first trap is incredibly human: “If I include everything, the model will always have what it needs.” “If I include everything, the model will always have what it needs.” So, you create one Skill per tool, and each Skill becomes a documentation dump: setup steps
API references
exhaustive examples
“don’t do X” lists
every edge case since 2017 setup steps API references exhaustive examples “don’t do X” lists every edge case since 2017 Then a task like “deploy a serverless function with a small UI” pulls in: your Cloudflare skill,
your Docker skill,
your UI styling skill,
your web framework skill… your Cloudflare skill, your Docker skill, your UI styling skill, your web framework skill… …and the model starts its job already half-drowned. Claude Code’s own docs warn that Skills share the context window with the conversation, the request, and other Skills — which means uncontrolled loading is a direct performance tax. (You feel it as slowness, drift, and “why is it ignoring the obvious part?”) So: your problem isn’t “lack of info.” It’s “too much irrelevant info.” your problem isn’t “lack of info.” It’s “too much irrelevant info.” 2. The Fix: Progressive Disclosure (Three Layers) ================================================= Claude Code docs explicitly recommend progressive disclosure: keep essential info in SKILL.md, and store the heavy stuff in separate files that get loaded only when the task requires them. progressive disclosure SKILL.md This maps cleanly to a three-layer system: Layer 1 — Metadata (always loaded) A short YAML frontmatter: name + description + the “routing signal.” Think of it like a book cover and blurb. You’re not teaching. You’re helping the model decide whether to open the book. Layer 2 — Entry point: SKILL.md (loaded on activation) SKILL.md Your navigation map: what the Skill is for
when to use it
what steps to follow
what files to open next what the Skill is for when to use it what steps to follow what files to open next Not a tutorial. Not a wiki. Layer 3 — References & scripts (loaded only when needed) only when needed Small, focused files: one topic per file
200–300 lines per file is a good target
scripts do deterministic work, so the model doesn’t burn tokens “describing” actions one topic per file 200–300 lines per file is a good target scripts do deterministic work, so the model doesn’t burn tokens “describing” actions Here’s what that looks like in a real folder: .claude/skills/devops/
├── SKILL.md
├── references/
│   ├── serverless-cloudflare.md
│   ├── containers-docker.md
│   └── ci-cd-basics.md
└── scripts/
    ├── validate_env.py
    └── deploy_helper.sh .claude/skills/devops/
├── SKILL.md
├── references/
│   ├── serverless-cloudflare.md
│   ├── containers-docker.md
│   └── ci-cd-basics.md
└── scripts/
    ├── validate_env.py
    └── deploy_helper.sh 3. The “200-Line Rule”: Brutal, Slightly Arbitrary, Weirdly Effective ===================================================================== In the community refactor story, the author landed on a hard constraint: Keep SKILL.md under ~200 lines. If you can’t, you’re putting too much in the entry point. Keep SKILL.md under ~200 lines. If you can’t, you’re putting too much in the entry point. Keep SKILL.md Claude’s own best practices docs recommend keeping the body under a few hundred lines (and splitting content as you approach that limit). But “200 lines” is a sharper knife: it forces you to write a table of contents, not a textbook. table of contents Why it works: The model can scan the entry quickly
It can decide what reference file to load next
Total “initial load” stays small enough that the conversation still has room to breathe The model can scan the entry quickly It can decide what reference file to load next Total “initial load” stays small enough that the conversation still has room to breathe A quick test you can steal Start a fresh session (cold start)
Trigger your Skill
If your first activation loads more than ~500 lines of content, your design is likely leaking scope Start a fresh session (cold start) Trigger your Skill If your first activation loads more than ~500 lines of content, your design is likely leaking scope more than ~500 lines 4. The Real Mental Shift: From Tool-Centric to Workflow-Centric =============================================================== This is the part most people miss. Tool-centric Skills look like: Tool-centric Skills cloudflare-skill
tailwind-skill
postgres-skill
kubernetes-skill cloudflare-skill cloudflare-skill tailwind-skill tailwind-skill postgres-skill postgres-skill kubernetes-skill kubernetes-skill They’re encyclopedias. They don’t compose well. Workflow-centric Skills look like: Workflow-centric Skills devops (deploy + environments + CI/CD)
ui-styling (design rules + component patterns)
web-frameworks (routing + project structure + SSR pitfalls)
databases (schema design + migrations + query patterns) devops (deploy + environments + CI/CD) devops ui-styling (design rules + component patterns) ui-styling web-frameworks (routing + project structure + SSR pitfalls) web-frameworks databases (schema design + migrations + query patterns) databases They map to what you actually do during development. actually do A workflow Skill answers: “When I’m in this stage of work, what does the agent need to know to act correctly?” “When I’m in this stage of work, what does the agent need to know to act correctly?” Not: “What is everything this tool can do?” “What is everything this tool can do?” That one reframing prevents context blowups almost by itself. 5. A Minimal, Production-Grade SKILL.md (Example) =================================================== SKILL.md Here’s a deliberately small entry point you can copy and customise. Notice what’s missing: long examples, full docs, and “everything you might ever need.” ---
name: ui-styling
description: Apply consistent UI styling across the app (Tailwind + component conventions). Use when building or refactoring UI.
---

# UI Styling Skill

## When to use
- You are building UI components or pages
- You need consistent spacing, typography, and responsive behaviour
- You need to align with existing design conventions

## Workflow
1. Identify the UI surface (page/component) and constraints (responsive, dark mode, accessibility)
2. Apply styling rules from the references (pick only what you need)
3. Validate output against the checklist

## References (load only if needed)
- `references/design-tokens.md` — spacing, font scale, colour usage
- `references/tailwind-patterns.md` — layouts, common utility combos
- `references/accessibility-checklist.md` — keyboard, focus, contrast

## Output contract
- Use UK English in UI strings
- Prefer reusable components over copy-paste blocks
- Keep className readable (extract when it gets messy) ---
name: ui-styling
description: Apply consistent UI styling across the app (Tailwind + component conventions). Use when building or refactoring UI.
---

# UI Styling Skill

## When to use
- You are building UI components or pages
- You need consistent spacing, typography, and responsive behaviour
- You need to align with existing design conventions

## Workflow
1. Identify the UI surface (page/component) and constraints (responsive, dark mode, accessibility)
2. Apply styling rules from the references (pick only what you need)
3. Validate output against the checklist

## References (load only if needed)
- `references/design-tokens.md` — spacing, font scale, colour usage
- `references/tailwind-patterns.md` — layouts, common utility combos
- `references/accessibility-checklist.md` — keyboard, focus, contrast

## Output contract
- Use UK English in UI strings
- Prefer reusable components over copy-paste blocks
- Keep className readable (extract when it gets messy) That’s it. The Skill’s job is to route the agent to the right file at the right moment — not to become an on-page encyclopedia. route 6. Measuring Improvements (Without Lying to Yourself) ===================================================== If you want repeatable results, track metrics that actually matter: Initial lines loaded on activation
Time to activation (roughly: how “snappy” it feels)
Relevance ratio (how much of the loaded content is used)
Context overflow frequency (how often long tasks crash) Initial lines loaded on activation Initial lines loaded Time to activation (roughly: how “snappy” it feels) Time to activation Relevance ratio (how much of the loaded content is used) Relevance ratio Context overflow frequency (how often long tasks crash) Context overflow frequency You don’t need a full observability stack. A simple repo audit script helps. Tiny Python audit: count lines per Skill from pathlib import Path

skills_dir = Path(".claude/skills")

def count_lines(p: Path) -> int:
    return sum(1 for _ in p.open("r", encoding="utf-8", errors="ignore"))

for skill in sorted(skills_dir.iterdir()):
    skill_md = skill / "SKILL.md"
    if skill_md.exists():
        lines = count_lines(skill_md)
        status = "OK" if lines <= 200 else "REFACTOR"
        print(f"{skill.name:20} {lines:4} lines  ->  {status}") from pathlib import Path

skills_dir = Path(".claude/skills")

def count_lines(p: Path) -> int:
    return sum(1 for _ in p.open("r", encoding="utf-8", errors="ignore"))

for skill in sorted(skills_dir.iterdir()):
    skill_md = skill / "SKILL.md"
    if skill_md.exists():
        lines = count_lines(skill_md)
        status = "OK" if lines <= 200 else "REFACTOR"
        print(f"{skill.name:20} {lines:4} lines  ->  {status}") If you run this weekly, you’ll catch “documentation creep” before it becomes a crisis. 7. Common Failure Modes (And How to Avoid Them) =============================================== Failure mode: Claude writes “a doc” instead of “a Skill” LLMs love expanding markdown into tutorials. Fix: explicitly tell it: this is not documentation
remove “beginner” filler
keep examples short, push detail into references explicitly tell it: this is not documentation this is not documentation remove “beginner” filler keep examples short, push detail into references Failure mode: Entry point bloats because the Skill scope is too wide Fix: split the Skill by workflow stage
or move decision trees into references split the Skill by workflow stage or move decision trees into references Failure mode: Too many references, still hard to navigate Fix: put a short “map” section in SKILL.md
keep reference files single-topic and named by intent, not by tool put a short “map” section in SKILL.md SKILL.md keep reference files single-topic and named by intent, not by tool 8. A Copyable Refactor Checklist ================================ Audit: list Skills + line counts, find any SKILL.md > 200 lines
Group by workflow: merge tool-specific Skills into capability Skills
Create references: move detailed info out of SKILL.md
Enforce entry constraints: keep SKILL.md lean and navigational
Cold start test: ensure first activation stays under your chosen budget
Keep scripts deterministic: offload “do the thing” to code where possible
Re-check monthly: Skills drift over time; treat them like code Audit: list Skills + line counts, find any SKILL.md > 200 lines Audit SKILL.md Group by workflow: merge tool-specific Skills into capability Skills Group by workflow Create references: move detailed info out of SKILL.md Create references SKILL.md Enforce entry constraints: keep SKILL.md lean and navigational Enforce entry constraints SKILL.md Cold start test: ensure first activation stays under your chosen budget Cold start test Keep scripts deterministic: offload “do the thing” to code where possible Keep scripts deterministic Re-check monthly: Skills drift over time; treat them like code Re-check monthly Final Take: Context Engineering Is “Right Info, Right Time” The big lesson isn’t “200 lines” or “three layers.” It’s this: Context is a budget. And the best Skill design spends it like an engineer, not like a librarian. Context is a budget. Don’t load everything. Load what matters — when it matters — and keep the rest one file away.

How to Build a Fast and Reliable Workflow: Refactoring Agent Skills

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

A Developer's Guide to Merging AI with the Spring Ecosystem

The Noonification: How Often Do NFTs Pass The Howey Test? (1/13/2023)

Darwin's Hybrid Intelligence to Align AI & Human Goals for Startups & VCs

The Noonification: White Man (11/26/2022)

The Noonification: The Metaverse is a Sh*tshow (11/2/2022)

100 Days of AI Day 1: From Newsletter to Podcast, Leveraging AI for Audio Transformation

A Developer's Guide to Merging AI with the Spring Ecosystem

The Noonification: How Often Do NFTs Pass The Howey Test? (1/13/2023)

Darwin's Hybrid Intelligence to Align AI & Human Goals for Startups & VCs

The Noonification: White Man (11/26/2022)

The Noonification: The Metaverse is a Sh*tshow (11/2/2022)

100 Days of AI Day 1: From Newsletter to Podcast, Leveraging AI for Audio Transformation

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps