Skip to content

Main documentation ยท Source commit 73b589630e0330e5410ab3b129ea1fe1bb840373.

Agent skills

hoimin distributes two English-language Agent Skills under skills/:

  • hoimin-mutation-testing: choose focused Python mutation candidates, create a disk-bounded plan, and verify selected IDs against a fresh baseline.
  • hoimin-mutation-improvement: improve behavioral tests for surviving candidates, preserve plan identity, and report unverified work honestly.

Each skill includes its own PyPI setup reference and can be installed separately.

These skills implement hoimin's primary local agent workflow: investigate small batches, identify specification-backed test improvements, and reverify within resource budgets. A survivor is not automatically a test defect; an agent's equivalence judgment is not a proof. Humans resolve unclear requirements and review changes. Do not use the skills to maximize a kill ratio or run an unbounded loop. Stop and diagnose resource-limit or cleanup failures rather than silently increasing limits.

Skills are instructions for an agent; installing them does not install hoimin, run tests, or grant permission to execute commands. The repository's Elastic License 2.0 also applies to the skills.

Install with GitHub CLI

Use GitHub CLI 2.90.0 or later with gh skill --help available. See the official skill command reference for this preview feature. Upgrade the CLI if it reports unknown command "skill".

Inspect a skill before installation. For reproducible installation, replace COMMIT_SHA with the reviewed full commit SHA that contains skills/:

gh skill preview HayaoSuzuki/hoimin hoimin-mutation-testing@COMMIT_SHA
gh skill install HayaoSuzuki/hoimin hoimin-mutation-testing --agent codex --scope project --pin COMMIT_SHA
gh skill install HayaoSuzuki/hoimin hoimin-mutation-improvement --agent codex --scope project --pin COMMIT_SHA

For Claude Code, use --agent claude-code instead of --agent codex. Use --scope user only when you want the skills available across projects. Install into the project under test; hoimin's distribution repository does not maintain local .agents/skills or .claude/skills mirrors.

An unpinned install chooses the latest tagged release, falling back to the default branch only if no release exists. Tagged releases containing skills/, including v0.4.6, distribute both packages. Older tags may lack them: inspect the selected tag before installing. To use changes not yet included in a release, pin their reviewed commit explicitly. A --pin main pin follows a moving branch, whereas a commit pin identifies fixed content. Preview and install the same reviewed revision.

For a local checkout, install without changing the distribution source:

gh skill install . hoimin-mutation-testing --from-local --agent codex --scope project
gh skill install . hoimin-mutation-improvement --from-local --agent codex --scope project

The CLI copies the skill and adds source-tracking metadata to the installed copy. Keep install-generated metadata.github-* fields out of committed distribution files. Check installed skills with gh skill list --agent codex. Pinned installs remain pinned unless explicitly changed; use gh skill update --help before updating them.

Maintainer checks and releases

Edit the canonical files under skills/. Preserve the disk limits, cleanup ownership, native test argv, replan conditions, fresh-baseline requirement, and candidate-set restrictions on progress comparisons. Keep bundled references inside each skill so installing a single skill leaves no missing sibling links.

From the repository root, validate packaging without publishing:

gh skill publish --dry-run
uv run --frozen --no-sync pytest tests/test_skills.py

hoimin's existing release workflow owns product tags and GitHub Releases. Skill files are fetched from the tagged repository tree; no wheel or separate skill archive is required. Users can install a release's skills by pinning its tag when that tag contains skills/. Do not run gh skill publish --tag as part of routine skill validation: it creates a separate release and can conflict with hoimin's version allocation and publication workflow.

For the mutation workflow itself, follow the usage guide, including plan/verify and resource limits. Writing clear tests follows the development guide.