Nestor G Pestelos Jr · Writing

Deleting 24K Lines of AI Instructions

Published March 17, 2026

The Bloat Problem

After 2,400+ sessions with Claude Code, I had 257 skills guiding the agent across everything from Rails security patterns to Readwise document synthesis to weekly life reviews. They worked. But they'd grown organically, each skill accumulating sections every time I hit a new edge case.

The average skill was 167 lines. Some hit 800+. Every time Claude activated a skill, it loaded the entire thing into its context window. A skill with 40 lines of methodology buried under 90 lines of examples, 30 lines of "when to use" documentation, and 15 lines of cross-references was diluting the signal.

I knew this because I'd built a usage tracker. It showed invocation counts, and the correlation was clear: the longest skills weren't the most-used. Many had never been invoked at all.

The Five-Step Algorithm

Elon Musk's manufacturing optimization framework, adapted:

1. Question every requirement. Does this section need to exist? Who requested it? (Usually past-me, solving a problem I no longer have.)
2. Delete. Remove everything that doesn't directly serve the skill's trigger scenario. Be aggressive. You can always add it back (you won't).
3. Optimize. Make what remains more efficient. Tables instead of prose. Merged rules instead of separate sections.
4. Accelerate. Make it faster to activate and parse. Shorter frontmatter descriptions, fewer code blocks.
5. Automate. Only after steps 1-4. For skills, this means: does the skill now trigger reliably without manual invocation?

Most people start at step 3 or 4, optimizing something that shouldn't exist.

What Got Deleted

After 29 batches (6 skills per batch, read in parallel, write in parallel, commit), clear patterns emerged in what was consistently deletable:

Always delete:

• ## When to Use sections. Duplicates the frontmatter description, which is what the agent actually reads for activation.
• ## Purpose blockquotes. Restates the heading in different words.
• ## Key Takeaway sections. Restates the methodology in fewer words. (If your methodology needs a summary, the methodology is too long.)
• ## Integration / ## Related Skills. Wiki-links the agent never follows during execution.
• Wrong/Right dialogue examples. Verbose "DON'T do this / DO this" patterns that triple the line count while adding one bit of information.
• ## Quick Decision Tree. Flowcharts that duplicate the methodology steps.
• ## Common Mistakes, when they overlap with the methodology. If step 3 says "always use git mv," you don't need a mistakes section saying "don't use mv."

Never delete:

• Core methodology/workflow steps. This IS the skill.
• Code examples in code-heavy skills (security patterns, MCP integration). The code IS the reference.
• Decision frameworks and threshold tables. Operational data the agent uses at runtime.
• Verification checklists. The agent actually executes these.

Judgment calls:

• Examples: keep one if it clarifies an ambiguous step, delete if it just illustrates something obvious
• Principles: merge into key rules if they're actionable, delete if they're philosophical
• Origin/history: condense to one line with a date. Future-me needs the "when" and "why," not the narrative.

The Results

| Metric | Before | After | Change | |--------|--------|-------|--------| | Total skills | 257 | 257 | 0 | | Total lines | ~43,000 | ~19,000 | -56% | | Average lines/skill | 167 | 74 | -56% | | Largest skill | 821 lines | 320 lines | -61% | | Skills over 500 lines | 12 | 0 | -100% |

The optimization was not uniform. Code-heavy reference skills (security patterns, macOS MCP integration, AppleScript patterns) got conservative 15-20% reductions. Their code blocks are the value. Methodology-heavy skills (synthesis workflows, audit procedures, career frameworks) got aggressive 60-70% reductions. Their value is in the steps, not the prose around the steps.

Observations

The agent doesn't need motivation. Half the deleted content was persuasive writing explaining why a pattern matters, when it applies, what happens if you skip it. Humans need that context. Agents don't.

Frontmatter is the actual trigger. The description field in YAML frontmatter determines whether a skill activates. A 20-line "When to Use" section inside the skill body is invisible to the activation logic. I was writing documentation the agent never read at the decision point that matters.

Tables beat prose for decision logic. A 12-line paragraph explaining four severity thresholds becomes a 6-line table.

Batch processing prevents preciousness. Six skills in parallel, edit, commit. By batch 22 of 29, you develop a ruthless eye for filler.

The 300-line budget is generous. The Agent Skills spec recommends under 500 lines. After optimization, my most complex skills sit around 100-130 lines. The constraint I needed was closer to 150.

Less Skill, Better Execution

Karpathy's autoresearch result points the same direction. His single-agent, single-file, single-metric loop outperformed the 8-agent research organization. My 74-line average skill outperforms the 167-line version.

Most of what we write for AI agents is for ourselves. The documentation, the examples, the principles sections. They make us feel like the skill is comprehensive. Delete them first.