Agent Skills for AI-native engineering with an executable Definition of Done: clean-api-docs, clean-debate and clean-refactoring, sharing a fail-closed verification kit. Install with: cargo install --locked clean-skills
  • Python 89.9%
  • Rust 6.4%
  • Shell 3.5%
  • jq 0.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-23 10:45:23 +10:30
clean-status-bar feat: add clean-status-bar, a Claude Code status line 2026-10-23 10:23:21 +10:30
docs feat: let clean-api-docs use an allowed web search to find official pages 2026-10-23 10:45:10 +10:30
kit feat: add clean-api-docs 1.0.0 and clean-debate 2.1.0 2026-10-02 15:42:35 +09:30
skills feat: let clean-api-docs use an allowed web search to find official pages 2026-10-23 10:45:10 +10:30
src feat: add clean-api-docs 1.0.0 and clean-debate 2.1.0 2026-10-02 15:42:35 +09:30
tests feat: add clean-video skill 2026-10-22 21:56:03 +10:30
tools feat: add clean-status-bar, a Claude Code status line 2026-10-23 10:23:21 +10:30
.gitignore feat: add the clean-skills installer crate 2026-10-01 14:35:18 +09:30
build.rs feat: add the clean-skills installer crate 2026-10-01 14:35:18 +09:30
Cargo.lock chore: release clean-skills 0.6.1 with clean-api-docs 1.2.0 2026-10-23 10:45:23 +10:30
Cargo.toml chore: release clean-skills 0.6.1 with clean-api-docs 1.2.0 2026-10-23 10:45:23 +10:30
CHANGELOG.md chore: release clean-skills 0.6.1 with clean-api-docs 1.2.0 2026-10-23 10:45:23 +10:30
LICENSE feat: publish clean-refactoring 2.1.0 and deliberate-delegate-verify 1.0.0 2026-10-01 13:25:58 +09:30
README.md chore: release clean-skills 0.6.1 with clean-api-docs 1.2.0 2026-10-23 10:45:23 +10:30

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, clippy and the installer's tests, then builds the packaged crate, checks it ships skills/ 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-video 1.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 are clean-explanation's. See the design and evaluation record.
  • clean-writing 1.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 with clean-explanation. See the design and evaluation record.
  • clean-explanation 1.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-docs 1.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-refactoring 2.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-debate 2.1.0 (named deliberate-delegate-verify until 2.0.0). The design was settled with an external reviewer model after three cycles (see docs/clean-debate/). It was dogfooded end to end to build clean-api-docs; the 17 friction items that run surfaced are folded into 2.1.0. clean-refactoring has 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.