feat(skills): add OpenAPI SSOT api-documentation skill#10
Merged
Conversation
Add a distributable `update-api-documentation` skill that documents external API contracts from a single source of truth (docs/openapi.yml), with generated Redoc HTML, docs:validate/docs:build tasks, and a CI step. The guide is stack-agnostic (Rails/Node/Python examples) and follows the code→OpenAPI mapping so agents update docs alongside code. Wired into the CLI as a seed file (created on init, never overwritten, tracked by update), mirroring the bug-reproduction pattern: - src/commands/init.sh: mkdir + download_if_missing - src/commands/update.sh: seed_templates entry - templates/CLAUDE.md: Additional Context reference - rebuilt bundled dotcontext executable Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Warning Review limit reached
More reviews will be available in 44 minutes and 11 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (4)
WalkthroughThis PR adds a new "update-api-documentation" skill template for OpenAPI single-source-of-truth (SSOT) workflows. The skill is seeded during project initialization, included as a create-only template during updates, and referenced in the project's guidance documentation. ChangesAPI Documentation (OpenAPI SSOT) Skill
🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
# Conflicts: # dotcontext # src/commands/init.sh # templates/CLAUDE.md
6 tasks
nicholastn1
added a commit
that referenced
this pull request
Jun 3, 2026
…0.17.0 PR #10 merged after v0.16.0 with no release of its own, so the skill first ships in v0.17.0; give it a proper entry instead of only a passing mention.
nicholastn1
added a commit
that referenced
this pull request
Jun 3, 2026
* feat(2b): add name/description frontmatter to all skills (discovery)
All SKILL.md files now carry YAML frontmatter so the model can auto-discover
skills by description across agents (not just explicit /name). ADR-018 item 4
done. First increment of phase 2b.
* feat(2b): multi-agent commands (hybrid) + skill discovery
- skills: name/description frontmatter on all SKILL.md → auto-discovery on every
agent (done earlier in this branch).
- commands (hybrid, ADR-018): opencode → .opencode/command/*.md, Copilot →
.github/prompts/*.prompt.md (native copies of the canonical workflow prompts);
Gemini/Cursor/Codex → new "## Workflows" section in AGENTS.md. Claude keeps
.claude/commands/. Per selected harness, create-only.
- registry: emit_agent_commands + DOTCONTEXT_COMMANDS; init wires it in.
- --version --json: + commands:true. ADR-018 Accepted.
- bump 0.17.0 + CHANGELOG.
Deferred (recorded in ADR-018): code-review/deep-context → skill-mode promotion;
per-agent TOML/skill command transforms for Gemini/Cursor/Codex.
* fix(2b): /add-skill generates name/description frontmatter
/add-skill produced the old format (# Skill: … with no YAML frontmatter), so
newly created skills wouldn't be auto-discoverable — inconsistent with the
frontmatter now required across agents. Updated the command to emit
name/description frontmatter (description front-loaded for discovery) and noted
the .agents/skills mirror for non-Claude agents.
* docs(changelog): note /add-skill format update in v0.17.0
* fix(2b): consistency sweep — kill stale CLAUDE.md/Claude-only references
Functional (commands were reading/writing the now-stub CLAUDE.md):
- setup-context: writes project instructions to AGENTS.md (was CLAUDE.md)
- fix-bug, execute-prp, deep-context, code-review: read AGENTS.md (canonical)
- doctor: Claude CLI missing → warn not fail; commands check is harness-aware
(no false failure for valid non-Claude projects)
User-facing text:
- help.sh tagline/init desc/section header → multi-agent
- update.sh MCP prompt "for your agents"
- README: taglines, AGENTS.md canonical, 4-skill tree, per-harness commands row,
conditional setup-context launch, per-agent notifications
- CLAUDE.md: tagline, init --agents / --version --features, template-init mapping,
multi-agent integration section
- CONTEXT.md: tagline, AGENTS.md canonical entity, command entity
ADRs reconciled:
- ADR-003: drop --force (contradicted its own v2.0); doctor not "status" cmd
- ADR-004: note extended beyond Claude by 016/017/018 + Related
- ADR-005: cross-agent note ({{ASK}} via ADR-018) + Related
- ADR-015: multiagent/skills/hooks/commands now true; drop "(forthcoming)"
- ADR-016/018: fix dangling "ADR-005 v2.0" ref → ADR-018; status/History consistency
* docs: add CONTRIBUTING.md (skill-first, full deploy/release flow)
Leads with the most common contribution — adding a skill (SKILL.md frontmatter,
init/update wiring, .agents/.claude mirror, build) — then covers other
contributions, local dev, PR workflow, decision compliance, and the deploy model
(templates live on merge; CLI binary + release via tag-triggered release.yml;
merge != release). Includes issue/PR guidance and community expectations per
GitHub's contributing-guidelines recommendations.
* docs: add issue templates + PR template
- .github/ISSUE_TEMPLATE/: bug_report + feature_request (skill/harness-aware) + config (links to CONTRIBUTING)
- .github/PULL_REQUEST_TEMPLATE.md: summary/changes/type/checklist (incl. the make-build-in-sync reminder CI enforces) + test plan
* docs: humanize CONTRIBUTING.md and README multi-agent section
Remove AI-writing tells (em-dash overuse, signposting, inline-header dashes,
rule-of-three, generic bookends) per the humanizer guide. Keeps the technical
content and tone; just reads less like generated text.
* feat(release): use CHANGELOG.md section for release notes
Squash-merges collapse history, so git-log-based notes were one line. Pull the
matching CHANGELOG.md section as the release body instead (fall back to git log
when absent), and keep the Full Changelog compare link. Docs/ADR-014 updated.
* docs(changelog): round out v0.17.0 entry to cover the whole PR
The release notes come from this section, so it must reflect everything shipping
in v0.17.0: phase 2b + the consistency fixes, doctor non-Claude fix, CONTRIBUTING,
issue/PR templates, humanized docs, and the CHANGELOG-based release notes.
* docs(changelog): credit the update-api-documentation skill (#10) in v0.17.0
PR #10 merged after v0.16.0 with no release of its own, so the skill first ships
in v0.17.0; give it a proper entry instead of only a passing mention.
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.
Summary
Adds a new distributable skill —
update-api-documentation— that standardizes external API/webhook documentation around a single source of truth (docs/openapi.yml), with generated Redoc HTML, validation/build tasks, a CI step, and a recyclable guide so agents update docs alongside code.What's included
templates/.claude/skills/update-api-documentation/SKILL.mddocs/openapi.yml, generated Redoc HTML (never hand-edited),docs:validate/docs:buildtasks, CI step, code→OpenAPI mapping table, agent workflow, anti-patterns, bootstrap checklist, per-app variables/api/v1/*,/webhooks/*) — not admin/UI/jobs/healthCLI wiring
Follows the
bug-reproductionseed pattern — created oninit, never overwritten, tracked byupdate:src/commands/init.sh—mkdir+download_if_missingsrc/commands/update.sh— added toseed_templatestemplates/CLAUDE.md— reference in Additional Contextdotcontextexecutable (make build)Design decisions
dotcontext init), stack-agnostic (Rails as one example), SKILL.md only (the agent generatesopenapi.yml/tasks/HTML in the target project by following the guide).🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation