moai-ref-api-patterns

REST/GraphQL API design patterns, error handling conventions, and input validation reference for backend development. Agent-extending skill that amplifies backend domain work (spawned via Agent(general-purpose) with backend instructions) with production-grade API patterns. Use when designing APIs, implementing endpoints, or reviewing backend code. NOT for: frontend development, DevOps, database schema design, security audits.

Quality

85%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

82%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content is a lean, well-organized reference of API patterns with concrete JSON examples, named tools, and explicit verification checkpoints. Its main weakness is that progressive disclosure is declared in frontmatter but not realized through any external bundle files.

Suggestions

Split the larger reference tables (HTTP status codes, input validation checklist, rate limiting) into a references/ file and link from SKILL.md to honor the declared progressive_disclosure token levels.

Add an explicit error-recovery feedback loop to the Verification section (e.g., 'If validation fails: fix the offending endpoint and re-run the checklist') to push workflow clarity higher.

Include at least one end-to-end executable example (e.g., a minimal validated handler returning the standard error envelope) to move actionability from concrete patterns to fully runnable code.

Dimension	Reasoning	Score
Conciseness	The body is lean and table/code-driven with no padding explaining concepts Claude already knows (no 'what is HTTP' prose); terse rules and the Hyrum's Law line each earn their tokens. Matches the 5 anchor; not a 4 because there are no meaningful instances of over-explanation to trim.	5 / 5
Actionability	Provides concrete, copy-paste-ready JSON error and pagination formats, specific header names, named tools (Zod, Joi, pydantic, Prisma, GORM), and concrete rate limits. Not a 5 because it is reference patterns rather than fully executable end-to-end scripts; not a 3 because the examples are concrete and complete rather than pseudocode.	4 / 5
Workflow Clarity	As a reference skill there is no multi-step destructive workflow, but the Verification section supplies explicit checkpoints ('All endpoints follow consistent naming', 'Error responses use a standard format'). Matches the 4 anchor with most checkpoints present and minor gaps; not a 5 because no error-recovery feedback loop is sequenced, and not a 3 because checkpoints are explicit rather than missing.	4 / 5
Progressive Disclosure	No bundle files exist (references/, scripts/, assets/ absent) yet the body is well-organized with clear section headers and self-contained reference tables. Matches the 4 anchor for good structure with minor gaps; not a 5 because the frontmatter declares progressive-disclosure token levels implying split content that is not actually split into external files, and not a 3 because sections are clearly organized rather than buried.	4 / 5
	Total	17 / 20 Passed

Description

87%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description clearly states both capabilities and trigger conditions, with strong third-person voice and explicit exclusions that bound the skill's scope. It is concise, concrete, and unlikely to trigger for the wrong domain.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions ('designing APIs, implementing endpoints, or reviewing backend code') alongside a clear domain ('REST/GraphQL API design patterns, error handling conventions, and input validation'), with minor gaps in coverage such as documenting or versioning. Not a 5 because the action list is not fully comprehensive; not a 3 because more than 1-2 concrete actions are named.	4 / 5
Completeness	Explicitly answers both 'what' (REST/GraphQL API design patterns, error handling conventions, input validation reference) and 'when' ('Use when designing APIs, implementing endpoints, or reviewing backend code') with concrete trigger phrases, plus explicit exclusions. Matches the 5 anchor; not a 4 because the 'when' clause is concrete rather than merely present.	5 / 5
Trigger Term Quality	Good coverage of natural terms a user would say ('designing APIs', 'implementing endpoints', 'reviewing backend code', 'REST', 'GraphQL'), with a few natural synonyms or extension-style triggers missing. Not a 5 because common variations/synonyms are not exhaustively covered; not a 3 because the keyword set is clearly relevant rather than partially missing.	4 / 5
Distinctiveness Conflict Risk	Carves a clear niche (API design patterns reference) and adds explicit boundary guidance ('NOT for: frontend development, DevOps, database schema design, security audits'), minimizing conflict risk. Matches the 5 anchor; not a 4 because the explicit NOT-for list pushes overlap risk below 'minor'.	5 / 5
	Total	18 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: modu-ai/moai-adk
Path: .claude/skills/moai-ref-api-patterns/SKILL.md
Commit: 4100d87

Reviewed: 2 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.