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.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- 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.
03 SKILL.md 正文
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 <file> at level <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, allowX → Ynotation. ("The dev server can be started withnpm 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, <!-- 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.
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
- Snapshot. Copy the target file to a temp path (
before). - 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.
- Verify. Run
.aiboarding/tools/check-preservation <before> <after>(fall back to the plugin'stemplates/tools/check-preservationif 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), otherwisetokens_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, "high_consequence_regions": [{ "location": "Agent Guardrails", "category": "guardrails", "outcome": "preserved", "explicit_opt_in": false }], "measured_at": "2026-07-02" }high_consequence_regionsis optional for backward compatibility. Each entry records location, category, outcome (preservedorrewritten), 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 compactcompression-verificationrecord with the subject, level, measurements, preservation and size outcomes throughwrite-evidence. Keep the legacy receipt unchanged; a failed preservation or size check is recorded when possible and never authorizes a sync-pointer advance. - Size check. Run
.aiboarding/tools/check-size-budget <file>as a local sensor. It does not prove chain safety; run.aiboarding/tools/audit-onboarding-evidence <repo-root>before claiming an effective Codex chain fits. If local guidance still WARNs afterfull, suggest moving detail to.claude/rules/or nestedAGENTS.mdfiles rather than jumping toultra.
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.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.