Lean SKILL.md Refactor
Refactor bloated SKILL.md files into a precise trigger, a lean router, and lazy-loaded reference files without losing behavior.
Before & after
Same prompt, same agent — the only difference is the skill.
A 900-line skill file is likely too large to be effective. Here are some suggestions: - Break it into smaller, focused sections - Move detailed content into separate reference files - Keep the main file concise with the most important instructions - Use clear headings so content is easy to navigate Large context can dilute the model's attention, so trimming down to essentials often improves how well instructions are followed. You might also consider whether all 900 lines are necessary, or if some can be removed entirely. Would you like help restructuring it?
900 lines isn't a length problem, it's an architecture problem. Right
now all 900 load whenever the skill triggers — that's the "dump." The
fix is progressive disclosure: point, don't dump.
HOW LOADING ACTUALLY WORKS
Only the skill's name + description sit in context by default. The
skill.md BODY loads only after Claude decides the skill is relevant, and
listed reference files load only when actually needed. Your 900 lines
are paying the full cost on every trigger because everything is in the
body instead of behind a pointer.
THE REFACTOR
BEFORE
skill.md — 900 lines: front matter + process + 600 lines of
reference material (the 139 marketing ideas, the examples, the
tables) all inline.
AFTER
skill.md — ~60 lines: YAML front matter (name, description) + the
PROCESS only. "When asked for a marketing idea, read
reference/ideas.md and select by [criteria]."
reference/ideas.md — the 139 ideas, loaded only when that path runs.
reference/examples.md — the examples, same deal.
Same knowledge, a fraction of the always-loaded cost. The 139-idea
case is the canonical one: it fits under the character limit only
because the ideas live in a knowledge file the process points at.
WHY "IGNORES HALF OF IT" HAPPENS
It's not ignoring — it's diluting. 900 lines of mixed process and
reference means the actual instructions compete with reference data for
attention. Separate them and the process gets read every time; the
reference gets read when relevant.
THE RULE GOING FORWARD
skill.md body = process (what to do, in what order).
reference files = knowledge (facts, lists, examples, tables).
If a line is a fact rather than a step, it belongs behind a pointer.
Paste the front matter and I'll show you the ~60-line router version.About this skill
"My skill has become a wall of text, but cutting it down keeps breaking things." This skill separates activation, execution, and task-specific knowledge, then produces a lean router rewrite with lazy-loaded reference files and a checkable record of what moved, merged, or stayed.
What it does
- Rewrites trigger descriptions around actual user requests and clear scope boundaries.
- Separates essential workflow rules from catalogs, examples, and branch-specific knowledge.
- Restructures the skill into a lean router that points at lazy-loaded reference files.
- Preserves exceptions, prerequisites, and output requirements instead of deleting them as clutter.
- Supplies invocation cases that expose wrong activation, missing knowledge, and broken routes.
What you get
A replacement lean-router SKILL.md, the complete text of every reference file its routes point to, a concise preservation map, and targeted validation cases.
Best for
Skill builders whose instructions have accumulated long catalogs, repeated examples, overlapping workflows, or descriptions that activate for the wrong requests.
SKILL.md preview
---
name: lean-skill-md-refactor
description: Refactor bloated SKILL.md files into a lean router with lazy-loaded reference files by separating activation metadata, essential execution rules, and conditionally needed knowledge while preserving behavior. Use when the user says "my SKILL.md is too long", "make this skill a lean router", "split the knowledge from the workflow", "my skill keeps loading irrelevant examples", "this skill triggers on everything", "refactor this without losing instructions", or "audit this skill for progressive disclosure".
---
# Lean SKILL.md Refactor
… (sign up to view the full skill)More ai & agents skills
View all AI & Agents skills →Autonomous /goal Prompt Builder
Turn rough ideas into one paste-ready /goal prompt with clear scope, constraints, acceptance checks, and autonomy rules.
Autonomous Creative Build Goal Prompts
Turn a rough game, 3D site, or video idea into one build prompt with scoped autonomy, acceptance tests, and delivery criteria.
Claude Power-User Coaching: One Tip Per Turn
Spots the Claude features and prompt habits you're missing in your actual work and coaches one concrete, copyable fix at a time.
Claude Skill Build and Launch
Turn an idea into a complete Claude skill with scoped triggers, acceptance tests, installation steps, and an agent launch plan.