Skills SDK
Portable contracts for inspectable AI skill packages
Skills SDK
Portable contracts for inspectable AI skill packagesProject overview
About the organization
An independent open-source Python project for maintainers building and checking Agent Skills packages. This case study inspects the committed version 0.1.0 contract.
What I did
I defined the product boundary and acceptance standard, directed the contract design, inspected failure cases, and used Codex to implement the typed models, CLI, schemas, fixtures, and tests.
Skills SDK turns package identity, validation, manifests, and receipts into explicit Python contracts that another tool can inspect without inheriting claims from a different candidate.
Inspectable boundary
What this work proves
- Claim
- A standalone skill package can be checked and described by deterministic, candidate-bound contracts.
- Evidence
- Committed Python source, Pydantic models, JSON schemas, synthetic fixtures, CLI tests, and explicit pass/blocked examples at the inspected revision.
- Caveat
- The SDK does not run providers, install packages, mutate runtimes, publish to registries, or prove installed behavior.
From problem to proof
How the delivery unfolded
Problem
Package evidence could lose the candidate it belonged to.
AI skill workflows produce many observations, but a green result is unsafe to reuse when the source revision or package content has changed. Maintainers needed portable data structures that preserve identity and blocked states.
Discovery
The core needed to stay independent of every host.
Provider accounts, registries, installation, and runtime discovery have different authorities. The reusable layer could model their evidence without pretending to perform or verify those external operations.
Constraints
Useful contracts without inflated capability.
- Package identity must bind a package ID, 40-character source revision, and SHA-256 content digest.
- Validation and build must be prompt-free, read-only, and explicit about blocked outcomes.
- Schemas must remain versioned and serializable for tools outside the repository.
- Discovery-only command names must not be presented as implemented execution paths.
Decisions
Keep the surface small and the boundary precise.
- Ship validate and build as the implemented CLI paths in the 0.x contract-building series.
- Use Pydantic models and checked JSON schemas for portable wire contracts.
- Return typed findings and blockers instead of flattening failure into prose.
- Model runtime planning as a mutation-free intention, leaving host actions to future adapters.
Delivery
A runnable contract layer with success and failure examples.
The repository includes a synthetic skill fixture, stable JSON output, schemas, and tests spanning package safety, receipts, evaluation, lifecycle, registry, risk, security, and runtime-evidence contracts.
Failure and correction
The public boundary now names what does not execute.
Earlier lifecycle language could be read as broader capability. The current source makes clear that only validate and build execute local package work; other command names expose help and discovery boundaries.
Outcome
Maintainers can inspect a package result without guessing.
A valid fixture can produce a versioned pass or built receipt, while malformed identity produces a typed blocked result. This is local contract evidence, not provider, installation, registry, or adoption proof.
Human-owned delivery
Directed by Jamie. Implemented with Codex.
- Jamie
- Set the outcome and boundaries, selected the contract shape, challenged overclaims, inspected evidence, and owns the product and release decisions.
- Codex
- Implemented Python models, CLI routes, schemas, fixtures, tests, and documentation under Jamie's direction and review.
Inspect the evidence
Follow the artifact, tests, and stated limits.
All work 05
01 / 05
SkillsBar
02 / 05
Skills SDK
03 / 05
CLI Tools
04 / 05
Proof Log
05 / 05