Boardgame rag bot

Skill mike623/agent-skills/skills/boardgame-rag-bot

Install

npx -y skills add mike623/agent-skills --skill boardgame-rag-bot

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Create public-safe board-game rules agents from a BGG link plus user-provided rulebooks, using private semantic RAG, lexical fallback, and page citations.

SKILL.md

5.1 KB, as published. Nobody here has run it

Boardgame RAG Bot

Use this skill when the user wants to turn a board game into a rules assistant from a BoardGameGeek link, PDF rulebook, FAQ, errata, or local notes.

The skill is intentionally frontend-agnostic: it creates a local RAG-backed agent package that Claude Code, Codex, Cursor, Hermes, or another agent can use. Telegram/Discord bots are optional wrappers, not part of the core workflow.

Public-safe constraints

Do not commit official rulebook PDFs, extracted full text, generated chunks, embeddings, indexes, or private filesystem paths.
Keep source documents and generated RAG indexes in a user-local output directory.
Quote only short snippets returned by lookup; prefer paraphrased rulings with citations.
If a BGG file needs login or an expiring signed URL, ask the user to download/upload/provide a fresh direct link. Never ask for BGG passwords.
Treat BGG metadata as useful context, not rules authority. Official rulebook/FAQ/errata sources are authoritative.

Practical user flow

User provides:

Make a rules agent from https://boardgamegeek.com/boardgame/<id>/<slug>

Best MVP command:

python3 skills/boardgame-rag-bot/scripts/boardgame_agent_from_bgg.py \
  "https://boardgamegeek.com/boardgame/<id>/<slug>" \
  --pdf /path/to/rulebook.pdf \
  --out /path/to/private/boardgame-agents/<game-slug>

Output package:

<out>/
├── README.md
├── SKILL.md                         # generated game-specific agent skill
├── sources/
│   ├── bgg-metadata.json
│   ├── source-links.json
│   ├── rulebook.pdf                 # private, gitignored by default
│   ├── rulebook.raw.txt             # private extraction
│   └── rulebook.md                  # private cleaned Markdown with page anchors
├── rag/
│   ├── chunks.jsonl                 # generated, private
│   ├── manifest.json
│   ├── embeddings.npy               # if semantic deps available
│   └── vectorizer.pkl               # if sklearn available
└── scripts/
    └── lookup.py

Retrieval policy

Always do retrieval before answering rules questions:

<out>/scripts/lookup.py "<question>" --limit 5

Use the returned source, page, heading, match_type, and short excerpt fields to answer.

Answer format:

Ruling: <direct answer>

Do this:
- <step>
- <step>

Source: <source>, p. <page> / <heading>
Confidence: high|medium|low

If retrieval is weak or conflicting:

I could not find a clear official rule in the indexed sources. Table ruling: ...

Build workflow

Fetch BGG metadata with XML API from the provided BGG URL.
Create a private output package under --out.
Collect rules sources:
- use --pdf or --pdf-url when provided;
- otherwise save candidate links and ask the user for a rulebook PDF/direct URL.
Extract PDF to text/Markdown with page anchors.
Build hybrid RAG:
- semantic embeddings when sentence-transformers + numpy are installed;
- TF-IDF when scikit-learn is installed;
- stdlib BM25-style lexical fallback always.
Generate game-specific SKILL.md that tells future agents to run scripts/lookup.py first.
Verify with 5-10 generic test queries such as setup, turn order, line of sight, end of round, victory, and common game-specific terms.

Dependencies

The scripts run with Python 3. Optional semantic dependencies:

python3 -m pip install --user sentence-transformers numpy scikit-learn pymupdf

Fallback behavior:

Without sentence-transformers/numpy, semantic embeddings are skipped and clearly recorded in manifest.json.
Without scikit-learn, TF-IDF is skipped.
Stdlib lexical BM25-style search still works.

BGG limitations

BGG metadata is usually accessible through:

https://boardgamegeek.com/xmlapi2/thing?id=<id>&stats=1

BGG file downloads are less reliable:

may require login;
may use short-lived Geekdo/S3 signed URLs;
may include fan uploads with unclear authority.

Practical rule: bootstrap metadata automatically, but treat rulebook discovery as best-effort. If the PDF is not publicly accessible, ask the user to provide it.

Source precedence

When multiple sources disagree:

Official errata/FAQ.
Current edition rulebook.
Expansion rulebook for expansion-specific rules.
Publisher player aid/reference.
Fan summaries/teaching aids, clearly labeled as non-authoritative.

Verification checklist

Output package exists outside the public skill repo.
sources/bgg-metadata.json exists.
Rulebook PDF/text/Markdown are private and not committed.
sources/rulebook.md has ## Page N {#page-n} anchors.
rag/manifest.json and rag/chunks.jsonl exist.
Semantic status is recorded in manifest.json.
scripts/lookup.py "setup" returns cited results.
Generated game SKILL.md requires lookup before rules answers.