From 2e0e8a37d17ed5420ed06ab969875332394a98de Mon Sep 17 00:00:00 2001 From: Florian Berthold Date: Mon, 8 Jun 2026 00:42:07 +0200 Subject: [PATCH] coa-db-skill: db.exil.es item/spell/NPC/quest lookup skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- .gitignore | 2 + README.md | 49 ++++++++++++++++++ bin/coa-db | 59 +++++++++++++++++++++ skills/coa-db-skill/SKILL.md | 99 ++++++++++++++++++++++++++++++++++++ 4 files changed, 209 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100755 bin/coa-db create mode 100644 skills/coa-db-skill/SKILL.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d646835 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +*.pyc +__pycache__/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..1e5e599 --- /dev/null +++ b/README.md @@ -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 `, …). + +## 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. diff --git a/bin/coa-db b/bin/coa-db new file mode 100755 index 0000000..6f81f5d --- /dev/null +++ b/bin/coa-db @@ -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 # search items/spells/npcs/quests +# coa-db item +# coa-db spell +# coa-db npc +# coa-db quest +# coa-db spells ... # filter catalogue, e.g. mechanic=15 limit=1000 +# coa-db changes +# coa-db url +# +# 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 " >&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 diff --git a/skills/coa-db-skill/SKILL.md b/skills/coa-db-skill/SKILL.md new file mode 100644 index 0000000..10f0923 --- /dev/null +++ b/skills/coa-db-skill/SKILL.md @@ -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=` +- 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=` | `{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/`. +- 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.