Claude Code Skills Deep Dive (8): From Loading to Compaction

TL;DR: A Skill has four easily confused states: its source on disk, candidate metadata, the rendered content produced by a particular invocation, and the copy preserved after compaction. Editing SKILL.md changes future discovery and invocation, not instructions already in the conversation. An inline Skill's body persists across turns, while its temporary tool approval does not. Compaction preserves recent invoked content within per-Skill and combined budgets; it does not reread the entire source.

Part 7: From Invocation to Safe Execution exposed one lifecycle split: Skill instructions may remain in context after the allowed-tools grant expires on the next user message.

That is not the only split. The common intuition that “the Skill is the SKILL.md file on disk” stops being useful once a session starts. At runtime, at least four objects matter.

Four states, four update events

A · Source file
    SKILL.md and supporting files on disk
        ↓ discovery
B · Candidate metadata
    name and description known in this session
        ↓ invocation and rendering
C · Rendered invocation
    body with arguments, variables, and dynamic context expanded
        ↓ conversation growth and compaction
D · Post-compaction preserved copy
    recent Skill content reattached within a budget

State	Created when	Updated by
Source	Skill is created or installed	Edits, plugin updates, version changes
Candidate listing	Session discovers it	Live detection, scope or visibility changes
Rendered invocation	User or Claude invokes it	New arguments, dynamic output, reinvocation
Post-compaction copy	Conversation compacts	Retention budget and recency of invocations

Without these names, phrases such as “the Skill was updated,” “the Skill is loaded,” and “the Skill is still active” are ambiguous.

Session startup: first comes a candidate index

In an ordinary Claude Code session, Skills available for model invocation contribute names and descriptions to the candidate listing. Claude knows what it might choose, but the full SKILL.md body has not entered the conversation. References, scripts, and assets do not load automatically either.

This is progressive disclosure's first level—and its fixed discovery cost. A user-only Skill need not advertise a full description for model matching. Visibility settings can also reduce an entry to name-only or hide it.

“Installed” means the source exists. “Listed as a candidate” means the current model has a chance to select it.

First invocation: rendered content enters the conversation

On activation, Claude Code reads the source, substitutes arguments, runs permitted dynamic context commands, and creates rendered content. The Claude Code documentation describes the result as a single message added to the conversation. It can influence later turns, not just the answer immediately following invocation:

Turn 1: /release-check
        → full instructions enter the messages

Turn 2: user adds “staging only”
        → earlier Skill instructions remain in history

Turn 3: Claude continues checking
        → the workflow need not be reread from disk

That enables multi-turn workflows. It also means each token in the main body is more than a one-time activation cost: later requests continue to carry it until the conversation is compacted or reset.

Instructions persist; temporary permissions do not

This is easy to misread:

Turn 1: /commit is invoked
        allowed-tools temporarily pre-approves Git commands

Turn 2: instructions still exist in context
        allowed-tools grant has cleared

Claude still knows the commit process, but a sensitive tool call may require approval again. The product has not “forgotten” the Skill. Knowledge and authorization intentionally have different lifetimes. If approval should last the session, use a session permission rule. If it should be granted again for just one turn, reinvoke the Skill.

Editing the source does not rewind conversation history

Claude Code detects edits to Skill definitions in watched locations. A changed SKILL.md can update the candidate description and future invocations. It does not search the message history for an earlier rendered copy and replace it:

T0: invoke Skill v1 → rendered v1 enters context
T1: edit disk source to v2 → source and candidate metadata update
T2: continue chatting → rendered v1 remains in the messages

History records what was actually loaded at the time. Silently rewriting it would break conversational continuity.

To use v2, invoke the Skill again, start a fresh session, or explicitly tell Claude that the new version supersedes earlier instructions. Live reload updates a definition; it is not a time machine.

Reinvocation compares rendered content

The same Skill can be called twice in one session. If the second rendered result is identical to a copy already in context, Claude Code adds a brief “already loaded” note instead of duplicating the full body. If the rendered result differs, it appends the new content.

Differences can come from changed arguments, dynamic shell output, an edited source file, or runtime variables. /fix-issue 123 and /fix-issue 456 are distinct rendered task inputs even though both use the same Skill name.

The practical deduplication key is the rendered content, not merely the Skill's name.

Dynamic context makes repeated calls naturally different

Suppose a Skill includes !git status --short``. The first invocation sees a clean workspace; the second sees five modified files. The source did not change, but the rendered body did.

Reinvocation can refresh a snapshot, and frequent reinvocation can also append repeated large outputs to context. Keep injected output compact and limited to state that actually affects the workflow.

Supporting resources have no special residency promise

