# GunSpec API skills for AI coding agents

Drop-in context packs that teach an AI coding agent how to consume the
GunSpec.io REST API correctly: authentication, the response envelope, error
handling, pagination, the official SDKs, and the key endpoints. Every pack is
derived from one source of truth, the OpenAPI spec at
`https://api.gunspec.io/openapi.json`, and points the agent back to it for the
full surface.

Live URLs:

- This folder:    `https://assets.gunspec.io/ai/`
- OpenAPI spec:   `https://api.gunspec.io/openapi.json`
- Docs:           `https://docs.gunspec.io`
- Machine index:  `https://docs.gunspec.io/llms.txt`

## Pick your agent

### Claude Code
Skill: `claude-code/skills/gunspec-api/SKILL.md`
Install per project: copy the `gunspec-api` folder into `.claude/skills/`.
Install globally: copy it into `~/.claude/skills/`.

```bash
mkdir -p .claude/skills/gunspec-api
curl -s https://assets.gunspec.io/ai/claude-code/skills/gunspec-api/SKILL.md \
  -o .claude/skills/gunspec-api/SKILL.md
```

The agent loads the skill on demand when a task mentions GunSpec or firearms data.

### GitHub Copilot
File: `github-copilot/instructions/gunspec-api.instructions.md`
Install: copy it into `.github/instructions/` in your repo. Copilot applies it
automatically based on the `applyTo` glob in its front matter.

### OpenAI Codex
File: `codex/AGENTS.md`
Install: merge its contents into your project `AGENTS.md` (repo root) or into
`~/.codex/AGENTS.md` for all projects.

### Cursor
File: `cursor/rules/gunspec-api.mdc`
Install: copy it into `.cursor/rules/` in your repo.

### Any other agent
Use the format-agnostic brief: `gunspec-api.md`. Paste it into your agent's
system prompt or rules file, or have the agent fetch it at runtime.

## What every pack tells the agent

- Base URL `https://api.gunspec.io/v1` and the `X-API-Key` header.
- Read the key from an environment variable; never hardcode it.
- The `{ success, data }` envelope and the `{ success: false, error }` shape, and the few file and redirect responses that are not JSON.
- Error codes and 429 `Retry-After` backoff.
- Pagination with `page` / `per_page`, and the SDK auto-paging helpers.
- The official SDKs (`@buun_group/gunspec-sdk`, `gunspec`) and when to prefer them.
- A compact endpoint map, with the OpenAPI spec as the source of truth.

## Linked reference docs

Every pack also deep-links the docs pages an agent should reach for detail:

- Field reference / data dictionary: `https://docs.gunspec.io/en?section=field-reference`
- Error handling: `https://docs.gunspec.io/en?section=errors`
- Rate limits: `https://docs.gunspec.io/en?section=rate-limits`
- Plans and pricing: `https://docs.gunspec.io/en?section=rapidapi-plans`
- Endpoint access by tier: `https://docs.gunspec.io/en?section=endpoint-access`

These files are plain text, safe to read at build time or runtime, and served
with open CORS from `assets.gunspec.io`.