xoai/api
skills/api/SKILL.md
Corrects the 13 most common API design mistakes agents make — grounded in Geewax, Amundsen, Ousterhout, Kleppmann, and Gough/Bryant
$ install --global
skillsauthnpx skillsauth add xoai/sage apiInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 25, 2026, 1:59 PM132.0s6 files scanned
SKILL.md
- name:
- api
- description:
- Corrects the 13 most common API design mistakes agents make — grounded in Geewax, Amundsen, Ousterhout, Kleppmann, and Gough/Bryant
- version:
- 2.0.0
- type:
- knowledge
- layer:
- domain
- sage:
- >=1.0.0
- detected:
- [express, fastify, koa, hono, django, flask, rails, spring, gin, echo, actix-web, axum]
- tags:
- [express,fastify,koa,hono,django]
api
Layer 1 — Domain Foundation (v2.0)
Corrects the 13 most common API design mistakes agents make, grounded in 5 authoritative sources:
- Geewax (API Design Patterns) — cursor pagination, error structure, idempotency, request deduplication
- Amundsen (RESTful Web API Cookbook) — PUT for idempotent creates, HTTP method semantics
- Ousterhout (Philosophy of Software Design) — information hiding, define errors out of existence, different layer/different abstraction
- Kleppmann (Designing Data-Intensive Applications) — network failures are normal, batch processing, data integrity
- Gough/Bryant (Mastering API Architecture) — schema validation, API lifecycle, backward compatibility, deprecation
What's Included
| Type | Count | Coverage | |------|-------|----------| | Patterns | 13 | Error envelope, input validation, cursor pagination, batch queries, auth-first, URL conventions, rate limiting, idempotent writes, separate representation, versioning, HTTP status codes, structured logging, health endpoints | | Anti-patterns | 9 | Inconsistent errors, trusting input, returning all records, N+1 loops, bolt-on auth, non-idempotent creates, leaking DB internals, 200-with-error-body, no versioning plan | | Constitution | 11 | principles |
Every pattern includes code examples showing wrong vs right approaches. Every anti-pattern includes root cause explaining WHY agents default to the wrong behavior.
Related Skills
xoai/git-discipline
development
VerifiedTrustedCommunity
Branch-per-initiative git discipline for all delivery workflows. Defines branch naming by workflow, the propose-confirm creation protocol, dirty-tree and detached-HEAD handling, the always user-gated merge protocol, worktree support for parallel sessions, and abandonment cleanup. Activates only in git repositories — silently inactive everywhere else. Use when starting /build, /fix, /architect, or /build-x at Standard+ scope, when resuming an initiative, when offering a merge at a completion checkpoint, or when the user wants a second concurrent initiative.
18SKILL.mdUpdated Jun 13, 2026
xoai/build-loop
development
VerifiedTrustedCommunity
Drives task-by-task execution from an approved plan with quality gates between each task. Reads the plan, finds the next incomplete task, dispatches implementation, validates, updates progress, and continues. Use after a plan is approved and the user says "go", "start building", "execute the plan", or "implement the feature".
18SKILL.mdUpdated Apr 25, 2026
xoai/session-bridge
testing
VerifiedTrustedCommunity
Preserves and restores context across agent sessions using plan file checkboxes as source of truth. Use when starting a new session, resuming previous work, ending a session, or when the user says "continue from last time", "what was I doing", or "save progress".
18SKILL.mdUpdated Apr 25, 2026
xoai/sage-self-learning
tools
VerifiedTrustedCommunity
Captures agent mistakes, corrections, and discovered gotchas so they are not repeated. Use when: (1) a command or operation fails unexpectedly, (2) the user corrects the agent, (3) the agent discovers non-obvious behavior through debugging, (4) an API or tool behaves differently than expected, (5) a better approach is found for a recurring task. Also searches past learnings before starting tasks to avoid known pitfalls. Activate alongside the sage-memory skill — they share the same MCP backend but serve different purposes (sage-memory = codebase knowledge, sage-self-learning = agent mistakes and gotchas).
17SKILL.mdUpdated May 20, 2026