Agent skill

Moai Ref API Patterns

by modu-ai in modu-ai/moai-adk

REST/GraphQL API design patterns, error handling conventions, and input validation reference for backend development.

Apache-2.0Auto-check passedBackend & APIs

Install Moai Ref API Patterns

skills CLI
$ npx skills add modu-ai/moai-adk --skill moai-ref-api-patterns -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install modu-ai/moai-adk moai-ref-api-patterns --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/modu-ai/moai-adk.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/moai-ref-api-patterns .claude/skills/moai-ref-api-patterns && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
moai-ref-api-patterns
GitHub stars
1.2k
Token cost
~1.9k tokens
SKILL.md length
648 words
Files
1
Skills in repo
48
Repo updated
First seen
Licence
Apache-2.0

At a glance

REST/GraphQL API design patterns, error handling conventions, and input validation reference for backend development.

  • Implementing endpoints
  • SKILL.md covers Target Spawn, RESTful API Design Conventions, HTTP Status Code Guide and Error Response Format, plus 7 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
  • Reviewing backend code

What it does

Moai Ref API Patterns is an agent skill from modu-ai/moai-adk. 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.

Its SKILL.md is about 1.9k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Backend & APIs, covering Design patterns, Frontend development and GraphQL. It works with GraphQL. The repository describes itself as: Agentic development harness for Claude Code — SPEC-driven plan/run/sync, TRUST 5 quality gates, model+effort routing, and Claude×GLM multi-LLM cost control. Single Go binary, 16… The licence is Apache-2.0.

When your agent uses it

  • Implementing endpoints
  • Reviewing backend code

Example prompts

  • “/moai-ref-api-patterns”

What it can do on your machine

Read from SKILL.md and the folder at commit 6c55321. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are json).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Moai Ref API Patterns loads about 1.9k tokens when it runs. Until then it costs about 113 tokens; SKILL.md has 648 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~113
When it runs · the whole SKILL.md, loaded when a task matches
~1.9k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from modu-ai/moai-adk at commit 6c55321, republished under its Apache-2.0 licence (© modu-ai). 648 words, ~1,881 tokens.

Download SKILL.mdSave it as .claude/skills/moai-ref-api-patterns/SKILL.md (or your agent's skills folder).
name
moai-ref-api-patterns
description
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.
when_to_use
Use for REST/GraphQL API design patterns: endpoint and route design, handler structure, request/response conventions, error handling, and input validation…
user-invocable
false
metadata.version
1.0.0
metadata.category
domain
metadata.status
active
metadata.updated
2026-03-30
metadata.tags
api, rest, graphql, patterns, backend, reference
progressive_disclosure.enabled
true
progressive_disclosure.level1_tokens
100
progressive_disclosure.level2_tokens
3000

API Patterns Reference

Target Spawn

Backend domain work spawned via Agent(general-purpose) with backend instructions - Applies these patterns directly to API implementation and review.

RESTful API Design Conventions

PrincipleConventionExample
Resource NamingPlural nouns, lowercase, kebab-case/api/v1/user-profiles
CollectionGET returns array with paginationGET /users?page=1&limit=20
Single ResourceGET returns objectGET /users/{id}
CreatePOST to collectionPOST /users
Update (full)PUT to resourcePUT /users/{id}
Update (partial)PATCH to resourcePATCH /users/{id}
DeleteDELETE to resourceDELETE /users/{id}
Nested ResourcesMax 2 levels deep/users/{id}/posts
FilteringQuery params?status=active&role=admin
SortingSort param?sort=-created_at,name
VersioningURL prefix/api/v1/, /api/v2/

HTTP Status Code Guide

CategoryCodeWhen to Use
Success200 OKSuccessful GET, PUT, PATCH, DELETE
Success201 CreatedSuccessful POST (resource created)
Success204 No ContentSuccessful DELETE (no body)
Client Error400 Bad RequestMalformed request, validation failure
Client Error401 UnauthorizedMissing or invalid authentication
Client Error403 ForbiddenAuthenticated but not authorized
Client Error404 Not FoundResource does not exist
Client Error409 ConflictResource state conflict (duplicate)
Client Error422 UnprocessableValid syntax but semantic error
Client Error429 Too ManyRate limit exceeded
Server Error500 InternalUnexpected server error
Server Error503 Service UnavailableMaintenance or overload

Error Response Format

json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Input validation failed",
    "details": [
      {"field": "email", "message": "Must be a valid email address"},
      {"field": "age", "message": "Must be between 0 and 150"}
    ],
    "request_id": "req_abc123"
  }
}

Rules:

  • Never expose stack traces or internal details in production
  • Always include request_id for traceability
  • Use consistent error codes (ENUM, not free text)
  • Login failures: "Invalid email or password" (never reveal which)

Pagination Pattern

json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8,
    "has_next": true,
    "has_prev": false
  }
}

For cursor-based (large datasets):

json
{
  "data": [...],
  "cursor": {
    "next": "eyJpZCI6MTAwfQ==",
    "has_more": true
  }
}

