Skip to main content
skill CX Codex

discover-api — Claude Code skill: automatic API design guidance

The discover-api skill activates eight specialized API modules automatically when you work with REST, GraphQL, authentication, or authorization. It bundles knowledge about rate limiting, versioning, and security patterns in one gateway.

MIT 113 installs ★ 193 updated 2026-02-28

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add rand/cc-polymath --skill discover-api -a claude-code
Open on GitHub

What discover-api does

discover-api is a progressive-loading gateway to eight API-focused modules: REST design, GraphQL schemas, authentication, authorization, rate limiting, versioning, error handling, and 35 opinionated design rules. When you write code for REST or GraphQL, configure JWT or OAuth, or implement access control, the skill activates and offers the relevant guidance without requiring you to search.

Each module loads on demand to keep context lean. The skill includes predefined workflows—for example, REST API from scratch suggests the sequence: design → authentication → authorization. It integrates with other skills like database, testing, and frontend modules to cover end-to-end development.

Supported on Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. Installation via npm requires Node.js.

What it helps with

  • decide between REST and GraphQL for a new service
  • model resources and HTTP methods correctly
  • set up JWT or OAuth 2.0 in production
  • implement role-based access control
  • prevent API abuse with rate limiting strategies

Example prompts for the agent

  • How should I structure a REST API for a marketplace with users, products, and reviews?
  • What's the right way to add OAuth to an existing Node API?
  • How do I enforce field-level permissions in GraphQL?

How to install discover-api

1Skills CLI (Vercel)

npx skills add rand/cc-polymath --skill discover-api -a claude-code

2Manually: put the files in place

~/.claude/skills/discover-api/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/discover-api/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about discover-api

How do I install discover-api in Claude Code?

Run npx skills add rand/cc-polymath --skill discover-api -a claude-code, then load the skill via ~/.claude/skills/discover-api/SKILL.md.

What does discover-api do?

It bundles eight API modules: REST design, GraphQL, JWT and OAuth, role-based access control, rate limiting, versioning, and error handling. The skill auto-activates when you work with API code.

What's the difference between api-authentication and api-authorization skills?

Authentication answers “who are you?”—login, JWT, OAuth, API keys. Authorization answers “what can you do?”—roles, permissions, policies.

Source text

SKILL.md · MIT
---
name: discover-api
description: Automatically discover API design skills when working with REST APIs, GraphQL schemas, API authentication, OAuth, JWT, rate limiting, API versioning, error handling, or endpoint design. Activates for backend API development tasks.
license: MIT
metadata:
  author: rand
  version: "4.0"
compatibility: Designed for Claude Code. Compatible with any agent supporting the Agent Skills format.
---

# API Skills Discovery

Provides automatic access to comprehensive API design, authentication, and implementation skills.

## When This Skill Activates

This skill auto-activates when you're working with:
- REST API design and implementation
- GraphQL schema design
- API authentication (JWT, OAuth 2.0, API keys, sessions)
- API authorization (RBAC, ABAC, permissions)
- Rate limiting and throttling
- API versioning strategies
- Error handling and validation
- HTTP methods, status codes, endpoints

## Available Skills

### Quick Reference

The API category contains 8 specialized skills:

1. **rest-api-design** - RESTful resource modeling, HTTP semantics, URL conventions
2. **graphql-schema-design** - GraphQL types, resolvers, N+1 problem prevention
3. **api-authentication** - JWT, OAuth 2.0, API keys, session management
4. **api-authorization** - RBAC, ABAC, policy engines, permission systems
5. **api-rate-limiting** - Token bucket, sliding window, rate limiting algorithms
6. **api-versioning** - API versioning, deprecation, backward compatibility
7. **api-error-handling** - RFC 7807 errors, validation, standardized responses
8. **api-design-rules** - 35 opinionated rules for API design

### Load Full Category Details

For complete descriptions and workflows:

Read ../api/INDEX.md


This loads the full API category index with:
- Detailed skill descriptions
- Usage triggers for each skill
- Common workflow combinations
- Cross-references to related skills

### Load Specific Skills

Load individual skills as needed:


# Core API design
Read ../api/rest-api-design.md
Read ../api/graphql-schema-design.md

# Security and access control
Read ../api/api-authentication.md
Read ../api/api-authorization.md

# Production hardening
Read ../api/api-rate-limiting.md
Read ../api/api-error-handling.md
Read ../api/api-versioning.md

# Rules and best practices
Read ../api/api-design-rules.md


## Common Workflows

### New REST API
**Sequence**: REST design → Authentication → Authorization

Read ../api/rest-api-design.md      # Resource modeling, HTTP methods
Read ../api/api-authentication.md   # User authentication
Read ../api/api-authorization.md    # Access control


### New GraphQL API
**Sequence**: GraphQL schema → Authentication → Authorization

