The design contract layer for AI agent skills.

Skills are folders of prose. There is no enforceable boundary.

A caller, human or agent, has to read the entire folder to learn what a skill exposes, what inputs it requires, what side effects it has, and which outputs it actually produces. When the skill changes, callers find out at runtime. When two skills depend on each other, nothing checks that the contract between them holds. When a model invokes a skill outside its declared surface, nothing catches it.

This isn't a documentation problem. It's a missing-contract problem. COVENANT.md fills that gap. A covenant beside SKILL.md declares what the skill is on five axes and lets a validator and a test runner enforce it.

One file beside SKILL.md. Two required fields.

A markdown file with YAML frontmatter that sits beside SKILL.md in a skill folder. The YAML is the machine-parseable contract; the markdown body is human rationale. Only covenant_version and name are required.

---
covenant_version: "1.0"
name: docx-generation
version: 1.0.0
domain:
  purpose: Create and edit Microsoft Word documents
  scope: Reads and writes .docx files via a structured content object
interface:
  surface:
    - name: render
      accepts: [content, output_path]
      returns: [success]
contracts:
  inputs:
    content: { type: object, required: true }
    output_path: { type: string, required: true }
  outputs:
    success: { type: boolean }
quality:
  fixtures:
    - name: minimal-render
      operation: render
      input: { content: { title: "Hello" }, output_path: "/tmp/out.docx" }
      expect: { success: true }
---

A validator checks this against the spec; a contract-driven runner executes the fixtures against a real or simulated skill runner. If the skill drifts from its own covenant, the gate fails.

Every COVENANT.md answers five questions about a skill.

SKILL.md is the how. COVENANT.md is the what.

SKILL.md is the how; COVENANT.md is the what. SKILL.md is procedural knowledge: the steps, scripts, and tools an agent follows. COVENANT.md is the design contract that sits above it, declaring the commitments the skill makes so callers can depend on a boundary rather than on the skill's internals.

LOGIC.md is flow; COVENANT.md is contract. LOGIC.md describes a multi-step reasoning pipeline as a directed graph. COVENANT.md describes a single skill as a bilateral binding. A LOGIC.md step that invokes a skill can assert against that skill's declared contract rather than guessing at its behaviour.

State your domain. Expose a narrow interface. Prove it with fixtures.

A skill that publishes a covenant is no longer a folder you have to read in full to trust. It's a party to an agreement. That's the shift: skills as contracts. #SkillsAsContracts

A contract layer, not a quality lever.

A deliberate response to two talks that name the problem from opposite sides.

Both transcripts ship in the repo under docs/ so anyone can read the primary source.

Anthropic names what skills are missing at the ecosystem layer. Pocock names what skills are missing at the design layer. COVENANT.md is one file that addresses both.

Four worked skills, validated end-to-end.

Each a complete COVENANT.md plus SKILL.md you can validate and run.

Three packages shipped. A Python SDK. A canonical schema.

npm install -g @covenant-md/cli

# Validate a covenant against the canonical spec
covenant validate examples/docx-generation/COVENANT.md

# Run its fixtures through a real or simulated skill runner
covenant test examples/docx-generation/

# Interactive scaffold for a new covenant
covenant generate

# Heuristic design checks
covenant lint examples/docx-generation/

# Semantic diff, breaking, additive, cosmetic
covenant diff old/COVENANT.md new/COVENANT.md

# Dependency graph across a skills library
covenant graph examples/

Canonical specification at docs/COVENANT.md. Claude Code plugin ships five slash commands: /covenant:validate, /covenant:check, /covenant:init, /covenant:diff, /covenant:graph. Specification licensed CC-BY-4.0; reference framework (core, cli) licensed MIT.

Evidence: compiled from the covenant-md repository on 2026-08-03. Every number on this page traces to a file path or command output in the source tree. Last updated: 2026-08-03.