Dwarf Fortress Agent Skills

A flat Agent Skills knowledge base for Dwarf Fortress v50 / Premium, built from the official wiki via its MediaWiki API — no RAG, no embeddings, no vector database. Clean Markdown + progressive disclosure + a tiny SQLite FTS5 search.

What is this?

13 flat Agent Skills (progressive-disclosure pattern) that any LLM agent — pi, Claude Code, Cursor, Codex, or a custom OpenRouter agent — can load to answer Dwarf Fortress gameplay questions with wiki ground-truth accuracy instead of inventing mechanics from memory.

The agent discovers skills by their description in the system prompt. When a task matches, it loads the skill's SKILL.md (a short index), then either reads the specific article from references/ or runs the bundled full-text search. The descriptions are bilingual (Portuguese framing + English game keywords) so the skills trigger whether the user writes in Portuguese or English.

Why flat?

pi/Claude Code skill discovery is flat and recursive — every directory with a SKILL.md becomes a peer in the system prompt, discovered only by its description. There is no built-in routing; the description is the router. Consequences this repo respects:

• Strict YAML. Descriptions are emitted as YAML folded scalars (>-), so colons/quotes never break the parser (a description: with an unquoted : silently fails to load).
• Unique names. Name collisions keep only the first discovery, so all 13 names are unique.
• No dispatcher. A greedy catch-all skill would just compete with the 13 specific ones in flat discovery, so there is none.

