How I compress agent skills with progressive disclosure

While using LLMs to write skills for a personal project, I noticed the instructions kept getting more detailed. When the environment changed, the agent sometimes stopped because the instructions described the setup too closely.

I created /compress-skill to review those instructions and organize them with progressive disclosure. The workflow audits the original, cuts duplication from a copy, and moves detailed instructions into references.

I want the skill to explain the required outcome without making every execution choice for the agent. When correctness depends on a specific sequence, that sequence stays.

Both commands install /compress-skill from my dotfiles repository.

Choose the command for your platform. The installer detects your coding agents and leaves existing agent instructions and terminal settings unchanged.

macOS or Linux:

curl -fsSL https://r1cco.com/skills/compress-skill | bash

Windows with PowerShell 7:

irm https://r1cco.com/skills/compress-skill.ps1 | iex

Then ask your coding agent to use /compress-skill on the skill directory you want to review.

By default, it prepares a proposal and report. Ask it to apply the changes when you're ready.

Audit assumptions before cutting

The first pass checks whether the instructions fit the target model and repository. A short instruction can still depend on a condition the agent cannot establish.

In one historical change, a batching rule depended on an undefined runtime setting when the skill ran alone. The replacement checked whether the harness could create a worker.

Here are the changed lines:

Source: https://github.com/rafaeelricco/job-kit-ai/commit/a57db7021f96f6462c502bfc765f0027c62192c5

The batching policy stayed explicit. The condition became one the current environment could satisfy or reject.

This corrects an assumption, but the diff does not establish how every model behaved before or after it.

The audit also checks for contradictions between files. A conflicting or uncertain rule needs evidence and review before removal.

Cut duplication without losing rules

After the audit, I remove redundant text. I justify each cut by what it removes, rather than by a target word count.

A scoring contract explained how to represent missing evidence, then repeated the rule below the scoring table.

The revised contract keeps this instruction in its main definition:

Cells are integers, or `—` for a factor with no evidence; never `0` for unknown.

The repeated sentence was removed:

Source: https://github.com/rafaeelricco/job-kit-ai/commit/2f793d4c19546636dc491c60d416028e77d25ed7

Unknown still means unknown. The rule stays in one place, so future changes have one authoritative instruction to update.

I preserve the triggers, behavioral constraints, and output requirements. I keep the reasons for important rules so the agent knows when a restriction applies.

Route detailed flows to references

The router pass reorganizes the shortened copy. It keeps the entry focused on the skill's purpose and the path into its workflow, and moves detailed procedures into references.

Anthropic describes progressive disclosure as loading skill information in stages. Metadata helps the agent select a skill, the entry file provides instructions, and additional references supply details as needed.

Splitting files alone does not reduce the context a task loads. If the entry immediately loads every reference, the agent still reads everything.

My flow-led structure is a design choice. Anthropic's authoring guidance recommends keeping references directly accessible from the entry file and avoiding deep chains.

I want the agent to find relevant instructions before it needs to act.

This change moved a reader skill's run steps out of its entry:

The new flow retained instructions about missing directories and read-only behavior:

Source: https://github.com/rafaeelricco/job-kit-ai/commit/ef433a3330217e6fd5822067af0ce99d93960bd4

The entry loads that flow immediately. This makes the entry easier to navigate, but it does not prove that a run loaded fewer tokens.

Progressive disclosure depends on the remaining routes: the agent should read additional references when the action needs them. Permissions and stopping conditions must reach the agent before the relevant action.

Compare behavior before and after

By default, the workflow runs audit, cut, and router in that order. Cut and router use one copy, then compare the final copy with the original.

For behavior checks, I send the same requests to both versions and compare expected results. The wording can differ; the constraints and required outputs should match.

Python tests add structural checks. They cannot show that an agent follows every instruction during a real task.

If an agent comparison cannot run, comparing the file trees gives narrower evidence. The report should say what was checked.

Different models may need different amounts of guidance. I test the models I intend to use because one successful comparison does not establish how every model will behave.

The final report records what was cut or moved, what stayed deliberately, and which checks were performed. Word counts describe the edit; they do not prove equivalent behavior or measured token savings.

The goal is a smaller skill with clear requirements and references the agent can find when needed. The comparison checks whether the task still gets done.

Read the skill

• https://github.com/rafaeelricco/dotfiles/blob/main/skill/compress-skill/SKILL.md
• https://github.com/rafaeelricco/dotfiles/blob/main/skill/compress-skill/references/flow-audit.md
• https://github.com/rafaeelricco/dotfiles/blob/main/skill/compress-skill/references/flow-cut.md
• https://github.com/rafaeelricco/dotfiles/blob/main/skill/compress-skill/references/flow-router.md