rogerchappel/skill-io-contract-skill

Skill IO Contract Skill

Validate that an agent skill has an explicit input/output contract before it is shared or reused.

skill-io-contract is a local-first checker for SKILL.md files and their fixture cases. It looks for explicit Markdown section headings that agents need in order to route a skill safely, then compares JSON fixture cases against a small contract schema. The default mode is read-only and emits a Markdown report.

Quickstart

python -m pip install "skill-io-contract-skill @ git+https://github.com/rogerchappel/skill-io-contract-skill.git"
skill-io-contract check --bundled

The package is not yet published to PyPI. Once it is available there, the shorter python -m pip install skill-io-contract-skill command will be supported. Until then, use the GitHub command above.

--bundled checks the reusable contract at share/skill-io-contract-skill/SKILL.md and its fixture at share/skill-io-contract-skill/fixtures/cases.json under the installation prefix. For a source checkout or your own skill, pass explicit paths instead:

skill-io-contract check --skill SKILL.md --fixtures fixtures/cases.json --report report.md

For development from a source checkout, install the development dependencies and run the repository smoke check:

python -m pip install -e ".[dev]"
npm run smoke

What It Checks

• Required SKILL.md headings for triggers, inputs, outputs, side effects, approvals, examples, and validation. Accepted heading names include the variants demonstrated in the bundled SKILL.md; keywords in prose or fenced code do not satisfy this check.
• Fixture cases that name the input, expected output shape, allowed side effects, and verification command.
• Missing approval boundaries when a fixture permits an unqualified write

(write, writes, writing, wrote, or written); an external action such as pushing, publishing, sending, or connector wording such as use, uses, or using; or a create, update, edit, delete, or remove action on a clearly external resource such as GitHub, a repository issue or release, a pull request, an external account, or a release artifact. Explicitly local report and file writes and read-only external actions do not require approval metadata. Action and resource signals must occur in the same clause, so a local mutation followed by a separate external read remains read-only externally; actions using not, never, without, or common contractions are not treated as mutations, including coordinated wording such as does not push or publish a release. Any affirmative external action in the same or a separate clause still requires approval.

• A concise release-readiness score that can be pasted into a PR.

Safety Notes

The CLI never writes to the skill or fixture files. It writes only the requested report path. It does not call external services, read credentials, or execute fixture commands.

Exit Status and I/O Errors

The check command exits with status 0 when every contract check passes, 1 when the generated report contains a failed check, and 2 when a CLI input cannot be read, including because it is not valid UTF-8, or the requested --report path cannot be created or written. Input and output errors are written to stderr without a Python traceback and identify the affected option and path, for example: