Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Full reference documentation (~2,500 tokens, ~90% functionality, LLM-estimated). This is the canonical source for all compressed variants.
Note: This reference document intentionally exceeds the 300-line MCE guideline.
As the canonical source for all compressed variants, comprehensiveness is prioritized
over brevity. For compact variants, see the main SKILL.md (~400 tokens, formula)
or compressed (~975 tokens, prose).
Agent Identity
Role: Help users compress verbose skills to reduce context window usage
Understands: Skills are verbose for human clarity but costly for context; compression is a trade-off
Approach: Identify section types, score importance, remove/shorten low-value sections
Boundaries: Preserve functionality, report what was removed, never hide trade-offs
Tone: Technical, precise, transparent about trade-offs
Data handling: This skill operates within your agent's trust boundary. All analysis uses your agent's configured model. No external APIs beyond your agent's LLM provider.
When to Use
Activate this skill when the user asks:
"Compress this skill"
"Make this skill smaller"
"Distill this skill to X tokens"
"What can I remove from this skill?"
"Reduce skill context usage"
Options
Flag
Default
Description
--mode
threshold
Compression mode: threshold, tokens, oneliner
--threshold
0.9
Functionality preservation target (0.0-1.0)
--tokens
-
Target token count (for tokens mode)
--provider
auto
LLM provider: auto, ollama, gemini, openai
--model
-
Specific model (e.g., llama3.2, gemini-2.0-flash)
--verbose
false
Show section-by-section analysis
--dry-run
false
Analyze without outputting compressed skill
--debug-stages
false
Show intermediate stage outputs
Provider auto-detection (in order):
Check ollama availability via ollama list
Check GEMINI_API_KEY environment variable
Check OPENAI_API_KEY environment variable
Error if none available
Process
1. Provider Detection
IF ollama available → use ollama (local, fast)
ELIF GEMINI_API_KEY set → use gemini
ELIF OPENAI_API_KEY set → use openai
ELSE → Error: "No LLM provider available. Run 'ollama serve' for local inference, or set GEMINI_API_KEY for cloud."
Analyze this section for compression. Classify phrases as:
- ESSENTIAL: Specific values, unique terms, key constraints, surprising info
- REDUNDANT: Could be inferred, restates earlier content, filler words
Section type: {type}
Content: {content}
Return JSON: {"essential": [...], "redundant": [...], "compression_potential": 0.0-1.0}
Pruning Rules:
Never prune ESSENTIAL tokens
Remove REDUNDANT phrases while preserving sentence structure
If >50% is REDUNDANT, consider removing entire section
Preserve specific values (numbers, thresholds, error codes)
Example:
Input: "The system will then proceed to process the input data and return the results"
Output: "process input data → return results"
Removed: "The system will then proceed to", "and"
4. Apply Compression
All modes use MetaGlyph native symbols (see §Symbol Reference below):
Replace "results in" → →
Replace "implies" → ⇒
Replace "for all" → ∀
Replace "not" → ¬
Threshold Mode (default):
Sort sections by importance (descending)
Include sections until functionality target reached
Apply symbol substitutions
Generate compressed markdown
Token-Target Mode:
Calculate minimum tokens (triggers + core)
If target < minimum: attempt LLM summarization
Add sections by importance until target
Apply symbol substitutions
One-Liner Mode:
Extract trigger conditions
Extract core action
Extract expected result
Format as 3-line summary with symbols
4.1. Example Compression (RECOMP)
For EXAMPLE sections, use extractive + abstractive compression:
Phase 1: Extractive Selection (preferred)
Score each example for pattern coverage, uniqueness, clarity
Select top 1-2 examples (keep full detail)
Compress remaining examples to one-liners (don't discard)
If coverage ≥ 0.8 → use selected + one-liners
Phase 1.5: One-Liner Compression (for non-selected examples)
Instead of discarding, compress to: {trigger} → {result}
Use MetaGlyph symbols
Preserves coverage, reduces tokens
Group under "### One-liners:" heading
Output structure:
### Full (selected):
[Detailed example with steps...]
### One-liners (compressed):-`--mode=tokens` → hard token limit
-`--verbose` → section-by-section analysis
Select the 1-2 BEST examples that cover the most patterns with minimum redundancy.
Examples:
{numbered_list}
Return JSON: {
"selected": [indices],
"coverage": 0.0-1.0,
"rationale": "..."
}
Synthesis Prompt (if coverage < 0.8):
Compress these examples into 1-2 summary examples.
Preserve: specific values, key patterns, expected outcomes.
Format: "When X → Do Y → Expect Z"
{examples}
Output shows:Examples: 5 → 2 full + 3 one-liners (extractive) or Examples: 5 → 1 (abstractive)
5. Measure Functionality
Evaluate by semantic understanding, NOT metrics.
Wrong (Metrics)
Right (Semantic)
"60% line reduction is too aggressive"
"Can an agent still execute this skill?"
"Token count exceeds target"
"Are all triggers and actions preserved?"
"Ratio doesn't match threshold"
"Would an agent behave the same way?"
LLM evaluates preservation by asking:
Can all original triggers still activate?
Are all core actions still specified?
Are critical constraints preserved?
Would an agent behave the same way?
Score 0-100 reflects semantic capability preservation, not line/token ratios. A skill compressed to 40% of original size can still preserve 95% functionality if the removed content was verbose explanation, redundant examples, or non-essential formatting.
6. Save Calibration
After compression, save entry to .learnings/skill-distiller/calibration.jsonl:
{"id":"c[N]","timestamp":"[ISO 8601]","skill":"[skill name from frontmatter]","mode":"[threshold|tokens|oneliner]","threshold":0.9,"input_tokens":1800,"output_tokens":1100,"reduction_pct":39,"sections_total":14,"sections_kept":9,"sections_removed":5,"classification_confidence_mean":0.90,"functionality_score":90,"protected_patterns_found":["n-count"],"protected_patterns_preserved":["n-count"],"advisory_patterns_found":[],"advisory_patterns_removed":[],"expected":{"functionality":90},"actual":null}
File rotation: If entries > 1000, truncate oldest 100 before appending.
Preserve X% of functionality, compress as much as possible.
/skill-distiller path/to/skill.md --threshold=0.9
Understanding thresholds: The threshold (0.9 = 90%) refers to semantic functionality, not token/line ratios.
Threshold
Meaning
NOT
0.95
95% of capabilities preserved
95% of lines kept
0.90
90% of semantic function
90% of tokens
0.80
80% of agent behavior
80% of bytes
A 0.9 threshold can result in 50%+ line reduction if the removed content was verbose examples, redundant explanations, or formatting. Judge quality by semantic analysis, not size ratios.
Why 0.9 default: Skill functionality is normally distributed across sections. Wide tails mean some "low importance" sections occasionally carry critical value for edge cases. At 0.9, you preserve more of the tail while still achieving meaningful compression.
Mode 2: Token Target
Compress to exact token budget.
/skill-distiller path/to/skill.md --tokens=500
Token estimation: Uses 4 chars/token heuristic. Accuracy: +/-20% vs actual provider tokenization. For precise limits, verify with provider's tokenizer.
Mode 3: One-Liner
Extreme compression for quick reference.
/skill-distiller path/to/skill.md --mode=oneliner
Produces 3-line summary: TRIGGER/ACTION/RESULT
Protected Patterns
These patterns must be preserved even if they look verbose:
Pattern
Why Protected
YAML name/description
REQUIRED by Agent Skills spec
Task creation
Compaction resilience
N-count tracking
Observation workflow
Checkpoint/state
State recovery
BEFORE/AFTER
Self-calibration
If a protected pattern is removed, the functionality score is penalized (-10% per pattern) and flagged explicitly in output.
Advisory Patterns
These patterns improve efficiency but aren't required:
Pattern
Impact if Removed
Parallel/serial decision
Suboptimal execution order
Performance hints
Slower but functional
Caching guidance
Works but inefficient
Advisory patterns removed are warned but don't penalize the functionality score.
Symbol Reference (MetaGlyph)
Native mathematical symbols LLMs understand from pre-training. Zero legend overhead.
Symbol
Replaces
Example
→
results in, leads to, produces
trigger → action
⇒
implies, therefore, thus
condition ⇒ behavior
∈
belongs to, is in, member of
value ∈ {a, b, c}
∀
for all, for every, for each
∀ files: validate
¬
not, doesn't, isn't
¬empty → process
∃
there exists, there is
∃ config → load
∧
and, also, plus
valid ∧ safe → proceed
∨
or, either
error ∨ timeout → retry
Application: Symbols replace verbose phrases in compressed output. No legend needed in output—LLMs comprehend natively.
Research: Based on MetaGlyph (arXiv:2601.07354) - 62-81% compression with native symbols.
Preserve original: Output to SKILL.compressed.md, never overwrite
Manual verification: Require human approval
Why 0.95 threshold: The distiller must remain fully functional to distill other skills. Capability loss compounds (0.95 x 0.95 = 0.90 at next level).
Enforcement: The 0.95 threshold is a documented guardrail, not an automated check. When compressing skill-distiller variants, manually verify you're using --threshold=0.95 or higher. The formula variant (SKILL.md) should never be the input for self-compression.
Error Handling
Error
Recovery Hint
No content
Provide a valid SKILL.md file path or pipe content via stdin
No frontmatter
Add --- block with name and description
No trigger section
Add '## When to Use' for best results
Token target impossible
Use --mode=oneliner for extreme compression
LLM unavailable
Run 'ollama serve' for local, or set GEMINI_API_KEY
