How to use the API Patterns Guide agent skill

What is an agent skill, and what does api-patterns make the agent do?

An agent skill is a folder of instructions and reference files that an AI agent can load when a task matches it. The skill's entry file, SKILL.md, tells the agent when to use it and which other files to read. The skill's own rule is to read only the files relevant to the request.

Once api-patterns is active, the agent works from a decision checklist before designing an API. It asks who the consumers are, chooses an API style for that context, and then follows consistent guidance on response formats, error handling, pagination, versioning, authentication and rate limiting. Guidance on REST, GraphQL, tRPC, OpenAPI documentation and OWASP API security testing is kept in separate files.

• api-style.md: decision tree for REST vs GraphQL vs tRPC
• rest.md: resource naming, HTTP methods, status codes
• response.md: envelope pattern, error format, pagination
• versioning.md: URI, header and query versioning
• auth.md: JWT, OAuth, Passkey and API keys
• rate-limiting.md: token bucket and sliding window
• documentation.md: OpenAPI/Swagger practices
• security-testing.md: OWASP API Top 10 and auth/authz testing

How do you install the api-patterns skill?

Download the skill ZIP from this page and unzip it. You can install it in one of two places. For a personal setup that works across projects, unzip it into ~/.claude/skills/. For a single project, unzip it into the .claude/skills/ folder inside that project.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal: unzip into ~/.claude/skills/
• Project only: unzip into .claude/skills/ in the project root
• Claude apps: Settings → Capabilities → Skills, then upload

How do you trigger the skill with a natural request?

You do not need a special command. Describe the API task in plain language and name the consumers and constraints if you know them. The skill's own procedure asks for consumers, deployed versions, expected payload size, access rules and compatibility obligations, so giving these up front saves a round of questions.

Requests that fit the skill's stated scope include defining a new endpoint contract, picking REST, GraphQL or tRPC for known clients, and changing pagination, errors, authentication or compatibility behaviour.

• Help me choose between REST and GraphQL for a mobile app and a public partner API.
• We have a TypeScript monorepo with a React frontend. Should we use tRPC?
• Review the pagination and error format of our order list endpoint.
• Plan URI versus header versioning for an API that third parties already call.

What does a worked example look like?

The skill includes a worked example for a public order list that changes while clients page through it. The suggested approach is a bounded page size and a cursor over a stable (created_at, id) order, with the next-cursor format, authorisation filter and behaviour for removed records or invalid cursors all defined. The example also calls for testing two equal timestamps and an insertion between pages, and documenting whether newly inserted rows can appear.

You can ask the agent to walk through the same reasoning for your own list endpoint, for example: Design cursor pagination for our invoices endpoint, where invoices can be added while clients page through them.

What does the optional Python script do?

The skill ships one script, scripts/api_validator.py. It runs a local heuristic scan of a project's API source files. It uses regular expressions and shallow checks on JSON and YAML, and it scans at most 15 matching files. The skill is explicit that this is a triage hint, not schema validation.

To run it, you need Python 3 and a project path. The command given in the skill is shown below.

• Requires Python 3 only if you run the script
• Scans local files; the skill states it uses no network
• Does not validate OpenAPI schemas, audit authorisation or approve deployments

What are the safety notes?

The skill runs scripts and the script reads your source files, so review it before running it on a repository you care about. The source states that the skill does not use the network. The skill's limitations also say security checks should only be run against authorised local or test targets, with isolated accounts and a defined scope.

The skill says shared build-time types do not guarantee that independently deployed clients stay compatible, so keep compatibility testing as a separate step.

• Runs scripts: yes, scripts/api_validator.py
• Network use: none stated in the skill
• Run security checks only against authorised local or test targets
• Do not treat script output as an authorization audit or deployment approval

What tips make the output more useful?

Give the agent concrete operations rather than abstract questions. One real endpoint with a request and response example will produce better guidance than a general discussion of API style. Also name the constraints that drive the decision, such as public third-party access or a single TypeScript team.

Treat the anti-patterns list as a review checklist. It warns against defaulting to REST for everything, using verbs in REST paths such as /getUsers, returning inconsistent response formats, exposing internal errors and skipping rate limiting.

• Name the consumers and their deployed versions first
• Ask for request, response and rejection examples
• Check the anti-pattern list against your draft
• Record the compatibility promise you are making to clients