Release 1.8.1: make the bundle a straight copy for downstream registries

[fedorov]

Review of the vendored copy in K-Dense-AI/scientific-agent-skills#158 surfaced two things that registry has to patch locally after every sync. Both are fixed here, so the next sync is a file copy with no local layer.

Frontmatter indentation (blocking downstream CI)

metadata was nested four spaces. Valid YAML, and metadata.version parses fine with a YAML library — but that registry's validator (tests/_contract/structure.py) reads frontmatter line by line and matches ^ key: only, so it reported metadata.version as missing and failed the bundle on whitespace. Running their repo-wide contract against a straight copy of 1.8.0 produced exactly one structural failure, this one.

Now two spaces, pinned by tests/test_structure.py::TestFrontmatter::test_metadata_scalars_are_indented_two_spaces.

Installer commands

The guides handed out pip install --upgrade idc-index in five Prerequisites blocks, plus pip install duckdb / google-cloud-bigquery mentions. A bare pip install targets whichever interpreter pip resolves to and drops the pinned version — the failure scripts/check_version.py exists to prevent, and why USAGE.md stopped doing it in 1.8.0.

The registry independently rewrites every pip install in a vendored skill to uv pip install (their commit 4226ca8), which is the same problem from the other side: any single installer named in the bundle is wrong in some environment. So the guides now name the package that is needed and point at check_version.py for idc-index, and that script — the one place that can see the interpreter it is running under — prefers uv when uv is on PATH:

Install the vetted version with:

    uv pip install --python /path/to/venv/bin/python 'idc-index==0.12.5'
    /path/to/venv/bin/python -m pip install 'idc-index==0.12.5'

--python matters: a bare uv pip install targets the active virtual environment, not necessarily the one that failed to import idc_index. Neither form overrides PEP 668 — both refuse on an externally managed interpreter, which is the intended outcome. tests/test_structure.py fails on a reintroduced pip/uv/conda/poetry install line in SKILL.md or references/.

New: tests/test_check_version.py

Offline, standard library only, 20 tests: version parsing (numeric ordering, v prefixes, pre-release tags), install-command construction, check_minimum / main exit codes, best-effort network notices, and guards that the script never shells out to an installer and never bypasses PEP 668. Runs with nothing installed.

That last property is deliberate: registries that require a test suite for any skill shipping scripts/ can run this file as-is instead of writing their own. The cases it duplicated were removed from tests/test_snippets.py, which needs idc-index installed. scripts/** was also missing from the test-snippets.yml path filters, so a change to the bundled script did not trigger CI.

Verification

• pytest tests/test_structure.py tests/test_check_version.py — 33 passed, no network, no idc-index
• SKILL.md is 495 lines (budget 500)
• No pip/uv/conda/poetry install command remains in SKILL.md, references/, USAGE.md, or README.md
• scripts/check_version.py run against a 0.12.3 environment prints both commands and exits 1
• uv pip install --python <venv> --dry-run 'idc-index==0.12.5' resolves; against an externally managed interpreter it refuses with the PEP 668 message, as intended

🤖 Generated with Claude Code