If SKILL.md tells Claude to read a reference, that read becomes an ordinary tool result in the conversation. It follows normal message and compaction behavior simply because it was read; being inside a Skill directory does not grant it permanent residency.

Likewise, unread script source is not in context; a script's output enters as a tool result if executed; an asset enters history if read. Files remain on disk for later access. The folder is persistent source, while the conversation holds only the path through it actually taken this time.

Forked Skills live primarily in a child context

An inline Skill's rendered body enters the main conversation. With context: fork, the body is instead a subagent task in a separate context. The child carries the rendered Skill and its intermediate reads and tool results; the main conversation receives the returned findings rather than the entire child work history.

This is why forked Skills fit long, self-contained investigations, but not a reference that the main agent must keep following line by line. For that, use inline loading or return the necessary rules explicitly.

Compaction: a generic summary may lose the method

As a conversation grows, Claude Code compacts earlier history into a summary. If all the summary retained were “the user invoked release-check,” the name would survive but its steps, constraints, and resource navigation might not. Claude would struggle to continue the workflow.

Claude Code therefore reattaches content from invoked Skills after compaction. It does not reread every source file. It preserves recorded rendered invocations, subject to a budget:

`text
compact summary

• recovered project context
• preserved invoked-Skill content → post-compaction context `

That is stronger recovery than an arbitrary early chat message gets, but it is not unlimited.

Two retention budgets: 5K per Skill, 25K overall

The current documentation specifies:

• At most the first 5,000 tokens of each invoked Skill are reattached.
• Reattached Skills share a 25,000-token combined budget.
• The most recently invoked Skill gets space first.
• Older Skills may be dropped entirely when many have been invoked.

`text
Most recent
Skill E 5K
Skill D 5K
Skill C 5K
Skill B 5K
Skill A 5K
── 25K total
Older Skills may not be reattached
`

Three implications follow. A SKILL.md longer than 5K tokens may lose its tail after compaction. Many active Skills can crowd older ones out. Critical constraints placed at the end are more likely to disappear than those near the top. This is a design reason to keep the main body concise and put essential rules first.

Compaction preserves the invoked snapshot, not the latest source

Consider:

`text
T0: invoke v1
T1: edit source to v2
T2: compact the conversation
`

Compaction should preserve the rendered v1 that the conversation actually used, rather than silently rewriting past constraints with v2. Source defines future invocations; the invocation record tells us what was loaded then; preservation carries that record forward.

If the user wants v2 after compaction, invoke v2. Do not treat an edit on disk as a hot replacement for active instructions.

The candidate listing has a budget too

Compaction limits invoked bodies. Startup discovery has another budget: the Skill listing. Claude Code scales its character budget to 1% of the model context window. When the list overflows, names remain, but descriptions for less-used Skills can be dropped. /context and /doctor help inspect this cost.

Installing 500 Skills does not yield 500 equally well-described automatic matches. Disk capacity is not the bottleneck; metadata visibility is.

The skillOverrides setting offers four useful states:

Setting	Listed to Claude	User / menu
on	Name and description	Shown
name-only	Name only	Shown
user-invocable-only	Hidden	Shown
off	Hidden	Hidden

This lets users reduce noise from a shared project Skill without modifying the repository's SKILL.md.

A new conversation keeps the source, not the invocation

The Skill folder persists on disk; the rendered invocation belongs to a conversation. After /clear or a fresh session, the source still exists and can be discovered again, but yesterday's loaded instructions do not automatically remain active. The Skill must be invoked when relevant to the new task.

This differs from memory. Memory preserves background across sessions; a Skill stores a reusable method. Its source survives, but “we were at step four of this release yesterday” should not become part of the Skill definition. Resume the session or keep a task handoff record instead.

The lifecycle in one picture

`text
Install or create on disk
SKILL.md + resources
↓
Session discovery
name + description listing
↓ match
Invocation
arguments + variables + dynamic context
↓
Rendered content
one inline instruction message, or a forked subagent task
↓
Later turns
instructions persist; temporary permission grant expires
↓
Compaction
up to 5K each, 25K total, recent first
↓
New session
source rediscovered; invocation must happen again
`

A Skill is not a file continuously mirrored into context. Source determines how future calls render; rendered content records what this call actually loaded; compaction carries that snapshot forward only within its budget.

Up next

Once a Skill matures in a personal folder, it may move into a project and later a plugin or marketplace. Copying files distributes content but does not solve namespaces, versions, dependencies, or cross-surface differences. Part 9 follows a capability from a local experiment to an installable component.

References

• Claude Code documentation: Skill content lifecycle, visibility, and listing budget
• Agent Skills specification: Progressive disclosure
• Previous article: From Invocation to Safe Execution
• Related future reading: the Claude Code Context Management series on compaction, and the Claude Code Memory series on what returns after compaction.