docs: interop with AGENTS.md and Skills (markdown agent patterns)#86
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
aswhitehouse
reviewed
Jul 9, 2026
aswhitehouse
left a comment
aswhitehouse
left a comment
Collaborator
There was a problem hiding this comment.
Thanks for picking this branch up and for the engine-portability additions — the spec.yaml comment showing the OpenAI→Anthropic swap with everything else unchanged is a genuinely good improvement, since portability is exactly the property the example exists to demonstrate.
One important correction though: the "fix" in 2999cde is based on a stale branch view, not a real gap. See inline comments — this branch was cut from 37e3607 (pre-#82), so spec.conformance.harness.harness didn't exist on the branch when you checked. It has been on main since #82 merged (2026-07-03), together with the node adapter and the CI job running both runtimes. So the original command and the original README claim ("certified identical across runtimes") were correct against main — the branch just needs a rebase, after which 2999cde's downgrades should be reverted.
On your two review notes:
- skill-wrapper e2e: correct that it hasn't had a live run — it passed
oa validatebut no keyed run yet. Agreed it should get oneoa runbefore merge; it's the same shape as the proven file-reader spec minus the tool, so low risk. - Proposed vs settled: fair catch. Merging the README positioning is accepting the proposal, so flip the doc to
Status: Acceptedin the merge commit rather than softening the README.
Summary of requested changes: rebase on main → revert the AGENTS.md command and README claim from 2999cde (keep the engine-swap docs) → one live oa run of the example → flip proposal status to Accepted.
aswhitehouse
self-requested a review
July 10, 2026 06:45
sgriffiths
pushed a commit
that referenced
this pull request
Jul 11, 2026
…p proposal Reverts the two doc downgrades from 2999cde that 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 from 2999cde 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. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XdPprn1xTRiR1rGZf4jUfP
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 <cursoragent@cursor.com>
… 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.
sgriffiths
pushed a commit
that referenced
this pull request
Jul 11, 2026
…p proposal Reverts the two doc downgrades from 2999cde that 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 from 2999cde 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. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XdPprn1xTRiR1rGZf4jUfP
sgriffiths
force-pushed
the
feat/markdown-interop
branch
from
July 11, 2026 22:45
61e8e30 to
aa26a7f
Compare
…p 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.
sgriffiths
force-pushed
the
feat/markdown-interop
branch
from
July 12, 2026 05:41
aa26a7f to
ad0a487
Compare
aswhitehouse
self-requested a review
July 12, 2026 10:29
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Docs and examples only — zero schema or runtime changes.
What this adds
docs/proposals/markdown-interop.md— position OA relative to AGENTS.md / SKILL.md, with the bright-line rule: markdown patterns may point at OA specs; OA specs never point at markdown patterns.AGENTS.md— dogfoods the pattern: directs coding agents to define behaviour as OA specs and run them via the CLI, plus contributor dev/test commands.examples/skill-wrapper/— aSKILL.mdthat wraps a typed, validated OA spec (spec.yaml) instead of improvising summarisation, with a README explaining the division of labour.Follow-up fixes on this branch (commit 2999cde)
AGENTS.md— it referenced a non-existent module/flags; now uses the real entry pointpython -m spec.conformance.runner.conformance_runner, and the wording reflects that the runtime-agnostic cases run against the Python runtime.spec.yamlcomment,SKILL.mdprerequisites, example README) to show the contract is engine-portable.Notes for review
spec.yamlparses and matches the schema shape, but has not been run end-to-end (oa run) — worth confirming via CI or a manual run before merge.Status: Proposedwhile the README ships the positioning as settled — decide whether to flip it toAcceptedor soften the README.