This repository contains an opinionated HTTP/REST API style guide packaged as a skill for AI coding agents. It gives agents concrete defaults for designing, implementing, documenting, evolving, deprecating, and reviewing HTTP APIs.
The guide favors pragmatic, codegen-friendly REST with design-first OpenAPI, resource-oriented modeling, Stripe-like ergonomics, and standards-based HTTP behavior.
- authoring/DECISIONS.md: resolved style decision register.
- authoring/OUTLINE.md: guideline and workflow map.
- authoring/DRAFTING.md: drafting order, page rules, and scope boundaries.
- authoring/TEMPLATE.md: required guideline page shape.
- SKILL.md: packaged skill entrypoint and root router.
- guidelines.md: packaged policy index.
- AGENTS.md: repository instructions for coding agents.
- Add or update a decision-register entry before changing the rule it owns.
- Draft or revise owner pages in the order defined by authoring/DRAFTING.md.
- Add workflow pages only where a repeated task needs a procedure, not just a rule.
- Keep each guideline routed exactly once from the policy index and each workflow routed exactly once from the skill entrypoint.
- Run
bash checks/check.shbefore committing skill changes.
The packaged guide can be browsed as an mdBook:
mdbook build
mdbook serve --openBook source lives under src/. Symlinks expose the canonical packaged
files without duplication, and a preprocessor removes SKILL.md frontmatter
from the rendered book.
The Pages workflow in .github/workflows/deploy.yml
builds and deploys pushes to main. Configure the repository's Pages source as
"GitHub Actions" before the first deployment.
SKILL.mdstays small and routes tasks through progressive disclosure.guidelines.mdindexes focused policy pages.guidelines/owns policy;workflows/owns multi-step procedures.agents/openai.yamlprovides UI metadata for the skill.authoring/,.ai/research/, and.ai/reviews/remain repository-only maintenance material.