docs: interop with AGENTS.md and Skills (markdown agent patterns)

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.

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:

docs/proposals/markdown-interop.md

@@ -0,0 +1,114 @@
+# Proposal: Interop with AGENTS.md and Skills (Markdown Agent Patterns)
+
+**Status:** Accepted
+**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.

examples/skill-wrapper/README.md

@@ -0,0 +1,54 @@
+# 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."}'
+```
+
+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.
+`~/.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.

examples/skill-wrapper/SKILL.md

@@ -0,0 +1,55 @@
+---
+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 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
+
+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": "<the document 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.

examples/skill-wrapper/spec.yaml

@@ -0,0 +1,55 @@
+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
+  # 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:
+    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