coa-db-skill: db.exil.es item/spell/NPC/quest lookup skill
Public, curl-based agent skill (Claude Code + Sub-Bots) over the db.exil.es JSON API (https://db.exil.es/api/v1, no auth): - skills/coa-db-skill/SKILL.md — endpoint reference + name->id->detail workflow - bin/coa-db — optional bash helper (search/item/spell/npc/quest/url)
This commit is contained in:
commit
2e0e8a37d1
4 changed files with 209 additions and 0 deletions
2
.gitignore
vendored
Normal file
2
.gitignore
vendored
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
*.pyc
|
||||
__pycache__/
|
||||
49
README.md
Normal file
49
README.md
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
# coa-db-skill
|
||||
|
||||
An agent skill for looking up **Conquest of Ascension (CoA)** WoW items,
|
||||
spells, NPCs, and quests on [db.exil.es](https://db.exil.es) — the CoA Guild
|
||||
"Exiles" database — via its public JSON API.
|
||||
|
||||
Works for Claude Code and the Sub-Net Sub-Bots. No credentials required; the
|
||||
db.exil.es API is public and read-only.
|
||||
|
||||
## What's here
|
||||
|
||||
- `skills/coa-db-skill/SKILL.md` — the skill (curl-based; API reference + workflow).
|
||||
- `bin/coa-db` — optional bash helper (`coa-db search "…"`, `coa-db item <id>`, …).
|
||||
|
||||
## Install
|
||||
|
||||
### Claude Code
|
||||
|
||||
Symlink (or copy) the skill into your skills dir:
|
||||
|
||||
```bash
|
||||
ln -s "$(pwd)/skills/coa-db-skill" ~/.claude/skills/coa-db-skill
|
||||
```
|
||||
|
||||
Optionally put the helper on your PATH:
|
||||
|
||||
```bash
|
||||
ln -s "$(pwd)/bin/coa-db" ~/.local/bin/coa-db
|
||||
```
|
||||
|
||||
### Sub-Bots
|
||||
|
||||
Drop `skills/coa-db-skill/` into the bot's skills directory (the same place
|
||||
the other `*/SKILL.md` skills live), or vendor this repo and point the loader
|
||||
at it. The skill only needs `curl` (and `jq`/`python3` for pretty output).
|
||||
|
||||
## Quick use
|
||||
|
||||
```bash
|
||||
curl -s 'https://db.exil.es/api/v1/search?q=Neurotoxin%20Edge'
|
||||
curl -s 'https://db.exil.es/api/v1/items/312518'
|
||||
# or, with the helper:
|
||||
coa-db search "Neurotoxin Edge"
|
||||
coa-db item 312518
|
||||
```
|
||||
|
||||
API base `https://db.exil.es/api/v1`; OpenAPI at
|
||||
`https://db.exil.es/api/openapi.json`. See `skills/coa-db-skill/SKILL.md` for
|
||||
the full endpoint reference.
|
||||
59
bin/coa-db
Executable file
59
bin/coa-db
Executable file
|
|
@ -0,0 +1,59 @@
|
|||
#!/usr/bin/env bash
|
||||
#
|
||||
# coa-db — tiny CLI over the public db.exil.es JSON API.
|
||||
# No auth required. Pretty-prints with jq when available.
|
||||
#
|
||||
# Usage:
|
||||
# coa-db search <text...> # search items/spells/npcs/quests
|
||||
# coa-db item <id>
|
||||
# coa-db spell <id>
|
||||
# coa-db npc <id>
|
||||
# coa-db quest <id>
|
||||
# coa-db spells <key=val>... # filter catalogue, e.g. mechanic=15 limit=1000
|
||||
# coa-db changes
|
||||
# coa-db url <item|spell|npc|quest> <id>
|
||||
#
|
||||
# Env: COADB_BASE (default https://db.exil.es)
|
||||
|
||||
set -euo pipefail
|
||||
BASE="${COADB_BASE:-https://db.exil.es}"
|
||||
API="$BASE/api/v1"
|
||||
|
||||
_get() { curl -fsS --max-time 20 "$1"; }
|
||||
|
||||
_pretty() {
|
||||
if command -v jq >/dev/null 2>&1; then jq .
|
||||
else python3 -m json.tool 2>/dev/null || cat
|
||||
fi
|
||||
}
|
||||
|
||||
# URL-encode a string (spaces, &, etc.) without external deps.
|
||||
_enc() {
|
||||
python3 -c 'import sys,urllib.parse as u; print(u.quote(" ".join(sys.argv[1:])))' "$@"
|
||||
}
|
||||
|
||||
cmd="${1:-}"; shift || true
|
||||
case "$cmd" in
|
||||
search)
|
||||
[ "$#" -ge 1 ] || { echo "usage: coa-db search <text...>" >&2; exit 2; }
|
||||
_get "$API/search?q=$(_enc "$@")" | _pretty
|
||||
;;
|
||||
item) _get "$API/items/${1:?item id}" | _pretty ;;
|
||||
spell) _get "$API/spells/${1:?spell id}" | _pretty ;;
|
||||
npc) _get "$API/npcs/${1:?npc id}" | _pretty ;;
|
||||
quest) _get "$API/quests/${1:?quest id}" | _pretty ;;
|
||||
spells)
|
||||
q=""; for kv in "$@"; do q="${q:+$q&}$kv"; done
|
||||
_get "$API/spells${q:+?$q}" | _pretty
|
||||
;;
|
||||
changes) _get "$API/changes" | _pretty ;;
|
||||
health) _get "$API/health" | _pretty ;;
|
||||
url)
|
||||
kind="${1:?kind (item|spell|npc|quest)}"; id="${2:?id}"
|
||||
echo "$BASE/$kind/$id"
|
||||
;;
|
||||
*)
|
||||
sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
99
skills/coa-db-skill/SKILL.md
Normal file
99
skills/coa-db-skill/SKILL.md
Normal file
|
|
@ -0,0 +1,99 @@
|
|||
---
|
||||
name: coa-db-skill
|
||||
description: Look up Conquest of Ascension (CoA) WoW items, spells, NPCs, and quests on db.exil.es via its public JSON API. Use when asked about a CoA/Ascension item/spell/NPC/quest by name or id, its stats, what drops it, or to link a db.exil.es page.
|
||||
requires:
|
||||
bins: ["curl"]
|
||||
---
|
||||
|
||||
# coa-db lookup (db.exil.es)
|
||||
|
||||
`db.exil.es` is the CoA Guild "Exiles" item/spell database (a self-hosted
|
||||
Wowhead-style site for Project Ascension's Conquest of Azeroth realm). It
|
||||
exposes a **public, unauthenticated JSON API** — no token needed.
|
||||
|
||||
- API base: `https://db.exil.es/api/v1`
|
||||
- Human pages: `https://db.exil.es/{item,spell,npc,quest}/{id}` and
|
||||
`https://db.exil.es/search?q=<text>`
|
||||
- OpenAPI: `https://db.exil.es/api/openapi.json`
|
||||
|
||||
The data is CoA-specific (custom classes, custom items in the 200000–2000000+
|
||||
id ranges, BWL/raid drops, mystic scrolls). Vanilla ids work too.
|
||||
|
||||
## Core workflow: name → id → detail
|
||||
|
||||
You almost always **search by name first** to get an id, then fetch the
|
||||
detail endpoint. Pipe through `jq` if available; otherwise `python3 -m
|
||||
json.tool`.
|
||||
|
||||
```bash
|
||||
# 1) search (returns items, spells, npcs, quests, worldforged — each [{id,name,label,tone}])
|
||||
curl -s 'https://db.exil.es/api/v1/search?q=Neurotoxin%20Edge'
|
||||
|
||||
# 2) fetch the item by id
|
||||
curl -s 'https://db.exil.es/api/v1/items/312518'
|
||||
```
|
||||
|
||||
URL-encode the query (`%20` for space). `tone` on item results is the
|
||||
quality color (`q0` poor … `q4` epic, `q5` legendary, `q6` artifact).
|
||||
|
||||
## Endpoints
|
||||
|
||||
| Endpoint | Returns |
|
||||
| --- | --- |
|
||||
| `GET /api/v1/search?q=<text>` | `{query, items[], spells[], npcs[], quests[], worldforged[]}`; each entry `{id, name, label, tone?}` |
|
||||
| `GET /api/v1/items/{id}` | item detail (below) |
|
||||
| `GET /api/v1/spells/{id}` | spell detail |
|
||||
| `GET /api/v1/npcs/{id}` | NPC detail |
|
||||
| `GET /api/v1/quests/{id}` | quest detail |
|
||||
| `GET /api/v1/spells?mechanic=&effect_mechanic=&dispel_type=&limit=&cursor=` | filterable spell catalogue (keyset-paginated; `cursor` = last id seen, `limit` 1–1000 default 200) |
|
||||
| `GET /api/v1/changes` | newest-first change_event log |
|
||||
| `GET /api/v1/health` | `{status, version, database}` (200 even in fixtures-only mode; data endpoints return 503 if `database=false`) |
|
||||
|
||||
Unknown ids return `404`.
|
||||
|
||||
### Item detail fields
|
||||
|
||||
`id, name, quality, item_level, required_level, item_class, item_subclass,
|
||||
inventory_type, bonding, worldforged, armor, stats[ {stat,value} ],
|
||||
spell_lines[], taught_spell, sell_price, source_label, description,
|
||||
required_class_mask`.
|
||||
|
||||
`source_label` is the recorded drop/vendor/quest source (may be `null` if
|
||||
not yet catalogued). `description` can contain `@…@`-wrapped flavour tags
|
||||
(e.g. `@Heroic Raid@`).
|
||||
|
||||
### Spell filter examples
|
||||
|
||||
```bash
|
||||
# every Bleed spell (mechanic 15)
|
||||
curl -s 'https://db.exil.es/api/v1/spells?mechanic=15&limit=1000'
|
||||
# every Poison-dispellable aura (dispel_type 4)
|
||||
curl -s 'https://db.exil.es/api/v1/spells?dispel_type=4'
|
||||
```
|
||||
|
||||
Common codes: mechanic 15=Bleed, 1=Charm, 19=Disarm; dispel_type 1=Magic,
|
||||
2=Curse, 3=Disease, 4=Poison.
|
||||
|
||||
## Optional helper
|
||||
|
||||
`bin/coa-db` (in this repo) wraps the above:
|
||||
|
||||
```bash
|
||||
coa-db search "Neurotoxin Edge" # search, compact id/name list
|
||||
coa-db item 312518 # item detail (jq-pretty if jq present)
|
||||
coa-db spell 500071 # spell detail
|
||||
coa-db npc 11502 # npc detail
|
||||
coa-db quest 580226 # quest detail
|
||||
coa-db url item 312518 # print the human page URL
|
||||
```
|
||||
|
||||
Set `COADB_BASE` to override the base URL (default `https://db.exil.es`).
|
||||
|
||||
## Tips
|
||||
|
||||
- When a user gives a bare number that "looks like an item", try
|
||||
`/api/v1/items/{id}` directly; fall back to `/search` if it 404s.
|
||||
- To share a result with a human, link the page: `https://db.exil.es/item/<id>`.
|
||||
- Search is fuzzy/multi-type — a name like "Ragnaros" returns the NPC, the
|
||||
quest, and items at once; pick the right section.
|
||||
- This API is read-only; there is no write/auth surface.
|
||||
Loading…
Add table
Add a link
Reference in a new issue