# Compress Onboarding > Use to compress any agent-instruction file (AGENTS.md, CLAUDE.md, .claude/rules/*.md, legacy AIBOARDING.md) into terse, high-signal prose without altering commands, code, URLs, or paths. Standalone compression engine with levels (off/lite/full/ultra), byte-preservation verification, and token receipts. Also invoked by the create/update onboarding skills. - Skill: `gustavo-meilus/compress-onboarding` (Agent Skill) - Install (CLI): `npx skillmds@latest add gustavo-meilus/compress-onboarding` - Raw SKILL.md: https://api.skillmd.com/api/skills/gustavo-meilus/compress-onboarding/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: gustavo-meilus (https://skillmd.com/u/gustavo-meilus) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/gustavo-meilus/compress-onboarding --- # Compressing onboarding files Instruction files load **every session**, so every saved token compounds. Compress prose aggressively while never touching the technical payload - and never trading away clarity where ambiguity is dangerous. **Announce at start:** "Using compress-onboarding on at level ." **Usage:** `compress-onboarding [--level off|lite|full|ultra]` Default file: the repo's `AGENTS.md`. Works under any SKILL.md-compatible runtime. ## Levels (sticky per repo) Resolve the level from `--level` if given, else `.aiboarding/config.json: compression_level`, else `full`. When `--level` is given, persist it back to `config.json` - the level is a per-repo decision, not per-run. - **`off`** - no rewriting. Still run the size report (step 5) so bloat is visible. - **`lite`** - remove filler, pleasantries, hedging, and restatement. Full sentences kept. ("In order to build the project, you should run…" → "To build, run…") - **`full`** (default) - additionally drop articles, compress to fragments and short synonyms, allow `X → Y` notation. ("The dev server can be started with `npm run dev`" → "Dev server: `npm run dev`.") - **`ultra`** - telegraphic; every non-load-bearing word goes. Use only when the effective instruction-chain audit needs it; confirm with the user before first use. ## Byte-preservation invariants (hard guarantees) Compression must NEVER alter: fenced code blocks (including the fence lines), inline backtick spans, shell commands, URLs, file paths, identifiers and symbol names, quoted error strings, `` markers, YAML frontmatter, and table structure. If a protected span is wrong, fixing it is an *update*, not a compression - route it through `update-agent-onboarding`. While rewriting, keep commands/identifiers/paths/error strings backtick-quoted (add backticks where the source lacks them - adding protection is allowed; removing it is not). The checker treats backtick spans as protected. ## High-consequence preservation Before rewriting, classify complete high-consequence regions. Preserve every identified region verbatim, byte-for-byte, by default. `full` or `ultra` never authorize rewriting one. Always classify complete `Agent Guardrails` and `Escalation - Ask the User When` sections. Outside those headings, classify smallest complete paragraph, list item, warning, or ordered procedure needed to retain context when it governs security, authorization, approval or escalation, destructive or irreversible actions, or required ordering or prerequisites for destructive or migration work. Record each region's source section or line location and category. Do not classify ordinary project purpose, architecture, domain, or routine descriptive prose solely because it is important or technical; compress that prose at selected level. If user asks to rewrite identified high-consequence content, name affected regions and obtain explicit opt-in for selected regions in current operation. Level choice and final diff approval do not count. Do not persist consent. Rewrite only selected regions, retain unselected regions verbatim, preserve all protected spans, and keep behavioral force unambiguous. Then show final diff and obtain normal approval. ## Procedure 1. **Snapshot.** Copy the target file to a temp path (`before`). 2. **Classify and compress.** Identify high-consequence regions, report their locations and categories, and copy them verbatim unless current-operation, per-region explicit opt-in permits rewriting. Compress remaining prose at resolved level. 3. **Verify.** Run `.aiboarding/tools/check-preservation ` (fall back to the plugin's `templates/tools/check-preservation` if not installed). Fix every reported span and re-run until clean. Never hand-wave this step. 4. **Approval gate.** Show the user a diff of the compressed file against the original. Write only after approval. 5. **Receipt.** Measure before/after: exact bytes and lines always; token counts with a real tokenizer if one is available in the environment (e.g. Python `tiktoken`), otherwise `tokens_approx = bytes / 4`, explicitly labeled approximate. Append to `.aiboarding/state.json:receipts` (one object per line, keeping the file hook-readable): ```json { "file": "AGENTS.md", "level": "full", "bytes_before": 8123, "bytes_after": 4310, "lines_before": 190, "lines_after": 121, "tokens_before_approx": 2031, "tokens_after_approx": 1078, "high_consequence_regions": [{ "location": "Agent Guardrails", "category": "guardrails", "outcome": "preserved", "explicit_opt_in": false }], "measured_at": "2026-07-02" } ``` `high_consequence_regions` is optional for backward compatibility. Each entry records location, category, outcome (`preserved` or `rewritten`), and explicit opt-in status; never copy instruction text. Include `[]` when classification verified no such regions. Report same evidence to user. Report the saving to the user; since the file loads every session, note the per-session saving - never claim unlabeled exact token numbers without a real tokenizer. Also write a compact `compression-verification` record with the subject, level, measurements, preservation and size outcomes through `write-evidence`. Keep the legacy receipt unchanged; a failed preservation or size check is recorded when possible and never authorizes a sync-pointer advance. 6. **Size check.** Run `.aiboarding/tools/check-size-budget ` as a local sensor. It does not prove chain safety; run `.aiboarding/tools/audit-onboarding-evidence ` before claiming an effective Codex chain fits. If local guidance still WARNs after `full`, suggest moving detail to `.claude/rules/` or nested `AGENTS.md` files rather than jumping to `ultra`. ## Writing into shared files When compression output must land inside a file that also has user-owned content (e.g. a hand-written `CLAUDE.md`), write only within the aiboarding marker fence via `.aiboarding/tools/inject-fenced` - re-runs stay idempotent and uninstall stays clean.