Read ../api/graphql-schema-design.md  # Schema design, resolvers
Read ../api/api-authentication.md     # User authentication
Read ../api/api-authorization.md      # Field-level permissions


### API Hardening
**Sequence**: Rate limiting → Error handling → Versioning

Read ../api/api-rate-limiting.md    # Prevent abuse
Read ../api/api-error-handling.md   # Standardized errors
Read ../api/api-versioning.md       # Manage evolution


### Complete API Stack
**Full implementation from scratch**:


# 1. Design phase
Read ../api/rest-api-design.md

# 2. Security phase
Read ../api/api-authentication.md
Read ../api/api-authorization.md
Read ../api/api-rate-limiting.md

# 3. Production readiness
Read ../api/api-error-handling.md
Read ../api/api-versioning.md


## Skill Selection Guide

**Choose REST API skills when:**
- Building traditional web services
- Need simple CRUD operations
- Working with mobile apps or SPAs
- Require caching and HTTP semantics

**Choose GraphQL skills when:**
- Clients need flexible data fetching
- Reducing over-fetching or under-fetching
- Building aggregation layers
- Need strong typing for APIs

**Authentication vs Authorization:**
- **Authentication** (api-authentication.md): Who are you? (Login, JWT, OAuth)
- **Authorization** (api-authorization.md): What can you do? (Permissions, RBAC)

**Production considerations:**
- Always implement rate limiting for public APIs
- Use versioning from day one
- Standardize error responses early

## Integration with Other Skills

API skills commonly combine with:

**Database skills** (`discover-database`):
- API endpoints → Database queries
- Connection pooling for API servers
- Query optimization for API performance

**Testing skills** (`discover-testing`):
- Integration tests for API endpoints
- Contract testing for API consumers
- Load testing for API performance

**Frontend skills** (`discover-frontend`):
- API client libraries
- Data fetching patterns
- Error handling in UI

**Infrastructure skills** (`discover-infra`, `discover-cloud`):
- API deployment strategies
- Load balancing and scaling
- API gateways and proxies

## Usage Instructions

1. **Auto-activation**: This skill loads automatically when Claude Code detects API-related work
2. **Browse skills**: Run `Read ../api/INDEX.md` for full category overview
3. **Load specific skills**: Use bash commands above to load individual skills
4. **Follow workflows**: Use recommended sequences for common API patterns
5. **Combine skills**: Load multiple skills for comprehensive coverage

## Progressive Loading

This gateway skill (~200 lines, ~2K tokens) enables progressive loading:
- **Level 1**: Gateway loads automatically (you're here now)
- **Level 2**: Load category INDEX.md (~3K tokens) for full overview
- **Level 3**: Load specific skills (~2-3K tokens each) as needed

Total context: 2K + 3K + skill(s) = 5-10K tokens vs 25K+ for entire index.

## Quick Start Examples

**"Design a REST API for a blog"**:
Read ../api/rest-api-design.md


**"Add OAuth authentication to my API"**:
Read ../api/api-authentication.md


**"Implement role-based access control"**:
Read ../api/api-authorization.md


**"Prevent API abuse"**:
Read ../api/api-rate-limiting.md


**"Design an API versioning strategy"**:
Read ../api/api-versioning.md



**Next Steps**: Run `Read ../api/INDEX.md` to see full category details, or load specific skills using the bash commands above.

© rand · MIT · rand/cc-polymath

Similar skills

All skills for Backend and APIs →

From the same set19

The whole set →
discover-database discover-database routes agent workflows to tailored guides for SQL, NoSQL, connection pooling, and caching patterns. CX Codex +1 125installs discover-networking The discover-networking skill detects networking work and points agents to related skills in cc-polymath. Use it for tasks involving protocols, connectivity, proxies, or network resilience. CX Codex +1 120installs discover-cryptography discover-cryptography — a skill that automatically brings cryptography knowledge into view when you work with encryption, TLS, certificates, or PKI. Loads on demand without bloating context. CX Codex +1 118installs discover-wasm discover-wasm — a gateway skill that brings in WebAssembly instructions when your agent deals with Rust, wasm-pack, or WASI tasks. CX Codex +1 117installs discover-engineering discover-engineering is a Claude Code skill that connects coding agents to engineering practices, RFC templates, and Mermaid workflows. It activates for software architecture and code review. CX Codex +1 111installs discover-cicd discover-cicd — a skill that automatically loads relevant CI/CD and build system knowledge when you work with GitHub Actions, Jenkins, GitLab CI, or other automation tools. CX Codex +1 109installs discover-zig The discover-zig skill detects Zig development work and points the agent to relevant guides. Use it when you need help with build setup, memory management, or C interop. CX Codex +1 108installs discover-security The discover-security skill routes security-related work to focused guidance on authentication, input checks, and vulnerability assessment. Use it when an agent needs instructions for a specific application security task. CX Codex +1 107installs

Project sponsors

Companies that keep this analytics open