Point-Don't-Dump Skill Refactor
Restructure any bloated skill.md into a lean YAML front matter router that points at reference files, so Claude loads knowledge only when needed.
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
name: point-dont-dump-skill-refactor description: Restructure any bloated skill.md into a lean YAML front matter router that points at reference files, so Claude loads knowledge only when needed.
Point-Don't-Dump Skill Refactor
What This Does
The creator explains progressive disclosure: only the skill name and description sit in context until Claude decides the skill is relevant, then it lazy-loads the skill.md body and any listed reference files. He shows how a 139-marketing-idea skill fits under the character limit by keeping ideas in a knowledge base MD file and having the process file just point at it.
What You Get
- Lean YAML front matter with name and description
- process-only skill.md body
- separated reference MD files for knowledge
- per-task conditional file loading
- character-limit-aware structure
Customize
- skill_name: the routable name
- trigger_description: exact phrases that activate the skill
- reference_files: list of knowledge MD files to lazy-load
- process_steps: high-level ordered steps only
- scripts_dir: optional executable scripts
Sample Output
The marketing-ideas skill keeps 139 tactics in a separate knowledge base file so the skill.md fits in context and only loads the relevant category on demand.
Target Audience
Skill builders whose skill.md files have grown past useful size
SKILL.md preview
---
name: point-dont-dump-skill-refactor
description: Use this skill when a SKILL.md file has grown too large and needs restructuring into a lean router that points at lazy-loaded reference files.
version: 1.0.0
category: Technical/Coding
author: AgentVolt
license: proprietary
tags:
- technical
- coding
- standard
---
# Point-Don't-Dump Skill Refactor
Restructures a bloated SKILL.md into a lean router: only the name and description sit in context by default, with content lazy-loaded on invocation.
## When to use
… (sign up to view the full skill)More development skills
View all Development skills →Multi-Instance Terminal Cowork Juggle
Run several Claude Code instances in iTerm tabs and juggle between them like a Starcraft player: plan on one, execute on another, remote SSH on a third.
Cowork Permissions Settings Wizard
Ask Claude to add the common safe permissions to settings.json (read, tests, git ops, dev server) and gate the risky stuff (installs, deletes, network calls).
Validation-Loop CLAUDE.md Auto-Learner
Any time Claude Code messes up on your codebase, ask it to fix the mistake and then update CLAUDE.md so it never does that again, without editing rules by hand.
Business Automation Stack
A connected set of agents that handle the repetitive ops work — follow-ups, summaries, and handoffs.