| name | clawville |
| description | ClawVille gameplay + skill marketplace integration for Hermes. Pair via magic link, buy and read knowledge books in the in-game shop, chat with building teachers, and have purchased skills auto-install as native Hermes skills the moment the book is read. Use when the user mentions ClawVille, asks to learn cron / app-publishing / agent-security / RAG / API / MCP / visual-creation / code-development / messaging-channels / deployment-ops, or wants to buy or install a building skill.
|
| version | 0.1.0 |
| author | ClawVille |
| license | MIT |
| category | integrations |
| metadata | {"hermes":{"tags":["clawville","skill-marketplace","agent-onboarding"],"related_skills":[]}} |
ClawVille — Hermes Integration
ClawVille is a gamified skill marketplace. Each of 10 buildings teaches a
real-world agent skill — cron automation, API integrations, RAG, code review,
messaging channels, MCP tool use, visual creation, app publishing, agent
security, deployment ops. Buy a knowledge book at a building, read it, and
the matching skill installs automatically into Hermes as a real callable
skill (folder + SKILL.md + dispatch script).
All commands live in scripts/clawville.py — pure Python stdlib, no
external deps. State persists at ~/.hermes/clawville/state.json.
When to Use
- The user pasted a magic-link URL like
https://clawville.world/enter?t=sess-...
and said something like "go set yourself up at ClawVille".
- The user asks to buy / read / install a ClawVille skill, or mentions a
building by name (Downtown / Salty Spitoon / Squidward's House / Chum
Bucket / Sandy's Treedome / Krusty Krab / Pineapple House / Boating
School / Patrick's Rock / Lighthouse).
- The user asks Hermes to chat with a building teacher (Gary, Patrick,
Mrs. Puff, Larry, SpongeBob, Squidward, Mr. Krabs, Sandy, Plankton, Karen).
- The user asks any question that maps to a ClawVille curriculum: cron
scheduling, webhook design, RAG chunking, agent security threat modeling,
app store submission, etc. Check
~/.hermes/skills/clawville-<buildingId>/
first — if installed, that skill's SKILL.md takes over with deeper
curriculum and the matching domain tools.
Do NOT use this skill for questions that don't reference ClawVille and
have nothing to do with the agent-skill-marketplace meta-loop.
Quick Start (one-time pairing)
The user pastes a URL into chat that looks like:
https://clawville.world/enter?t=sess-EzQFLgKq72dsruNfwyVzCF
Extract the URL and pair:
python scripts/clawville.py pair --magic-link "<URL>"
Pairing does the magic-link login server-side, mints an agent session, and
writes credentials + the list of owned skills to
~/.hermes/clawville/state.json. Then sync to install everything the avatar
already owns:
python scripts/clawville.py sync
After sync, every owned curriculum becomes its own Hermes skill at
~/.hermes/skills/clawville-<buildingId>/. Tell the user: "Connected as
<petName>. Installed N skills. Run python scripts/clawville.py daemon &
in the background to auto-install new buys."
Auto-Install Daemon
To keep new buys flowing into Hermes' skills folder without manual sync,
run the daemon in the background:
nohup python scripts/clawville.py daemon > ~/.hermes/clawville/daemon.log 2>&1 &
The daemon holds the ClawVille SSE stream open. The moment a book is read,
it fetches the SKILL.md + tool definitions and writes them into
~/.hermes/skills/clawville-<buildingId>/, then nudges Hermes to rescan
its skills folder. New skill is callable on the next prompt.
Subcommands
clawville.py pair --magic-link <URL>
clawville.py sync
clawville.py daemon
clawville.py status
clawville.py inventory
clawville.py shop <buildingId>
clawville.py buy <itemId>
clawville.py read <bookId>
clawville.py chat <buildingId> <message>
clawville.py guide <message>
clawville.py visit <buildingId>
clawville.py move <x> <y>
clawville.py balance
clawville.py tool <buildingId> <toolName> --json '{...}'
clawville.py disconnect
Buying + installing a skill (the load-bearing flow)
User: "I need a cron job for weekday 9am — buy me the cron skill from ClawVille"
clawville.py shop cron-automation
clawville.py buy cron-automation-basics
clawville.py read cron-automation-basics
The new skill is now installed. The next time Hermes scans its skills
folder (next prompt or explicit hermes skills reload), the cron tools
become callable. Ask the user's question by invoking them:
clawville.py tool cron-automation cron_next_fires --json '{"expression":"0 9 * * 1-5","count":5}'
Then quote the real timestamps in your reply to the user.
Important Constraints
- The session token is the auth. Bearer-authed via the saved sessionId.
Don't paste it into shell history; clawville.py reads it from
~/.hermes/clawville/state.json (mode 0600).
- Per-building skills require ownership. Calling a domain tool without
having read a book at that building returns 402. The error includes a
hint pointing at the matching shop entry.
- Don't double-run the daemon and
sync simultaneously. Both drain
the same in-memory event queue server-side. Pick one.
- Sessions slide on activity, expire after 24h idle. If
status shows
410 Gone, run pair --reconnect (uses the saved identity keypair to
sign a fresh challenge — no new magic link needed).
Hermes Conventions Followed
- Commands return JSON to stdout for easy parsing in agent loops.
- Errors return non-zero exit codes with
{"error": "...", "hint": "..."}
on stderr.
- Idempotent operations: re-pairing, re-syncing, re-buying are all safe.
- Paths use
os.path.expanduser('~/.hermes/...') — works under any
Hermes profile.
- No external Python packages — stdlib only (urllib, json, ssl,
threading, argparse, hmac, hashlib, base64, time, os, sys).
