Portable Agent Skills Need Contracts, Not Just Instructions

Reusable AI-agent skills are becoming software packages. The missing layer is the same one software learned the hard way: explicit contracts.

A skill that works inside one agent can fail dangerously when another agent runs it. Different runtimes expose different tools. Different users assume different permissions. Different memory systems silently promote different facts. Different models interpret vague instructions differently.

That is why portable skills need more than a SKILL.md with helpful prose. They need a contract: what the skill accepts, what it may touch, what it must produce, what it must never do, and what evidence it leaves behind.

The failure mode

Most skill packages describe capability:

• "Research prospects."
• "Review code."
• "Publish content."
• "Summarize documents."
• "Automate support triage."

Capability is not enough. The buyer question is not "can it do the thing?" The buyer question is: can I predict its boundary conditions before I let it run?

The portable skill contract

Every reusable skill should ship with a one-page contract that answers nine questions:

1. Identity: What job does this skill do, and what jobs does it explicitly not do?
2. Inputs: What input fields are required, optional, or forbidden?
3. Tools: Which tools may it use, at what scope, and under what approval rules?
4. Outputs: What schema, artifact, or receipt must it return?
5. Receipts: What sources, actions, timestamps, and confidence notes must be logged?
6. Memory: What can it read, what can it propose writing, and what must never become durable memory automatically?
7. Exceptions: When should it stop, draft, escalate, or queue a human decision?
8. Evals: What cases prove the skill respects permissions and fails safely?
9. Versioning: What changed, who approved it, and which workflows depend on it?

A tiny example

For a code-review skill, the contract should say something like:

Notice what changed. The skill is no longer just "review code." It is a bounded capability with predictable authority.

Why this matters for marketplaces

Agent marketplaces will not scale on screenshots and vibes. Buyers need to compare skills the way engineers compare APIs: interface, permissions, side effects, failure behavior, and version history.

The winning skill sellers will make trust inspectable. They will publish clear contracts, sample receipts, eval cases, and compatibility notes. That is what turns a clever prompt bundle into a reusable production asset.

The 30-minute test

Before you publish or install a skill, ask:

• Can I name every tool this skill may call?
• Can I tell which actions are read-only, reversible, compensatable, or irreversible?
• Can I see what receipt it produces after running?
• Can I tell what it writes to memory versus what it merely observes?
• Can I predict when it will stop and ask a human?

If the answer is no, the skill is not ready for production reuse. It may still be useful. It just should not be trusted with real authority yet.