How the content is built (and why it's trustworthy)

Earlier versions parsed a 2023 raw-wikitext XML dump with mwparserfromhell + pandoc. That route is fundamentally lossy: offline parsers cannot expand MediaWiki templates, so infoboxes, token tables and /raw subpages came out empty or as [TABLE] placeholders. See AUDIT_REPORT.md for the full findings.

This version fetches server-rendered HTML from the live wiki's MediaWiki API (action=parse), where templates are already expanded. As a result:

• Creature infoboxes are preserved as **Key:** value blocks (pet value, body size, butchering returns, etc.).
• Token reference tables (creature/weapon/material tokens) survive as proper GFM pipe tables — no [TABLE].
• /raw pages contain the full [CREATURE:DOG]… token definitions as fenced code blocks.
• Content is current v50 (namespace 0), snapshot dated 2026-06, not a stale 2023 merge.

Skill categories

| Skill | Mode | Covers | |---|---|---| | df-criaturas | both | creatures, animals, megabeasts, races, bestiary, creature raws | | df-combate | both | weapons, armor, wounds, syndromes, military, squads, defense | | df-materiais | both | metals, stone, ores, gems, alloys, steel, adamantine, properties | | df-saude | both | food, drink, hospital, disease, farming, crops, brewing | | df-geologia | both | biomes, layers, worldgen, plants, trees, locations, lore | | df-modding | both | tokens, raws, tilesets, graphics, creature definitions | | df-interface | both | keys, menus, designations, UI shortcuts (v50) | | df-adventure | adventure | character creation, travel, conversation, sites, quests | | df-fortress-industria | fortress | smelting, forging, workshops, production chains | | df-fortress-construcao | fortress | workshops, furniture, mechanisms, stockpiles, bridges | | df-dwarves | fortress | labors, skills, strange moods, nobles, justice, psychology | | df-comercio | fortress | trade, caravans, depot, wealth, economy | | df-fortress-geral | fortress | defense, embarks, physics (water/magma/pressure), guides, FAQs |

Descriptions are bilingual; article content is the original English wiki text.

How an agent uses it

1. System prompt includes the 13 descriptions. Agent sees the user's question.
2. Agent picks the relevant skill by description match (PT or EN triggers).
3. Agent loads that skill's SKILL.md (short index + search instructions).
4. Agent searches, then reads the specific references/*.md article:
     python3 .agents/skills/scripts/search.py --skill df-materiais "steel smelting"
     python3 .agents/skills/scripts/search.py --json "magma forge"
5. Agent answers in the user's language, citing the source wiki page.

Articles are English. When the user asks in Portuguese, the agent translates the query to English game terms (helped by scripts/glossary-pt-en.tsv), searches in English, and answers in Portuguese.

Search (SQLite FTS5, stdlib-only)

python3 .agents/skills/scripts/search.py "how to make steel"        # all skills
python3 .agents/skills/scripts/search.py --skill df-criaturas "dragon"
python3 .agents/skills/scripts/search.py --json --limit 8 "como fazer aço"

• BM25 ranking with title boosting and context snippets.
• Porter stemming (smelt/smelting, miner/mining).
• Multi-term AND (multi-word queries work — unlike the old whole-phrase grep).
• PT→EN expansion via scripts/glossary-pt-en.tsv (~200 jargon pairs) so Portuguese queries match English content.
• Graceful fallback: AND → OR → prefix when a query returns nothing.

The index (scripts/index.db) is a derived artifact built from the markdown by scripts/build_index.py. Search uses only the Python standard library (sqlite3 with FTS5) — no network, no external packages — so it is portable to any agent runtime. A grep -ril fallback is documented in each SKILL.md for index-less use.

Installation

Via npm (recommended) — interactive installer

npm install -g dwarf-fortress-agent-skills
# or straight from GitHub (no registry needed):
npm install -g github:frederico-kluser/dwarf-fortress-agent-skills

cd your-project
df-skills            # interactive: pick your code agent with ↑/↓

The installer asks which code agent you use and sets everything up for it:

| Agent | What df-skills does | |---|---| | Claude Code | copies skills to .claude/skills/ (or ~/.claude/skills/ with --global) | | pi | copies skills to .agents/skills/ (auto-discovered) | | Cursor | copies skills + creates .cursor/rules/dwarf-fortress-skills.mdc router rule | | Codex (OpenAI) | copies skills + appends a routed section to AGENTS.md (idempotent) | | Other / OpenRouter | copies skills + writes a system-prompt snippet (INSTRUCTIONS.md) |

It rewrites the search paths inside each SKILL.md for the chosen target, and ends by telling you the initial skill (df-fortress-geral) and the exact phrasing to reference it in your agent.

Non-interactive: df-skills --agent claude|pi|cursor|codex|generic [--global] [--force]

Manual (clone)

pi / .agents/skills (automatic discovery): just clone — no config needed.

Claude Code / Cursor / Codex:

cp -r .agents/skills/* ~/.claude/skills/        # or per-project: .claude/skills/

Build pipeline (reproducible)

python -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt                 # requests, beautifulsoup4, lxml
# system deps: pandoc, sqlite3 (FTS5), ripgrep

python .work/crawl_api.py                        # live wiki API → .work/pages.jsonl (rendered HTML)
python .work/build_skills.py                     # HTML → clean Markdown → .agents/skills/*/references/
python .agents/skills/scripts/build_index.py     # build the FTS5 search index

.work/pages.jsonl (the rendered-HTML cache) is large and git-ignored; the crawl regenerates it from the live wiki, so a clean clone rebuilds end-to-end.

Pipeline modules in .work/: crawl_api.py (API crawler) · htmlmd.py (HTML→Markdown) · taxonomy.py (skill taxonomy + bilingual descriptions) · build_skills.py (assembler).

Design decisions

• API-rendered HTML, not a wikitext dump. The only way to preserve infoboxes, token tables and /raw content; also keeps the content current (v50) instead of a 2023 snapshot. Templates are expanded server-side; offline parsers cannot do this.
• SQLite FTS5, not RAG. At a few thousand Markdown files, BM25 + stemming is sub-millisecond, deterministic, zero-infrastructure, and portable (stdlib only). Embeddings would add a model dependency and break portability for no benefit here.
• Bilingual descriptions + query glossary. Triggering and retrieval both work for Portuguese users over English content, without multilingual embeddings.
• Split, don't truncate. Articles over 48 KB are split into navigable …-part-N.md files with continuation notes — no content is silently dropped.
• Subject-based routing. Each page is assigned to one skill by its wiki categories (deterministic priority), with /raw pages routed to their topic skill (e.g. Dog/raw → df-criaturas), not dumped into modding.
• Relevance-ranked indexes. SKILL.md lists the top articles by inbound-link count (a popularity proxy); the rest are found via search.py.

License

• Wiki text (under .agents/skills/*/references/) — GFDL & MIT by Dwarf Fortress Wiki contributors. Every article links to its source page.
• Build scripts & search tooling — MIT License (see LICENSE).
• Game-derived data — © 2002–2026 Tarn Adams / Bay 12 Games.

This is an unofficial community resource, not affiliated with Bay 12 Games.