SkillCurated by metahubEval warningsprompts

api-design-reviewer

Name: api-design-reviewer
Author: oxbshw

Use when reviewing a proposed REST or GraphQL API change before merge — checks contract clarity, backwards compatibility, errors, pagination, auth, and naming.

pinned to #7f8ee3cupdated 2 months ago

7/11Verified publisherCurated by MetaHubActively maintainedLicensedDocumentedStructuredClean repo

Ask your AI client: “install skills/api-design-reviewer”.

Requires the metahub MCP server installed in your client. Set up MCP.

mh install skills/api-design-reviewer

metahub onboarded this repo on the author's behalf.

If you own github.com/oxbshw/LLM-Agents-Ecosystem-Handbook on GitHub, claim the listing to take over publishing. Your claim preserves the existing eval history and badges; only the curator label is replaced with verified-publisher on your next publish.

Claim this repo

Stars

533

Last commit

2 months ago

7f8ee3c

Latest release

published

2 months ago

#ai
#ai-agent
#ai-agents
#fine-tuning
#finetuning-llms
#freamework
#llm
#llmops
#local-development
#mcp-server
#memory
#rag
#rag-chatbot
#voice-agent

Evaluation report

WarningsView full report

Automated checks the publisher passed at publish time — structure, docs, safety, and whether the artifact behaves as claimed.7f8ee3c· 2 months ago

Behavioral checks ran but aren't published for this artifact; the static checks above ran at publish time.

Documentation

4 passed1 warning

README has usage / example sectionswarn
README has no Usage / Example / Quick start / Installation heading at any level
Add a `# Usage`, `## Quick start`, or similar section so end users can copy/paste a working invocation. Code blocks alone work too if there are several.
Description quality
23 words · 159 chars — "Use when reviewing a proposed REST or GraphQL API change before merge — checks c…"
README is present and substantial
19,199 chars · 20 sections · 2 code blocks
Tags / topics declared
14 total — ai, ai-agent, ai-agents, fine-tuning, finetuning-llms, freamework (+8)
Homepage / docs URL declared
no homepage declared (registry will use the repo URL) — info-only, not blocking

Release history

releasecurrent7f8ee3cwarn2 months ago

View on GitHub

When to use

A new endpoint / mutation / schema is being proposed
A breaking change is on the table
An API draft needs a second pair of eyes before stakeholder review

When NOT to use

Pure implementation details (use repo-auditor)
UI / UX feedback
Cost / SLA tradeoffs (those need product discussion)

Inputs

Name	Type	Required	Notes
`spec`	path or text	yes	OpenAPI / GraphQL SDL / Markdown design doc
`mode`	`"public"` \| `"internal"`	no	Default `internal`. `public` raises the bar on backwards-compat.

Outputs

A Markdown review with sections: Critical, Important, Nits, Open questions.

Workflow

Parse the spec; list the operations / types touched
For each operation, walk references/api-review-checklist.md:
- Naming consistent with neighbors?
- Resource model coherent?
- Errors enumerated and typed?
- Pagination present (where lists are returned)?
- Auth + authz documented?
- Idempotency on writes?
- Versioning strategy?
For breaking changes, surface the contract delta explicitly
Group findings into Critical (blockers), Important (should fix), Nits (style)
Append Open questions for the author

References

references/api-review-checklist.md

Success criteria

0 fabricated findings (every finding cites a section of the spec)
Critical/Important findings have a concrete suggested fix
Tone is collegial, not pedantic

Failure modes

Spec too large (> 200 ops) → split into modules and ask the author which to focus on
Internal jargon in the spec without definitions → list as Open questions, don't guess

Examples

Good: "Critical — GET /users returns an unbounded list. Add cursor pagination (suggested: ?cursor=...&limit=...)."
Bad: "I think pagination might be useful here."