patch.md

An open format for declarative, AI-native code transformations.

A patch.md is a markdown file that describes a change in natural language — versioned in git, authored in any text editor, applied by any LLM-based agent. The format is the primitive; registries, marketplaces, and tooling are downstream of the convention.

patch.md has two modes:

• Source-tree patches edit a codebase you own — your app, your package, your mod's source. Specified in RFC 0001.
• Overlay patches inject behavior into a running host you don't own — a website you visit, a deployed service, a game you play. Specified in RFC 0002.

Both share the same document format, substitution rules, and verify-as-contract model. Status: early draft.

The smallest valid patch.md

# patch.md

## meta
- name: fix-typos

## files

### README.md (modify)
Fix any typos, grammatical errors, and awkward phrasing. Do not
change the meaning or structure of any section.

That's it. Two sections, one file operation.

A more realistic patch.md

# patch.md

## meta
- name: add-stripe-checkout
- version: 1.0.0
- target: next.js >= 16

## files

### src/lib/stripe.ts (create)
Create a Stripe client wrapper that exports a configured Stripe
instance using STRIPE_SECRET_KEY from environment variables.

### src/app/api/checkout/route.ts (create)
POST handler that creates a Stripe checkout session and returns
its URL as JSON.

## verify
- `src/lib/stripe.ts` exports a named `stripe` instance
- POST /api/checkout with a valid priceId returns 200 with a `url` field

See examples/ for a spectrum of patches, from one-line notes-to-self to full publishable integrations.

Why the format matters

Diffs are line-positional and brittle. Codemods are expensive to author and framework-coupled. Developers already describe changes to agents in natural language every day — there's just no shared format for it.

patch.md is a minimal markdown convention that is human-writable, model-agnostic, and verifiable through a behavioral-contract section (## verify). The full motivation and spec live in RFC 0001.

Repository layout

• rfc/ — numbered design documents for the format and ecosystem
  • 0001-patch-md.md — source-tree patches (filesystem)
  • 0002-overlay-patches.md — overlay patches (runtime injection into hosts you don't own)
• examples/ — illustrative patch.md files spanning both modes and the specificity spectrum
• skills/ — Anthropic-format skills for agents that interpret or apply patch.md files

Contributing

This repo is the home base for the format — spec, RFCs, and examples. Tooling and reference executors will live in separate repos. Open an issue or PR to propose changes to the spec.

Acknowledgments

Inspired by Theo Browne (t3dotgg). Prior art includes SOUL.md (markdown convention for agent personas) and Anthropic's SKILL.md format.