Add sync-openapi-spec skill#50
Merged
hongyi-chen merged 2 commits intomainfrom May 9, 2026
Merged
Conversation
Adds a new skill at .agents/skills/sync-openapi-spec/ that compares
warp-server/public_api/openapi.yaml against developers/agent-api-openapi.yaml
(the file the Scalar API reference at docs.warp.dev/api renders from) and
regenerates the docs subset deterministically.
The skill is documented in SKILL.md, with the exclusion policy (which tags
and paths are kept vs dropped) recorded in references/sync-policy.md and
encoded in scripts/sync_openapi.py as EXCLUDED_TAGS / EXCLUDED_PATHS. The
script supports --mode {diff,apply,self-test}.
This PR ships only the skill itself. Running the skill (and updating
developers/agent-api-openapi.yaml) is intentionally a follow-up, so reviewers
can vet the policy before any changes land in the public API reference.
Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Audit-driven follow-up: - Add _validate_output() that walks the regenerated spec and fails if any $ref points at a missing component. Apply mode now exits with code 3 and refuses to overwrite the target on validation failure. - Self-test asserts no unresolved refs after transform. - Fix SKILL.md Step 5 wording: npm run build does not catch dangling $refs (Astro just YAML-parses the file). The new validator covers that case; npm run build remains a belt-and-braces integration check. - Update troubleshooting entry to match the new behavior. Co-Authored-By: Oz <oz-agent@warp.dev>
liliwilson
approved these changes
May 9, 2026
liliwilson
approved these changes
May 9, 2026
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
2 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.
What this changes
Adds a new skill at
.agents/skills/sync-openapi-spec/that keepsdevelopers/agent-api-openapi.yaml(the file rendered by Scalar atdocs.warp.dev/api) in sync with the canonical OpenAPI spec atwarp-server/public_api/openapi.yaml.Why
developers/agent-api-openapi.yamlis a hand-curated subset of the canonical spec, with no tooling to detect drift today. The header comment onsrc/pages/api.astroalready calls it out as "synced from the upstream Oz Agent API source... Re-sync that file when the API changes," but there's been no skill, script, or workflow to actually do the re-sync — so it has drifted from the source.A quick
--mode diffrun againstdevelopof warp-server confirms real drift today: 3 paths whose operations have moved on, 3 schemas added in source that are missing from docs (e.g.AgentRunMode,SecretRef,SessionSharingConfig), and 11 schemas in the docs file that aren't in the source subset anymore (mostlyharness-supportartifacts).What's in this PR
SKILL.md— workflow doc (modeled onsync-error-docs/SKILL.md): prereqs, diff/triage/apply/validate/PR steps, troubleshooting.scripts/sync_openapi.py— Python 3 / pyyaml-based diff & apply tool with three modes (diff,apply,self-test). Keeps theagentandschedulestags, dropsmemory_stores/harness-supportand a small list of internalagentpaths (followups,handoff,fork,redirect), and prunescomponents.schemasto only schemas reachable via transitive$refwalking. Preservesx-internal: trueoperations under public paths to match the file's existing behavior.references/sync-policy.md— rationale for each exclusion and instructions for adding/removing exclusions when new endpoints land.This PR ships only the skill. It does not modify
developers/agent-api-openapi.yaml. Running the skill end-to-end and updating that file is a deliberate follow-up so reviewers can vet the policy first.Validation
python3 .agents/skills/sync-openapi-spec/scripts/sync_openapi.py --mode self-test→self-test: OK--mode diffagainst the live source/target produces the drift report quoted in the "Why" section--mode applyagainst a temp file produces a parseable YAML with 24 paths / 76 schemas / tags[agent, schedules](matches the existing docs file's path set exactly)Conversation: https://staging.warp.dev/conversation/176cd75e-155b-466f-8c14-871b799b7271
Run: https://oz.staging.warp.dev/runs/019e09f3-7262-7aa6-86ff-5b8f6f78da68
Plans:
sync-openapi-specskill to docs repoThis PR was generated with Oz.