A SKILL.md can tell an agent how to use a browser, call an API, or edit files. What it usually does not say clearly is where the boundary is. Which tools? Which domains? Which actions need approval? What evidence shows the skill behaved?

Hand-drawn skill contract flow showing a skill file contract, static validation, runtime evidence, and audit results.
Skill Contracts connect what a skill promises to evidence from the run.

@skill-tools/contracts adds an optional contract block to SKILL.md frontmatter. The first contract kind is for browser-agent skills, because that is where I kept seeing the same risks: domains, actions, provenance, and grounding.

contract:
  kind: browser-agent
  runtime:
    domains: ["example.com"]
    approvalRequired: ["purchase", "submit_form"]
  provenance:
    replay: strict
  grounding:
    abstainBelowConfidence: true

I group the contract into three plain questions:

  • Runtime: what tools, domains, and actions are allowed?
  • Evidence: what traces, replay capsules, or artifacts should exist after the run?
  • Grounding: when should the skill refuse to act instead of guessing?

The workflow is declare, validate, audit. Static validation catches unsafe declarations early, like a risky browser action with no approval policy. Runtime adapters can normalize evidence from BAP, DBAR, or uSEID, then compare that evidence against the contract.

Hard violations fail closed. Missing evidence is surfaced as a warning unless the contract marks that evidence as required. That distinction matters: a missing optional trace should not break every workflow, but a declared approval gate must be enforced.

Skill Contracts and Agent Contracts solve related problems at different layers. The skill contract describes the promises attached to a capability. The agent contract describes the runtime boundary around the agent using that capability.

GitHub / npm