Input Validation Checklist

ValidationMethodTool
Type validationSchema validationZod, Joi, pydantic, Go validator
Length limitsMin/max constraintsSchema min/max
Pattern matchingRegexEmail, URL, phone patterns
Range validationNumber/date boundsmin/max values
EnumerationAllowed valuesenum types
SQL InjectionParameterized queriesORM (Prisma, GORM, SQLAlchemy)
XSSHTML escapingTemplate engines, DOMPurify
Path TraversalPath normalizationfilepath.Clean + whitelist

Rate Limiting Strategy

TargetLimitKey
Auth endpoints5 req/minIP
General API100 req/minUser token
File upload10 req/hourUser token
Public API30 req/minIP

Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After (on 429).

API Versioning Strategy

StrategyUse CaseExample
URL prefixMost APIs/api/v1/users
HeaderInternal APIsAccept: application/vnd.api+json; version=2
Query paramSimple APIs/users?version=2

Breaking changes that require version bump:

  • Removing or renaming fields
  • Changing field types
  • Removing endpoints
  • Changing authentication methods

Non-breaking changes (no version bump needed):

  • Adding new optional fields
  • Adding new endpoints
  • Adding new query parameters
<!-- moai:evolvable-start id="rationalizations" -->
Show full SKILL.md (257 more words)Show less

Common Rationalizations

RationalizationReality
"REST naming conventions are just aesthetics"Consistent resource naming is how clients discover and predict endpoints. Inconsistency multiplies documentation burden.
"GraphQL solves over-fetching, so I do not need to design response shapes"GraphQL shifts complexity to the resolver layer. Poorly designed schemas create N+1 queries and authorization gaps.
"Error codes are internal details, clients just need the message"Clients need machine-readable error codes for programmatic handling. Messages are for humans, codes are for code.
"PATCH and PUT are interchangeable"PATCH applies partial updates; PUT replaces the entire resource. Using them incorrectly breaks idempotency expectations.
"I will version the API when it becomes necessary"Versioning after breaking changes forces emergency migrations. Plan versioning from the first release.

Hyrum's Law: Every observable API behavior will eventually be depended on by clients. Undocumented response fields, error formats, and timing characteristics become implicit contracts.

<!-- moai:evolvable-end -->
<!-- moai:evolvable-start id="red-flags" -->

Red Flags

  • API returns different error formats across endpoints
  • Resource names use verbs instead of nouns (e.g., /getUser instead of /users/:id)
  • No pagination on list endpoints that can return unbounded results
  • Breaking change deployed without API version bump
  • GraphQL schema allows unbounded depth or circular queries without limits
<!-- moai:evolvable-end -->
<!-- moai:evolvable-start id="verification" -->

Verification

  • All endpoints follow consistent naming convention (nouns, plurals, nested resources)
  • Error responses use a standard format with machine-readable error code
  • List endpoints implement pagination with documented limits
  • API versioning strategy present and enforced (URL path, header, or query param)
  • Breaking vs non-breaking change classification documented for recent changes
  • Input validation returns 400 with specific field-level error details
<!-- moai:evolvable-end -->

© modu-ai, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .claude/skills/moai-ref-api-patterns of modu-ai/moai-adk.

Open the folder on GitHubat commit 6c55321

Compare with similar skills

Moai Ref API Patterns next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Moai Ref API Patterns compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Moai Ref API Patterns this skillmodu-ai/moai-adk1.2k—~1.9kAutomated safety check: PassApache-2.0
Senior Backendalirezarezvani/claude-skills28k1 repos~3.8kAutomated safety check: PassMIT
Nestjsgiuseppe-trisciuoglio/developer-kit355—~1.4kAutomated safety check: NotesMIT
Nodejs Backend Patternsever-works/ever-works15817 repos~4kAutomated safety check: PassAGPL-3.0
API Design Principlesjh941213/my-cc-harness12619 repos~3.4kAutomated safety check: PassNone
Twenty Syncable Entity Wiringtwentyhq/twenty58k—~2.9kAutomated safety check: PassCustom licence

Similar skills

  • Senior Backend

    alirezarezvani/claude-skills

    Designs and implements backend systems including REST APIs, microservices, database architectures, authentication flows, and security hardening.

    28k GitHub starsUsed in 1 repo~3.8k tokens
    Backend & APIsAuto-check passed
  • Nestjs

    giuseppe-trisciuoglio/developer-kit

    Provides comprehensive NestJS framework patterns with Drizzle ORM integration for building scalable server-side applications.

    355 GitHub stars~1.4k tokensUpdated 27 days ago
    Backend & APIsAuto-check: notes
  • Nodejs Backend Patterns

    ever-works/ever-works

    Build production-ready Node.js backend services with Express/Fastify, implementing middleware patterns, error handling, authentication, database integration, and API design best practices.

    158 GitHub starsUsed in 17 repos~4k tokens
    Backend & APIsAuto-check passed
  • API Design Principles

    jh941213/my-cc-harness

    REST 및 GraphQL API 설계 원칙 가이드. An agent skill from jh941213/my-cc-harness.

    126 GitHub starsUsed in 19 repos~3.4k tokens
    Backend & APIsAuto-check passed
  • Registers a new syncable entity in three NestJS modules and adds its service and GraphQL resolver layers when contributing to the Twenty server.

    58k GitHub stars~2.9k tokensUpdated today
    Backend & APIsAuto-check passed
  • Phoenix Server

    Arize-ai/phoenix

    Backend development guide for the Phoenix AI observability platform (Strawberry GraphQL, SQLAlchemy async, FastAPI).

    12k GitHub stars~1.6k tokensUpdated today
    Backend & APIsAuto-check passed

