COVENANT.md

The design contract layer for AI agent skills.

A portable, framework-agnostic file format for declaring what a skill is: its domain, public interface, dependencies, typed contracts, and proof-of-correctness fixtures, declared in YAML and markdown beside SKILL.md and validatable before a single line of implementation is written.

Developed as the sibling of LOGIC.md: LOGIC.md describes the flow between steps; COVENANT.md describes the contract of each skill those steps invoke. They are complementary, and never drawn the same way.

---

The problem

Skills are folders of prose. 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. There is no enforceable boundary.

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 is not a documentation problem. It is 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.

---

What it is

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. Two fields are required (covenant_version, name), the rest is optional.

---
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.

---

The five questions

Every COVENANT.md answers five questions about a skill:

• Domain: who are you? The skill's identity and the problem space it owns.
• Interface: what do you expose? The operations callers may invoke, and nothing more. The boundary that stops internal complexity leaking outward.
• Dependencies: what do you need? The tools, sibling skills, and environment a correct invocation requires.
• Contracts: what do you promise? Typed inputs and outputs, plus invariants that hold for every invocation regardless of input.
• Quality: how do you prove it? Fixtures and gates that demonstrate the skill meets its contracts, runnable by a validator.

---

How it relates to SKILL.md and LOGIC.md

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 that 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: a task-level structure of how work flows from step to step. 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. A flow and a binding are never drawn the same way.

---

Skills as contracts

A skill that publishes a covenant is no longer a folder you have to read in full to trust. It is a party to an agreement. State your domain, expose a narrow interface, declare your dependencies, promise typed contracts, and prove them with fixtures. That is the shift: skills as contracts. #SkillsAsContracts

---

When to use COVENANT.md, and when not to

Use COVENANT.md when:

• A skill's interface is depended on by other skills, by agents, or by humans, and the boundary needs to be explicit and enforceable.
• You maintain a library of skills and want each one to declare its operations, typed inputs and outputs, and invariants.
• You want continuous validation of skills against a spec in CI.
• You are pairing with LOGIC.md and need each invoked skill to expose a contract the reasoning step can assert against.

You probably do not need COVENANT.md when:

• You have a one-off script with no callers and no interface to declare.
• The skill is still being prototyped and its surface is not yet known.
• You are optimising raw model output quality on a single LLM call. COVENANT.md is a contract layer, not a quality lever.

COVENANT.md does not make model outputs better. It makes the skill's surface explicit, validatable, and testable, so callers depend on a declared boundary rather than on reading the skill's internals.

---

Research and background

COVENANT.md is a deliberate response to two recent talks that name the problem from opposite sides. Both transcripts ship in this repo under docs/ so anyone can read the primary source.

Anthropic on Agent Skills: A New Paradigm for AI Agents

Barry and Mahesh's talk introduces Agent Skills as organised folders of files that package composable procedural knowledge for agents. Their stated roadmap for where skills are heading is exactly the gap COVENANT.md closes:

Testing & evaluation: formal testing and evaluation pipelines to verify skills load at the right time and produce quality output.

Versioning: clear lineage tracking as skills evolve and agent behaviour changes.

Skill dependencies: skills that can explicitly declare dependencies on other skills, MCP servers, or packages, improving predictability across runtime environments.

Sharing & distribution: better distribution and marketplace-style sharing so skills built anywhere benefit agents everywhere.

quality.fixtures is the testing pipeline. version plus interface.breaking_changes is the versioning lineage. dependencies.skills / mcp_servers / packages / environment is the dependency declaration. domain plus a kebab-case name is the marketplace handle.

Source: docs/Agent_Skills_Key_Takeaways.docx.

Matt Pocock (aihero.dev) on Software Fundamentals in the Age of AI

Pocock's argument is that AI thrives in well-structured codebases and breaks in poor ones, so software fundamentals matter more now, not less. Three of his named primitives are baked directly into COVENANT.md:

• Ubiquitous Language (from Eric Evans' Domain-Driven Design): a curated glossary of agreed terms derived from the domain model. In a covenant, this lives in domain.ubiquitous_language, either inline or as a separate file.
• Deep modules (from John Ousterhout's A Philosophy of Software Design): prefer relatively few, large units with simple interfaces that hide internal complexity. In a covenant, this is the domain.depth field, declared as deep or shallow, with the validator's heuristic that a deep skill should expose three or fewer operations.
• Design the interface; delegate the implementation. This is the entire separation that COVENANT.md formalises beside SKILL.md: the covenant is the public, validatable contract; SKILL.md is the procedural implementation that the contract no longer forces you to read in full.

Pocock closes by quoting Kent Beck: invest in the design of the system every day. A skill that publishes a covenant is doing exactly that, every time it changes.

Source: docs/Software_Fundamentals_in_AI_Age.docx.

Where the two converge

Anthropic names what skills are missing at the ecosystem layer (test pipelines, versioning, dependency declaration, distribution). Pocock names what skills are missing at the design layer (ubiquitous language, deep modules, declared interfaces). COVENANT.md is one file that addresses both: a declared, validatable, versioned, testable, dependency-aware contract beside the skill that owns the implementation.

---

Packages

Package	Description	Install
@covenant-md/core	Parser, validator, contract-driven test runner, skill runner, lint, diff, graph.	npm i @covenant-md/core
@covenant-md/cli	Six-command CLI (validate, test, generate, lint, diff, graph) with interactive scaffolding.	npm i -g @covenant-md/cli

---

Getting started

As a CLI

npm install -g @covenant-md/cli

covenant validate examples/docx-generation/COVENANT.md
covenant test examples/docx-generation/
covenant generate                    # interactive blueprint
covenant lint examples/docx-generation/
covenant diff old/COVENANT.md new/COVENANT.md
covenant graph examples/

As a library

npm install @covenant-md/core

import {
  validateCovenant,
  CovenantTestRunner,
  createSkillRunner,
  lintCovenant,
  diffCovenants,
  graphSkills,
} from '@covenant-md/core';

From source

git clone https://github.com/SingularityAI-Dev/covenant-md.git
cd covenant-md
npm ci
npm test                 # Jest across packages
npm run test:fixtures    # runs all four example skills through the CLI

---

Examples tour

Four worked example skills live under examples/, each a complete COVENANT.md plus SKILL.md you can validate and run:

• markdown-to-html: a single pure transform; the smallest useful covenant.
• pdf-generation: document creation with output contracts.
• template-rendering: typed inputs rendered against a template.
• docx-generation: create, read, and edit operations with invariants, roundtrip fixtures, and quality gates.

covenant test examples/docx-generation/

---

Specification

The canonical specification is docs/COVENANT.md. It is the source of truth when framework behaviour is ambiguous.

A canonical spec/schema.json, conformance fixtures, and three implementation tiers (parser, runtime, full) are landing in v1.1 (see the roadmap below).

---

Ecosystem

Shipped (v1.0)

• @covenant-md/core on npm
• @covenant-md/cli on npm
• @covenant-md/mcp on npm (MCP server, six tools over stdio)
• covenant-md on PyPI (Python SDK, alpha; parser + validator with verdict parity against the shared spec/fixtures/)
• Canonical spec/schema.json plus 15 conformance fixtures and three conformance tiers; see docs/IMPLEMENTER-GUIDE.md
• Claude Code plugin with five slash commands (/covenant:validate, /covenant:check, /covenant:init, /covenant:diff, /covenant:graph)
• Eval harness measuring the contract thesis (interface adherence, output fidelity, undeclared side effects) with a wired Anthropic adapter; results published when runs land
• Reusable GitHub Action for CI
• Four worked example skills, validated end-to-end

On the roadmap

• VSCode extension
• Cross-model published bench runs (Anthropic adapter wired; runs pending)

See ROADMAP.md for the full arc.

---

Status

• v1.0 shipped. @covenant-md/core@1.0.0 and @covenant-md/cli@1.0.0 published on npm.
• 56 Jest tests passing across two packages.
• Four example skills passing their fixtures end-to-end through the CLI.
• CI green on Node 20 and Node 22.

---

Development

git clone https://github.com/SingularityAI-Dev/covenant-md.git
cd covenant-md
npm ci
npm test
npm run test:fixtures
npm run lint        # Biome

Stack: ESM JavaScript, Node 20+, npm workspaces, Jest under --experimental-vm-modules, Biome for lint and formatting, js-yaml/semver/yaml for the parser.

---

Contributing

See CONTRIBUTING.md for build and test instructions and the project conventions (no em-dashes, British English, ESM only inside packages/). Issues and pull requests are welcome.

Security disclosures: see SECURITY.md.

---

Licensing

• Specification (the COVENANT.md format and its prose): CC-BY-4.0.
• Reference framework (packages/core and packages/cli): MIT.
• The "COVENANT.md" name: see TRADEMARK.md, including the conditions for calling a tool "COVENANT.md compliant".

---

Built by Rainier Potgieter, Durban, South Africa. MIT licensed.