CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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

82%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

71%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 body is a highly actionable, concrete reference with concrete schemas, tooling, and checklists, but it front-loads material Claude largely already knows (status codes, basic REST verbs) and inlines everything instead of realizing its declared progressive-disclosure structure. Splitting into reference files and pruning known-knowledge tables would raise both efficiency and structure scores.

Suggestions

Move the detailed tables (REST conventions, status codes, validation, rate limiting) into a references/ file and keep a concise overview in SKILL.md, matching the declared progressive_disclosure levels (level1 100 / level2 3000 tokens).

Trim or drop the HTTP status code guide and basic CRUD verb conventions — this is knowledge Claude already has; keep only project-specific conventions or non-obvious choices (e.g., 422 vs 400 policy).

Keep the error-response JSON schema, pagination schemas, and Verification checklist as the core inline content — they are the highest-value, most concrete material.

DimensionReasoningScore

Conciseness

Mostly efficient — tables and JSON blocks with no prose padding — but the "HTTP Status Code Guide" and parts of the REST conventions table restate knowledge Claude already has (200/201/404/409 semantics, POST-to-create), which is unnecessary explanation that could be trimmed. Not 4 because the redundancy is more than minor; not 2 because the material is dense reference, not verbose explanation.

3 / 5

Actionability

Fully concrete and copy-paste ready: complete JSON error and pagination schemas (both offset and cursor), named validation tools per threat (Zod, pydantic, DOMPurify, filepath.Clean), specific rate limits with exact header names, and explicit breaking/non-breaking change lists. Common cases are covered.

5 / 5

Workflow Clarity

As a single-purpose reference skill its use is unambiguous (apply these patterns during API design/review), and the Verification section provides a 6-item checklist of checkpoints. Not 5 because there is no sequenced workflow or error-recovery loop; not 3 because validation checkpoints are explicitly present, not merely implicit.

4 / 5

Progressive Disclosure

The body is well-sectioned and navigable, but ~150 lines of API reference tables are all inlined in SKILL.md with no bundle files at all, despite frontmatter declaring progressive_disclosure levels (level1 100 / level2 3000 tokens). This matches the anchor where content that could live in a separate reference file is inline. Not 4 because the declared disclosure structure is unrealized; not 2 because sections are clearly organized, not an unstructured wall.

3 / 5

Total

15

/

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 is strong: it states concrete capabilities, provides explicit use triggers, and fences its scope with a NOT-for list. Minor improvement is possible by adding more natural trigger synonyms.

Suggestions

Add a few natural trigger synonyms users would actually say, e.g. "API spec", "request/response design", "endpoint error format", to strengthen trigger term coverage.

Consider naming one or two concrete deliverables (e.g., "standardized error response format, pagination schema") to sharpen the what-portion of the description.

DimensionReasoningScore

Specificity

Names several concrete areas — "REST/GraphQL API design patterns, error handling conventions, and input validation" — matching the anchor for several specific items with minor gaps. Not 5 because it describes reference domains rather than a comprehensive list of concrete actions; not 3 because coverage goes well beyond 1-2 actions.

4 / 5

Completeness

Explicitly answers both: what ("REST/GraphQL API design patterns, error handling conventions, and input validation reference for backend development") and when ("Use when designing APIs, implementing endpoints, or reviewing backend code"), with concrete trigger phrases. The explicit NOT-for list further sharpens the boundary.

5 / 5

Trigger Term Quality

Includes natural phrases users would say — "Use when designing APIs, implementing endpoints, or reviewing backend code" — plus strong domain keywords (REST, GraphQL, backend, endpoints, error handling). Not 5 because it lacks synonyms and variations users might use (e.g., "API spec", "endpoint review", "request validation").

4 / 5

Distinctiveness Conflict Risk

Clear niche (backend API design/error/validation patterns) with an explicit exclusion fence — "NOT for: frontend development, DevOps, database schema design, security audits" — minimizing overlap with related skills.

5 / 5

Total

18

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

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

Reviewed

Table of Contents

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.