From 9bf3a6d7e26bc7925e01a1c80c7714f070a51ce9 Mon Sep 17 00:00:00 2001 From: Your Name Date: Fri, 3 Jul 2026 12:00:06 +1000 Subject: [PATCH 1/3] =?UTF-8?q?docs:=20markdown=20interop=20=E2=80=94=20sk?= =?UTF-8?q?ill-wrapper=20example,=20AGENTS.md,=20positioning?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Defines OA's relationship to the AGENTS.md / SKILL.md patterns without attaching to them. One bright-line rule: markdown patterns may point at OA specs; OA specs never point at markdown patterns. - docs/proposals/markdown-interop.md: full proposal — background, risks (discoverability collision, distribution channel), position (guidance layer vs execution contract), what we refuse, how we manage it - examples/skill-wrapper/: SKILL.md wrapping a typed OA spec — turns the skills ecosystem into a distribution channel for specs - AGENTS.md: dogfoods the coexistence pattern — points coding agents at specs and the CLI instead of hand-rolled agent logic - README: "How OA Relates to AGENTS.md and Skills" positioning section Zero schema or runtime changes. Co-authored-by: Cursor --- AGENTS.md | 65 ++++++++++++++++ README.md | 28 +++++++ docs/proposals/markdown-interop.md | 114 +++++++++++++++++++++++++++++ examples/skill-wrapper/README.md | 50 +++++++++++++ examples/skill-wrapper/SKILL.md | 53 ++++++++++++++ examples/skill-wrapper/spec.yaml | 49 +++++++++++++ 6 files changed, 359 insertions(+) create mode 100644 AGENTS.md create mode 100644 docs/proposals/markdown-interop.md create mode 100644 examples/skill-wrapper/README.md create mode 100644 examples/skill-wrapper/SKILL.md create mode 100644 examples/skill-wrapper/spec.yaml diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7b4e8c6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,65 @@ +# AGENTS.md — Guidance for Coding Agents Working in This Repository + +This repository is the home of **Open Agent Spec (OA)** — a declarative +standard for defining AI agents as portable YAML contracts. + +## The one rule that matters + +**Agent behaviour in this repo is defined as OA specs, not as code or prose.** +If you need an agent to do something, find or write a spec under `examples/` +and execute it with the CLI — do not hand-roll LLM calls, prompts, or agent +logic inline. + +```bash +# Validate a spec +oa validate --spec examples/file-reader/file-reader.yaml + +# Run a task from a spec +oa run --spec examples/skill-wrapper/spec.yaml --task summarise \ + --input '{"text": "..."}' +``` + +This file (AGENTS.md) is guidance; the specs are contracts. When they appear +to conflict, the spec wins — it is schema-validated and runner-enforced, +this file is not. + +## Repo layout + +| Path | What it is | +|---|---| +| `oas_cli/` | Reference Python runtime + CLI | +| `npm/` | TypeScript/npm runtime (`@prime-vector/open-agent-spec`) | +| `spec/` | The formal specification, JSON Schemas, and conformance suite | +| `spec/conformance/` | Runtime-agnostic conformance harness and cases | +| `examples/` | Runnable example specs — the canonical usage reference | +| `docs/` | Reference docs and proposals | + +## Development commands + +```bash +# Python: install, test, lint +pip install -e ".[dev]" +python -m pytest tests/ -q +ruff check . --exclude test_output/ && ruff format --check . --exclude test_output/ +mypy oas_cli tests + +# npm runtime: build and typecheck +cd npm && npm ci && npm run build + +# Conformance suite (certifies both runtimes against the standard) +python -m spec.conformance.harness.harness --adapter python --adapter node +``` + +## Conventions + +- Changes to runtime behaviour need tests, and if the behaviour is normative, + a conformance case under `spec/conformance/cases/` so no runtime can + regress silently. +- The Python and npm runtimes must stay in parity — if you change execution + semantics in one, change the other and re-run the conformance suite. +- OA's boundaries are deliberate: no orchestration, no conditionals or + branching in specs, no prose-as-contract. Read + `docs/proposals/markdown-interop.md` before proposing integrations with + markdown agent patterns (AGENTS.md / SKILL.md). +- Use `OA` (not `OAS`) in prose; technical identifiers like `oas_cli/` and + `oas-schema-*.json` keep their existing names. diff --git a/README.md b/README.md index 04225e1..0ed8635 100644 --- a/README.md +++ b/README.md @@ -463,6 +463,34 @@ Supports OpenAI and Anthropic, `depends_on` chains, and history threading. --- +## How OA Relates to AGENTS.md and Skills + +AGENTS.md tells your copilot how to behave. **Open Agent Spec defines what +your agents actually do** — typed, sandboxed, conformance-tested. + +The markdown agent patterns (AGENTS.md, SKILL.md) are prose guidance +interpreted by a model at runtime: quick to write, but unvalidated, +unenforceable, and untestable. OA operates one layer below them as the +execution contract — input/output schemas, pinned models, runner-enforced +sandboxing, and structured errors, certified identical across runtimes by a +[conformance suite](spec/conformance/README.md). + +The two layers compose cleanly, following one rule: + +> **Markdown patterns may point at OA specs. OA specs never point at +> markdown patterns.** + +- A **SKILL.md can wrap an OA spec** — the skill provides discovery, the spec + provides the guaranteed behaviour. See + [examples/skill-wrapper/](examples/skill-wrapper/). +- An **AGENTS.md can direct coding agents to your specs** instead of letting + them improvise agent logic. This repo's own [AGENTS.md](AGENTS.md) + demonstrates the pattern. + +Full rationale: [docs/proposals/markdown-interop.md](docs/proposals/markdown-interop.md). + +--- + ## Generate a Python Scaffold If you want editable generated code instead of running the YAML directly: diff --git a/docs/proposals/markdown-interop.md b/docs/proposals/markdown-interop.md new file mode 100644 index 0000000..87143e2 --- /dev/null +++ b/docs/proposals/markdown-interop.md @@ -0,0 +1,114 @@ +# Proposal: Interop with AGENTS.md and Skills (Markdown Agent Patterns) + +**Status:** Proposed +**Scope:** Documentation and examples only — zero schema or runtime changes +**Author:** Prime Vector / Open Agent Spec maintainers + +## Background + +Since OA was designed, two markdown-based patterns have gained significant +mindshare in agentic engineering: + +- **AGENTS.md** — a prose file at a repository root giving interactive coding + agents (Cursor, Claude Code, Codex, etc.) ambient instructions: conventions, + build commands, style rules. +- **Skills** (SKILL.md folders) — prose instructions with name/description + frontmatter, optionally bundled with loose scripts, progressively disclosed + to an agent when the description matches the task at hand. + +Stripped of hype, both are the same thing: **natural-language instructions +that a model may or may not follow**. Neither has a schema. Neither is +validated, versioned, mechanically enforceable, or conformance-testable. +When a skill "breaks", you find out by watching an agent do the wrong thing. + +## The question + +Should OA engage with these patterns, and if so, how — without inheriting +their weaknesses? + +Two real risks argue against ignoring them entirely: + +1. **Discoverability collision.** People searching "agent spec" increasingly + land on AGENTS.md content. Some will assume Open Agent Spec is a competing + "agent file" format. Silence lets others define the relationship for us. +2. **Distribution channel.** Skills are becoming how people *share agent + capabilities*. Ignoring that channel means OA specs lose a growing on-ramp. + +## Position + +OA and the markdown patterns are not competitors. They operate at different +layers: + +| | AGENTS.md / Skills | Open Agent Spec | +|---|---|---| +| Layer | Guidance (how an interactive agent behaves) | Execution contract (what an agent task *is*) | +| Format | Prose | Declarative YAML, JSON-Schema validated | +| Enforcement | Model goodwill | Runner-enforced (sandbox, schemas, structured errors) | +| Portability | Per-tool conventions | Conformance-tested across runtimes | +| Failure mode | Silent drift | Structured error codes | + +The industry has discovered that agents need shared, distributable +definitions — and reached for the weakest possible format first. OA's answer +is not to join the trend or to buck it, but to be the thing the markdown +eventually points at. + +## The rule (bright line) + +> **Markdown patterns may point at OA specs. OA specs never point at +> markdown patterns.** + +All interop happens one layer *above* the spec. Nothing enters the schema. +This is consistent with every prior boundary decision: no `skill:` task type +(rejected), no orchestration, no prose-as-contract. + +## What this proposal delivers + +Three artifacts, all documentation/examples: + +1. **`examples/skill-wrapper/`** — a SKILL.md that wraps an OA spec. The + skill provides discovery (name + description an agent can match on) and + instructs the agent to execute via `oa run` rather than improvising. The + OA spec provides the actual contract: typed inputs/outputs, pinned model, + validated output. This turns the skills ecosystem into a distribution + channel for OA specs — a skill wrapping a spec is strictly better than a + skill wrapping a loose script. + +2. **Root `AGENTS.md`** — dogfoods the coexistence pattern in this repo: + tells coding agents that agent behaviour here is defined as OA specs, + points them at `oa run` / `oa validate` / the conformance harness, and + instructs them not to hand-roll agent logic. Doubles as genuinely useful + contributor guidance. + +3. **README positioning section** — "How OA relates to AGENTS.md and + Skills". Defines the relationship publicly before someone else does. + +## What we explicitly refuse + +To keep the line bright, the following are out of scope permanently unless +revisited by a future proposal: + +- ❌ A `skill:` task type or any skill reference inside a spec +- ❌ Markdown-file prompt references inside specs (kills single-file + portability) +- ❌ Any schema-level claim of AGENTS.md/skills "compatibility" +- ❌ Runtime awareness of SKILL.md or AGENTS.md files + +The moment prose instructions become load-bearing inside a spec, OA inherits +every problem it is currently immune to. + +## Future (optional, demand-driven) + +If the skills channel proves sticky, an `oa skill package` CLI command could +generate a SKILL.md wrapper from a spec's existing metadata (agent name, +description, task inputs). This is tooling *on top of* the boundary, not a +schema change — and should not be built until someone asks for it. + +## How we manage it + +- These artifacts ship as docs/examples in a normal PR; no version bump + required beyond a changelog note. +- The bright-line rule above gets cited in future feature discussions the + same way "no orchestration" and "no skills task type" are today. +- If the AGENTS.md/skills patterns evolve into something schema'd and + enforceable, we reassess via a new proposal — from a position of interop + rather than dependence. diff --git a/examples/skill-wrapper/README.md b/examples/skill-wrapper/README.md new file mode 100644 index 0000000..9d12842 --- /dev/null +++ b/examples/skill-wrapper/README.md @@ -0,0 +1,50 @@ +# Skill Wrapper — Distributing an OA Spec Through the Skills Ecosystem + +This example shows the **skill-wrapper pattern**: a `SKILL.md` (the markdown +"skills" format used by Claude Code, Cursor, and similar coding agents) whose +only job is to point the agent at a typed, validated OA spec. + +``` +skill-wrapper/ +├── SKILL.md # discovery + instructions: "run the spec, don't improvise" +├── spec.yaml # the actual contract: typed I/O, pinned model, prompts +└── README.md # this file +``` + +## The division of labour + +| Layer | File | Responsibility | +|---|---|---| +| Guidance | `SKILL.md` | Discovery (name/description an agent matches on) and the instruction to execute via `oa run` | +| Contract | `spec.yaml` | Input/output schemas, pinned engine and model, explicit prompts, structured errors | + +The skill is a thin distribution shim. All behaviour lives in the spec — +which means it is identical on every machine, validated on every run, and +certifiable by the [conformance suite](../../spec/conformance/README.md). +A skill wrapping an OA spec is strictly better than a skill wrapping a loose +script: the payload is typed, versioned, and portable. + +## Try it directly (no agent required) + +```bash +export OPENAI_API_KEY=sk-... +oa run --spec examples/skill-wrapper/spec.yaml --task summarise \ + --input '{"text": "OA is a declarative standard for defining AI agents as portable YAML contracts. It supports tools, sandboxing, spec composition and a public registry."}' +``` + +## Try it as a skill + +Copy this directory into your agent's skills location (e.g. +`~/.claude/skills/document-summariser/` or your project's skills folder) and +ask the agent to summarise something. The agent discovers the skill via the +frontmatter description and executes the spec instead of improvising. + +## The rule this pattern follows + +> Markdown patterns may point at OA specs. OA specs never point at markdown +> patterns. + +`spec.yaml` contains no reference to `SKILL.md` — delete the skill file and +the spec still works everywhere. See +[docs/proposals/markdown-interop.md](../../docs/proposals/markdown-interop.md) +for the full rationale. diff --git a/examples/skill-wrapper/SKILL.md b/examples/skill-wrapper/SKILL.md new file mode 100644 index 0000000..7a40a71 --- /dev/null +++ b/examples/skill-wrapper/SKILL.md @@ -0,0 +1,53 @@ +--- +name: document-summariser +description: > + Produce a structured summary (one paragraph + key points) of any document + or text. Use this whenever the user asks to summarise a file, article, + changelog, meeting notes, or any other body of text and expects a + consistent, structured result. +--- + +# Document Summariser + +This skill delegates to a typed, validated **Open Agent Spec** task instead +of improvising summarisation behaviour. Do not summarise the text yourself — +execute the spec so the output shape is guaranteed. + +## Prerequisites + +The `oa` CLI must be available (`pipx install open-agent-spec` or +`npm i -g @prime-vector/open-agent-spec`) with an `OPENAI_API_KEY` set. + +## How to use + +1. Obtain the text to summarise (read the file yourself if the user gave a + path). +2. Run the spec from this skill's directory, passing the text as input: + +```bash +oa run --spec spec.yaml --task summarise \ + --input '{"text": ""}' --quiet +``` + +For long documents, write the input to a JSON file first and pass the path: + +```bash +oa run --spec spec.yaml --task summarise --input input.json --quiet +``` + +3. The result is guaranteed by the spec's output schema to be a JSON object + with exactly: + - `summary` — one-paragraph summary (string) + - `key_points` — key takeaways (array of strings) + +Relay `summary` and `key_points` to the user. If the command exits non-zero, +report the structured error (`code`, `stage`) — do not retry with your own +improvised summary. + +## Why this is a spec and not instructions + +The behaviour lives in `spec.yaml`: typed input/output schemas, a pinned +model, explicit prompts, and structured errors. That makes this skill's +behaviour identical across every agent and machine that invokes it — +something prose instructions cannot guarantee. See +https://openagentspec.dev for the standard. diff --git a/examples/skill-wrapper/spec.yaml b/examples/skill-wrapper/spec.yaml new file mode 100644 index 0000000..ea83d3b --- /dev/null +++ b/examples/skill-wrapper/spec.yaml @@ -0,0 +1,49 @@ +open_agent_spec: "1.5.0" + +agent: + name: document-summariser + description: > + Summarises a document into a concise paragraph and structured key points. + Designed to be wrapped by a SKILL.md so interactive coding agents execute + this typed, validated task instead of improvising their own behaviour. + role: analyst + +intelligence: + type: llm + engine: openai + model: gpt-4o-mini + +tasks: + summarise: + description: > + Summarise the supplied text and return a validated, structured result. + prompts: + system: > + You are a precise summarisation assistant. Respond with valid JSON + containing exactly two fields: + "summary" (a concise one-paragraph summary of the text) and + "key_points" (an array of short strings, one per key takeaway). + Return only the JSON object — no markdown fencing, no extra text. + user: "Please summarise the following text:\n\n{text}" + input: + type: object + properties: + text: + type: string + description: The document text to summarise. + required: + - text + output: + type: object + properties: + summary: + type: string + description: A short summary of the document. + key_points: + type: array + items: + type: string + description: Bullet-point key takeaways. + required: + - summary + - key_points From fe8cef855f5de1e099b9f3d28d8135a2d61907c5 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 4 Jul 2026 08:23:09 +1000 Subject: [PATCH 2/3] docs: fix conformance command in AGENTS.md; document Anthropic engine swap - AGENTS.md pointed at a non-existent module/flags (spec.conformance.harness.harness --adapter ...); replace with the real entry point (spec.conformance.runner.conformance_runner) and note the suite runs the runtime-agnostic cases against the Python runtime. - Soften the matching README claim from 'certified identical across runtimes' to 'pinned to a shared, runtime-agnostic conformance suite'. - skill-wrapper: document the OpenAI->Anthropic engine swap in spec.yaml, SKILL.md prerequisites, and the example README to demonstrate portability. --- AGENTS.md | 5 +++-- README.md | 2 +- examples/skill-wrapper/README.md | 4 ++++ examples/skill-wrapper/SKILL.md | 4 +++- examples/skill-wrapper/spec.yaml | 6 ++++++ 5 files changed, 17 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7b4e8c6..52032a0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,8 +46,9 @@ mypy oas_cli tests # npm runtime: build and typecheck cd npm && npm ci && npm run build -# Conformance suite (certifies both runtimes against the standard) -python -m spec.conformance.harness.harness --adapter python --adapter node +# Conformance suite (runtime-agnostic cases; executes them against the Python runtime) +python -m spec.conformance.runner.conformance_runner +python -m spec.conformance.runner.conformance_runner --list # list all cases ``` ## Conventions diff --git a/README.md b/README.md index 0ed8635..39ec51e 100644 --- a/README.md +++ b/README.md @@ -472,7 +472,7 @@ The markdown agent patterns (AGENTS.md, SKILL.md) are prose guidance interpreted by a model at runtime: quick to write, but unvalidated, unenforceable, and untestable. OA operates one layer below them as the execution contract — input/output schemas, pinned models, runner-enforced -sandboxing, and structured errors, certified identical across runtimes by a +sandboxing, and structured errors, pinned to a shared, runtime-agnostic [conformance suite](spec/conformance/README.md). The two layers compose cleanly, following one rule: diff --git a/examples/skill-wrapper/README.md b/examples/skill-wrapper/README.md index 9d12842..4722a17 100644 --- a/examples/skill-wrapper/README.md +++ b/examples/skill-wrapper/README.md @@ -32,6 +32,10 @@ oa run --spec examples/skill-wrapper/spec.yaml --task summarise \ --input '{"text": "OA is a declarative standard for defining AI agents as portable YAML contracts. It supports tools, sandboxing, spec composition and a public registry."}' ``` +To run it on Anthropic instead, switch `engine`/`model` in `spec.yaml` (see the +comment there) and export `ANTHROPIC_API_KEY` — the command and output shape are +unchanged. That engine-swap is the portability the spec buys you. + ## Try it as a skill Copy this directory into your agent's skills location (e.g. diff --git a/examples/skill-wrapper/SKILL.md b/examples/skill-wrapper/SKILL.md index 7a40a71..994b58e 100644 --- a/examples/skill-wrapper/SKILL.md +++ b/examples/skill-wrapper/SKILL.md @@ -16,7 +16,9 @@ execute the spec so the output shape is guaranteed. ## Prerequisites The `oa` CLI must be available (`pipx install open-agent-spec` or -`npm i -g @prime-vector/open-agent-spec`) with an `OPENAI_API_KEY` set. +`npm i -g @prime-vector/open-agent-spec`) with an API key set for the spec's +engine — `OPENAI_API_KEY` as shipped, or `ANTHROPIC_API_KEY` if the spec is +switched to the Anthropic engine. ## How to use diff --git a/examples/skill-wrapper/spec.yaml b/examples/skill-wrapper/spec.yaml index ea83d3b..1dcf685 100644 --- a/examples/skill-wrapper/spec.yaml +++ b/examples/skill-wrapper/spec.yaml @@ -12,6 +12,12 @@ intelligence: type: llm engine: openai model: gpt-4o-mini + # Portability is the point: the contract below is engine-agnostic. Swap the + # two lines above for Anthropic (set ANTHROPIC_API_KEY instead of + # OPENAI_API_KEY) and everything else — schemas, prompts, output shape — + # stays identical: + # engine: anthropic + # model: claude-haiku-4-5-20251001 tasks: summarise: From ad0a487b61bd8bbde6ca7305e282b0957b0e95fb Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 11 Jul 2026 10:45:27 +0000 Subject: [PATCH 3/3] docs: restore both-runtime conformance claims; accept markdown-interop proposal Reverts the two doc downgrades from the previous commit, which were based on a pre-#82 branch view. The conformance harness (spec.conformance.harness.harness) and the node adapter have been on main since #82, and CI runs both runtimes, so the original wording was correct against main: - AGENTS.md: restore the both-runtime conformance command (harness.harness --adapter python --adapter node). - README.md: restore "certified identical across runtimes". The skill-wrapper engine-swap docs are kept. Also flips the markdown-interop proposal to Status: Accepted, since merging the README positioning accepts it. Addresses review feedback from @aswhitehouse on #86. --- AGENTS.md | 5 ++--- README.md | 2 +- docs/proposals/markdown-interop.md | 2 +- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 52032a0..7b4e8c6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,9 +46,8 @@ mypy oas_cli tests # npm runtime: build and typecheck cd npm && npm ci && npm run build -# Conformance suite (runtime-agnostic cases; executes them against the Python runtime) -python -m spec.conformance.runner.conformance_runner -python -m spec.conformance.runner.conformance_runner --list # list all cases +# Conformance suite (certifies both runtimes against the standard) +python -m spec.conformance.harness.harness --adapter python --adapter node ``` ## Conventions diff --git a/README.md b/README.md index 39ec51e..0ed8635 100644 --- a/README.md +++ b/README.md @@ -472,7 +472,7 @@ The markdown agent patterns (AGENTS.md, SKILL.md) are prose guidance interpreted by a model at runtime: quick to write, but unvalidated, unenforceable, and untestable. OA operates one layer below them as the execution contract — input/output schemas, pinned models, runner-enforced -sandboxing, and structured errors, pinned to a shared, runtime-agnostic +sandboxing, and structured errors, certified identical across runtimes by a [conformance suite](spec/conformance/README.md). The two layers compose cleanly, following one rule: diff --git a/docs/proposals/markdown-interop.md b/docs/proposals/markdown-interop.md index 87143e2..0fe08e3 100644 --- a/docs/proposals/markdown-interop.md +++ b/docs/proposals/markdown-interop.md @@ -1,6 +1,6 @@ # Proposal: Interop with AGENTS.md and Skills (Markdown Agent Patterns) -**Status:** Proposed +**Status:** Accepted **Scope:** Documentation and examples only — zero schema or runtime changes **Author:** Prime Vector / Open Agent Spec maintainers