More from modu-ai/moai-adk

All 48 skills in this repo
  • Builds hand-editable SVG diagrams from computed layout coordinates, lints the source and renders a 2x PNG, with rules for when mermaid is the better choice.

    1.2k GitHub stars~5.2k tokensUpdated today
    Auto-check: notes
  • MoAI Foundation Core

    modu-ai/moai-adk

    Reference for MoAI-ADK's core development principles: TRUST 5 quality gates, SPEC-first domain-driven workflow, agent delegation and token budgeting.

    1.2k GitHub stars~5k tokensUpdated today
    Auto-check passed
  • MoAI SPEC Workflow

    modu-ai/moai-adk

    Manages SPEC documents for MoAI-ADK development, with GEARS or EARS requirement notation, acceptance criteria and a link into the Plan-Run-Sync workflow.

    1.2k GitHub stars~5.1k tokensUpdated today
    Auto-check passed
  • MoAI TDD Workflow

    modu-ai/moai-adk

    Drives test-first development through the RED, GREEN, REFACTOR cycle, with a config switch that selects between TDD and a DDD workflow for existing code.

    1.2k GitHub stars~3.1k tokensUpdated today
    Auto-check passed
  • MoAI Worktree Management

    modu-ai/moai-adk

    Gives each SPEC its own Git worktree with a registry of active workspaces, base-branch sync and cleanup of merged ones, inside the MoAI-ADK workflow.

    1.2k GitHub stars~3.9k tokensUpdated today
    Auto-check passed
  • Watches a pull request's CI checks after creation, separates required from auxiliary failures, applies limited safe fixes and escalates anything semantic to you.

    1.2k GitHub stars~2.4k tokensUpdated today
    Auto-check: notes

Works with

Questions about Moai Ref API Patterns

What does Moai Ref API Patterns do?

REST/GraphQL API design patterns, error handling conventions, and input validation reference for backend development. Moai Ref API Patterns is an agent skill from modu-ai/moai-adk. REST/GraphQL API design patterns, error handling conventions, and input validation reference for backend development.

When should I use Moai Ref API Patterns?

Moai Ref API Patterns fits situations like: implementing endpoints; reviewing backend code.

How do I install Moai Ref API Patterns in Claude Code?

Run `npx skills add modu-ai/moai-adk --skill moai-ref-api-patterns -a claude-code`. Or copy the skill folder (.claude/skills/moai-ref-api-patterns in modu-ai/moai-adk) into .claude/skills/moai-ref-api-patterns in your project. Claude Code loads it when a task matches its description.

How do I install Moai Ref API Patterns in Codex?

Run `npx skills add modu-ai/moai-adk --skill moai-ref-api-patterns -a codex`. Or copy the skill folder (.claude/skills/moai-ref-api-patterns in modu-ai/moai-adk) into .agents/skills/moai-ref-api-patterns in your project. Codex loads it when a task matches its description.

Can I use Moai Ref API Patterns in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add modu-ai/moai-adk --skill moai-ref-api-patterns -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/moai-ref-api-patterns, .gemini/skills/moai-ref-api-patterns, .github/skills/moai-ref-api-patterns and .opencode/skills/moai-ref-api-patterns in your project.

What does Moai Ref API Patterns need to run?

SKILL.md names no scripts, command-line tools or credentials: Moai Ref API Patterns is instructions for the agent only.

Does Moai Ref API Patterns access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Moai Ref API Patterns safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Moai Ref API Patterns use?

Moai Ref API Patterns is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Moai Ref API Patterns use?

About 1.9k tokens (SKILL.md is roughly 7.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Moai Ref API Patterns?

Skills that share tags, products or a category with Moai Ref API Patterns: Senior Backend (alirezarezvani/claude-skills, 28k stars), Nestjs (giuseppe-trisciuoglio/developer-kit, 355 stars), Nodejs Backend Patterns (ever-works/ever-works, 158 stars) and API Design Principles (jh941213/my-cc-harness, 126 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Moai Ref API Patterns?

modu-ai (a GitHub organization) maintains it in modu-ai/moai-adk, which has 1,230 GitHub stars. The repository holds 48 skills in this directory. The repository was last updated on October 7, 2026.

Source: modu-ai/moai-adk on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.