# Player API skills

Task playbooks for working on the GCC **Player API** (`app/api/`). Each folder
holds a `SKILL.md` with YAML frontmatter (`name`, `description`), matching the
convention used in `app/Admin/Skills/` and `app/.claude/skills/`.

These are **procedures**. The reference material they lean on lives in
[`../docs/`](../docs/), and the standing rules are in [`../CLAUDE.md`](../CLAUDE.md).

| Skill | Use it when |
|---|---|
| [`api-endpoint`](api-endpoint/SKILL.md) | Adding or changing an endpoint — the registry entry, the `this.routable` allowlist, access rules, caching, the envelope |
| [`api-access-rule`](api-access-rule/SKILL.md) | An endpoint needs an entitlement beyond "any valid key", or you're adding a new rule kind |
| [`api-verify`](api-verify/SKILL.md) | **Before every commit** — drive the real endpoint with a real key, test the gate, clean up |

## Suggested order

Adding an endpoint → `api-endpoint`, then `api-access-rule` if it needs gating,
then `api-verify`.

Changing an existing one → remember it is a **public contract**. Adding a field
is safe; renaming or removing one breaks callers you cannot see.

## The one thing to internalise

`Registry.cfc` is the single declaration point. Routing, `meta.endpoints`, and
the in-game documentation page all render from it. If you find yourself updating
documentation by hand to describe an endpoint, stop — you are working around the
registry rather than with it.

## Two standing rules

- **This API is read-only.** GET is the only method that routes. If a change
  seems to need a write, it belongs in the game or the Admin panel.
- **Never commit a verification harness**, and delete `test.cfm` before
  production. `git status --short app/api` before every commit.

## Related skills elsewhere

- `app/Admin/Skills/` — the staff panel. Similar shape, different application
  and auth; do not carry assumptions across.
- `app/.claude/skills/game-changelog` — player-facing changelog. A new public
  endpoint is a player-facing change and belongs there.