- Python 89.9%
- Rust 6.4%
- Shell 3.5%
- jq 0.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| clean-status-bar | ||
| docs | ||
| kit | ||
| skills | ||
| src | ||
| tests | ||
| tools | ||
| .gitignore | ||
| build.rs | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CHANGELOG.md | ||
| LICENSE | ||
| README.md | ||
clean-skills
Agent Skills for evidence-driven engineering, clear technical explanations, short explainer videos and clean personal writing. They are portable across Claude Code and Codex, and work with any host that reads the Agent Skills format.
| Skill | Use it when |
|---|---|
clean-api-docs |
An answer or change depends on the current, version-specific behaviour of a library, framework, SDK, CLI or hosted API. It resolves the version the project actually uses, reads the installed code and then that version's official docs, stops early and labels the source |
clean-debate |
You want several strong models to work out a task independently and correct each other, then hand a qualified contract to a capable (not necessarily the strongest) executor. Fits feature work, migrations, decisions and documents |
clean-explanation |
You want to understand a concept, result or system at your level, using text, an example or a richer artifact when it helps. Preserves qualifications, checks artifacts with the available tools and reports what remains unchecked |
clean-refactoring |
A large application should be rebuilt from first principles instead of refactored in place |
clean-video |
You want a short video (about 30 seconds to 3 minutes) that explains one idea clearly, in English or Chinese, narrated by a local text-to-speech voice. Writes the script for the ear, times the diagrams to the narration, makes captions from the script, renders locally, checks every beat's frame, loudness and captions, and never narrates a published video with a voice whose licence forbids it |
clean-writing |
You want your own notes, diary entries or blog posts cleaned up, fact-checked, drafted in your style and published with their photos and files, in English, Chinese or both, from text, voice transcripts or screenshots. Keeps your words, meaning and certainty at a declared edit level, reports every change and correction with its source, uses your settled layout and publishes only when you confirm |
The idea
For clean-debate and clean-refactoring, the strongest reasoning goes into the contract, cheaper execution goes into the
work, and a fail-closed gate decides what is done. Agreement between models is
not evidence. A plan is good enough to delegate when its acceptance checks are
qualified:
- Every mandatory check accepts a bound known-good specimen and genuinely rejects a bound defective one.
- Every declared mutant is killed.
- Selected probes have resolved receipts.
The probes include two kinds:
- an interpretation probe, where independent interpreters predict observable outcomes;
- an adversarial probe, a lazy-compliance attempt that counts as a bypass only when it demonstrably violates a requirement.
Those two skills share one verification kit (kit/scripts/cr.py, Python 3.9+ standard
library). It binds evidence to exact tree, suite and dependency digests. It enforces:
- verifier-only runners, repetitions (pass^k), flaky-history rejection, a holdout, suite locks and reviews with veto;
- prerequisite receipts and the control matrix.
Missing, stale, skipped, crashed or builder-produced evidence fails. The kit's self-test runs 113 end-to-end negative controls.
What the kit does not claim (see "Known limits" in the kit reference):
- runner and reviewer identities are labels, not authentication;
- a passing gate proves conformance to the contract in a stated environment, not that defects are absent;
- the qualification probes are bounded diagnostics, not certificates.
Install
The 0.6.1 crate bundles six skills: clean-api-docs, clean-debate,
clean-explanation, clean-refactoring, clean-video and clean-writing. A plain
install adds all six.
Python 3.9+ is needed for the helper, the writing and video scripts and the verification kit; the explanation skill's
text path needs no tools. Install with Rust's cargo:
cargo install --locked clean-skills
clean-skills install --host codex # dry run: shows what it would write to ~/.agents/skills
clean-skills install --host codex --apply
clean-skills install --host claude --apply # writes to ~/.claude/skills
clean-skills copies the skills bundled in its release and leaves a marker in each
folder it writes, then prints the command that runs the kit's self-test from the
installed copy. Re-running it upgrades a copy only while that copy is unchanged since
install. An edited, extra or missing file, an unmarked folder or a symlink is reported
as a conflict and left alone. clean-skills uninstall --host <host> --apply removes
only its own unchanged copies. --dir PATH targets another folder, such as a
project's .claude/skills. If ~/.claude or its skills folder is a symlink (a
dotfiles setup, say), it works in the real folder the link points to.
From a checkout instead, linking the skills to the repository:
git clone https://x.vibewait.ing/x/clean-skills.git
cd clean-skills
tools/install.sh --host codex # dry run: shows the links it would create in ~/.agents/skills
tools/install.sh --host codex --apply
tools/install.sh --host claude --apply # links into ~/.claude/skills
That installer only creates and removes its own symlinks. Neither installer
overwrites anything else, and neither edits hooks, permissions or settings. Invoke a skill
with /clean-debate in Claude Code, or $clean-debate
in Codex. Then check the kit from the checkout:
python3 skills/clean-debate/scripts/cr.py selftest
Layout
kit/ single source (kit/SKILLS lists the skills that receive a copy): scripts/ (cr.py, crkit/, stop_gate.py, tests/), shared references and templates, VERSION
skills/ self-contained skills (clean-api-docs, clean-debate, clean-explanation, clean-refactoring, clean-video, clean-writing); the two listed in kit/SKILLS get a generated kit copy (scripts/KIT_VERSION records the kit digest)
src/ the clean-skills installer crate (embeds skills/ at build time; see build.rs)
tools/ sync-kit.sh (generate copies; --check detects drift), assemble.sh (dist/), install.sh, check.sh
docs/ design records, research and validation evidence
clean-status-bar/ the Claude Code status line (statusline.sh, statusline.jq), its installer and tests; not in the crate
Edit the kit only under kit/, then run tools/sync-kit.sh. Before publishing, run
tools/check.sh. It:
- assembles
dist/; - runs the kit self-test and template manifest check on every skill listed in
kit/SKILLS, unit tests on every skill that has them, and skill validation on all; - runs lint and a publication scan;
- runs negative controls against the tooling itself: the drift check, an unlisted skill surviving the kit sync, symlinks in the kit source and copies, the publication scan, the installer and the gate;
- runs
cargo fmt,clippyand the installer's tests, then builds the packaged crate, checks it shipsskills/byte for byte, installs from it into a scratch home, runs the kit self-test there and uninstalls.
A missing required tool makes the result INCOMPLETE, never a pass.
Status
clean-video1.0.0. Makes short explainer videos: a script written for the ear, local narration (Kokoro for English, Qwen3-TTS for Mandarin, as tested), diagrams timed to each line, captions from the script's exact text, a local render (HyperFrames by default) and checks of frames, loudness and captions. Three standard-library scripts assemble the narration and captions and check the finished file. Its content rules areclean-explanation's. See the design and evaluation record.clean-writing1.0.0. Cleans, drafts and publishes the user's own writing using local style, destination and language settings kept outside the skill folder. Light edits keep the author's words; drafts never invent the author's experiences; facts and references are checked against opened sources; attachments are stripped of metadata; two standard-library scripts list every change and every piece of metadata a file would publish. It shares its plain-language principles withclean-explanation. See the design and evaluation record.clean-explanation1.1.0. A lightweight, independent skill inspired by Karpathy's explanation post. It selects the smallest useful medium, respects requested formats and depth, and separates structural checks from observed artifact behavior. Its original STE-inspired guidance does not claim ASD-STE100 compliance. See the design and evaluation cases.clean-api-docs1.2.0. Its helper reads local files only and never uses the network.- 1.2.0 lets a web search that a user or project instruction allows find the official page for the resolved version. A search result is never evidence; only the page it leads to counts. It was checked on one scenario against 1.1.0, not on the frozen eval.
- 1.1.0 puts version-pinned official sources before a local doc index, which is now a fallback. That order was decided on freshness and has not been measured; the numbers below are for 1.0.0.
- Designed and built with
clean-debate(two vendors' sealed briefs, a verifier, cheaper executors, four audits); see the design record. - 1.0.0 was measured against the previous skill on a frozen 12-item eval, run twice per arm: equal accuracy (23/24 each), 1.15x total tokens (+3.5% uncached) and equal safety flags. That failed the pre-registered token gate, and it was published on an explicit decision with these numbers. See the validation record for what the sample can and cannot show.
clean-refactoring2.1.0.- Kit 2.0 was reviewed in three cross-model cycles.
- Kit 2.1 was reviewed in further independent rounds; every finding became a regression scenario or a tooling control. See the validation record.
- A fresh agent's documentation smoke test passed end to end.
- Mutation testing caught every deliberate gate break.
clean-debate2.1.0 (nameddeliberate-delegate-verifyuntil 2.0.0). The design was settled with an external reviewer model after three cycles (seedocs/clean-debate/). It was dogfooded end to end to buildclean-api-docs; the 17 friction items that run surfaced are folded into 2.1.0.clean-refactoringhas not yet been run as a full multi-model workflow on a production application.
Explanation examples
After installing, use $clean-explanation in Codex or
/clean-explanation in Claude Code:
Use $clean-explanation: what is an API? Two sentences.Use $clean-explanation to explain this retry flow to a new teammate, with a diagram grounded in the supplied code.Use $clean-explanation to make an interactive explanation of compound interest. Show the assumptions and verify the controls and calculations.Use $clean-explanation for a rigorous text-only derivation. No follow-up quiz.
Writing examples
After installing, use $clean-writing in Codex or /clean-writing in Claude Code:
Use $clean-writing to set up my site at ~/Projects/site: notes get a light proofread, blog posts use my style.Use $clean-writing: post this voice transcript as a note.Use $clean-writing to write a blog post from these notes and this screenshot. Ask me before you invent anything.Use $clean-writing to post this note in Chinese and also in English.Use $clean-writing: post this on my blog with the attached photo and PDF. Check my facts first.
Video examples
After installing, use $clean-video in Codex or /clean-video in Claude Code:
Use $clean-video to set up my voices: Kokoro for English, Qwen3-TTS for Mandarin.Use $clean-video to make a 60-second video explaining how a web cache works, for my website.Use $clean-video: 用中文做一个一分钟的视频,解释 Git 的 rebase 和 merge 有什么区别。Use $clean-video to turn this post into a 45-second vertical Short with captions drawn in.Use $clean-video: change the second line to "The copy is out of date" and re-render.
Status bar
clean-status-bar is a two-row status line for Claude Code,
not a skill. It shows the repository, branch and changes, then the model, effort and your
5-hour and weekly usage, coloured by pace, with the reset time once a window is over 80%:
curl -fsSL https://x.vibewait.ing/x/clean-skills/raw/branch/main/clean-status-bar/install.sh | bash -s -- --apply
It needs bash and jq 1.6 or newer. The installer sets only statusLine in
~/.claude/settings.json, keeps an existing status line unless you pass --replace, and
--uninstall --apply restores it.
MIT licensed. See LICENSE. Linked third-party sources retain their own terms.