| name | compress-onboarding |
| description | 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. |
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 <file> [--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. Only for repos
pressed against the 32 KiB Codex cap; 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, <!-- aiboarding-* --> 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.
Auto-clarity exemptions
Never compress below full sentences, regardless of level:
Agent Guardrails and Escalation - Ask the User When sections: cap at lite.
A misread guardrail costs more than its tokens.- Security warnings and destructive/irreversible-action instructions.
- Multi-step sequences where fragment order creates ambiguity ("migrate table drop
column backup first" - unclear; keep explicit ordering words).
Procedure
- Snapshot. Copy the target file to a temp path (
before).
- Compress section by section at the resolved level, honoring the invariants
and exemptions above.
- Verify. Run
.aiboarding/tools/check-preservation <before> <after> (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.
- Approval gate. Show the user a diff of the compressed file against the
original. Write only after approval.
- 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):
{ "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, "measured_at": "2026-07-02" }
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.
- Size check. Run
.aiboarding/tools/check-size-budget <file>; if it 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.
