Declare and validate each skill's capabilities

[richardmhope]

What & why

Skills didn't declare what they ask an agent to do, so a reviewer or installer had to read every instruction to find out. This adds a required, versioned capabilities block to every skill's meta.yaml (schema 1). It covers:

• files read and edited;
• commands;
• network use, and why;
• credentials;
• agent tools;
• files created.

Anything not declared is not requested. The docs say plainly that this is a declaration for review, and that skilldeck can't enforce it inside an agent.

• Validation (skilldeck.capabilities, registry) rejects:

  • malformed blocks;
  • commands given as script paths, with shell operators, or as an interpreter given a script or inline code;
  • artifact paths that could leave the project: absolute, a drive, ~, \, . or ...

• Bundle rules. A skill directory is exactly a regular meta.yaml plus a regular skill.md. It rejects:

  • symlinks and Windows junctions, including a linked skill directory;
  • subdirectories;
  • undeclared executables, detected by script suffix, exec bit, #! or binary header;
  • any other file;
  • links in skill.md to files the skill can't ship. This covers Markdown links, images, reference definitions, autolinks, and HTML tag src/href. Code, prose and indented blocks aren't checked.

  OS and editor leftovers (.DS_Store, swap files, …) are ignored when loading, so one stray file doesn't break every command. provenance --verify and catalog stay strict and report them as unexpected files. tests/test_capabilities.py builds the adversarial bundles in tmp_path.

• Preview. skilldeck show <skill> --summary and skilldeck install … --dry-run show:

  • the source and the build recorded at build time;
  • the digest checked against the shipped content manifest, with a pointer to provenance --verify for real verification;
  • the deprecation state and the declared capabilities.

  The dry run also shows what each install would do, or the error it would hit (including a destination folder that can't be created). It writes nothing.

• Installed files. Adapters add a ## Declared capabilities section, addressed to the agent, only to skills that ask for more than a read-only review: an edit, a credential, an agent tool, an artifact, or a command beyond read-only git. The ten read-only review skills install byte for byte as before; only dependency-review, logging and test-review gain the section. The adapter contract skill declares its project test command, so the fixtures pin the section (contract sha256:7c21e0856472).

• Catalog. catalog --json gains an additive capabilities field. schema_version stays 1; a future capability schema would be a breaking catalog change.

• The 13 bundled skills each declare what their instructions ask for, with a version bump: patch for the declaration alone, and dependency-review goes to 0.5.0 (a minor bump) because its instructions changed.

  • test-review now runs a regression test against the pre-change code only in a temporary git worktree.
  • dependency-review runs pip-audit only as pip-audit --disable-pip on fully pinned files, following pip-audit's security model, and declares reading package registry pages.

• Structure test. It keeps the declared commands and the skill bodies in sync, including commands from common CLIs that no skill declares yet. The plugin tree and manifests are regenerated.

• Breaking for skill authors, per docs/lifecycle.md: meta.yaml now requires capabilities, and a skill directory may hold only meta.yaml and skill.md.

An independent review found two problems, both fixed here:

• the notice originally went on every skill, mostly repeating its body;
• a single stray .DS_Store broke every command.

It also found:

• the pip-audit and test-review instruction issues above;
• --dry-run reporting "would install" when a destination folder couldn't be created;
• the link check matching prose;
• gaps in the command checks.

Not done here: the golden-diff evals weren't re-run, because they're paid. The dependency-review and test-review bodies changed, and three skills gained the section, so a maintainer should run them by hand.

Closes #73

Tracking: #94

Type of change

• Bug fix
• New feature
• New or updated skill
• Docs only
• Refactor / internal

Checklist

• Ran uv run --extra dev ruff check . && uv run --extra dev ruff format --check . && uv run --extra dev mypy && uv run --extra dev pytest (1137 passed, also with -W error::EncodingWarning and --resolution lowest-direct)
• Added or updated tests
• Updated docs where relevant
• Added a CHANGELOG.md entry under ## [Unreleased]
• For a skill change: bumped that skill's version in meta.yaml

🤖 Generated with Claude Code

https://claude.ai/code/session_01HtiCGzpikMrkDYBkfQG5CX

---

Generated by Claude Code