Your skill stops working in long sessions

What actually happens at compaction

When a session grows long enough, Claude Code summarises the conversation to make room. Most of what loaded at startup comes back: the project-root CLAUDE.md and unscoped rules are re-read from disk, auto memory is re-read, the system prompt still applies.

Invoked skills come back too, but not intact. Anthropic's documentation states the limits plainly: skill bodies are re-injected capped at 5,000 tokens per skill and 25,000 tokens total, with the oldest invoked skills dropped first.

Source: code.claude.com/docs/en/context-window, section "What survives compaction". Checked 2026-09-20.

The part that decides how you write the file

Truncation is not random and it is not from the middle. The documentation says it directly: "Truncation keeps the start of the file, so put the most important instructions near the top of SKILL.md."

So a long skill does not degrade evenly. It loses its tail. And the tail is where most people put the things they wrote last: the exit criteria, the anti-patterns, the one rule that prevents the expensive mistake. Those are the first to go, in the session where they matter most.

Read that sentence again with a stopwatch on it. Your skill has its most important instruction for the easy first half of a long session, and does not have it for the hard second half.

The skill listing does not come back at all

A second limit sits next to the first. The startup listing of available skills -- the one-line descriptions that let the model know what it can reach for -- is not re-injected after compaction. Only skills that were actually invoked are preserved.

The practical effect: a skill the model has not yet used stops being visible to it in a long session. If a skill is going to matter, invoking it early is worth more than hoping its description fires late.

What to do about it, in order

1. Move the load-bearing rule to the top. Lead with the rule, then the procedure, then the background. If the file reads better the other way round, write it the other way round and then move the rule anyway.
2. Measure the file. 5,000 tokens is roughly 3,500-4,000 words. If your SKILL.md is past that, some of it is decorative in every long session whether you like it or not.
3. Split rather than reorder twice. A skill that needs its tail is two skills. One skill, one job, is a context rule before it is a style preference.
4. Count your invoked skills. The 25,000-token total is shared. Five invoked skills at 5,000 each fill it exactly, and the sixth pushes the first one out.
5. For anything with side effects, set disable-model-invocation: true. That keeps the skill out of context entirely -- it is not even in the startup listing -- until a person invokes it by name. It costs zero until the moment you want it.

What this is not

This is not the model ignoring instructions, and no amount of stronger wording fixes it. The sentence is gone from the context window. Rewriting it in capitals at the bottom of the file produces a more emphatic sentence in the same place, which is to say nowhere.

Where this came from

This page is one section of skill-authoring, one of the Agent Skills in this set. The skills are plain SKILL.md markdown -- no install, no runtime, no dependency. Drop a folder into ~/.claude/skills/ and invoke it by name.

Four of them are free and need no signup: github.com/resilientmindset01-commits/claude-code-skills-free

Written by ResilientMindset. Not affiliated with, endorsed by, or sponsored by Anthropic. Every claim about Claude Code on this page was checked against Anthropic's own documentation on the date shown.