{
  "markdown": "# specter-skills\n\n[![npm version](https://img.shields.io/npm/v/specter-skills.svg)](https://www.npmjs.com/package/specter-skills)\n[![node](https://img.shields.io/node/v/specter-skills.svg)](https://www.npmjs.com/package/specter-skills)\n[![license](https://img.shields.io/badge/license-UNLICENSED-lightgrey.svg)](#)\n\n> **Build your game backend by talking to Claude.**\n\n`specter-skills` teaches Claude everything about [Specter](https://console.specterapp.xyz) — the\ngame backend platform — so you can add player accounts, an in-game economy, daily quests,\nleaderboards, tournaments, battle passes, and real-time multiplayer to your game in plain English,\nand get **correct, working code** plus the ability to **configure your backend without ever\nopening the dashboard**.\n\nNo SDK to learn. No API docs to read. Install it, then ask.\n\n```\nYou:    \"Add Specter to my game — silent login, a coins wallet, and a daily\n         quest 'play 3 matches' that rewards 100 coins.\"\nClaude: ...writes the integration code, sets up the quest in your backend, done.\n```\n\n---\n\n## Contents\n\n- [What's inside](#whats-inside)\n- [Quickstart](#quickstart)\n- [Installation](#installation)\n- [The skills](#the-skills)\n- [The MCP server](#the-mcp-server) · [Setup](#setup) · [Sign in](#signing-in-no-password-needed) · [Tools](#tools) · [Configuration](#configuration)\n- [Things to ask Claude](#things-to-ask-claude)\n- [Checking the version & updating](#checking-the-version--updating)\n- [Requirements](#requirements)\n- [Troubleshooting](#troubleshooting)\n\n---\n\n## What's inside\n\nThis one package ships **two halves of the same product**:\n\n| | What it is | What it does |\n|---|---|---|\n| 🧠 **Skills** | Knowledge Claude reads | Claude writes correct Specter integration code — right endpoints, headers, response handling, and all the platform's gotchas baked in. |\n| 🛠️ **MCP server** | A tool Claude can run | Claude *acts on* your backend — inspect a project, verify your setup, and create currencies, items, tasks, leaderboards, battle passes, and more, **straight from chat**. |\n\nSkills work in **Claude Code**, **Claude Desktop**, the **Claude Agent SDK**, and any other\nskills-aware host. The MCP server works in any MCP-compatible host (Claude Desktop, Claude Code, …).\n\n---\n\n## Quickstart\n\n**1. Install the skills** in your game project:\n\n```bash\nnpx specter-skills init\n```\n\n**2. Get your API key** from [console.specterapp.xyz](https://console.specterapp.xyz)\n(Project → API Keys).\n\n**3. Ask Claude** to build something:\n\n> *\"Add Specter email login and a gem currency to my Unity game.\"*\n\nThe right skill activates automatically and Claude writes the integration. That's it.\n\n> 💡 Want Claude to also **set up the backend for you** (create currencies, quests, leaderboards)?\n> Add the [MCP server](#the-mcp-server) and ask *\"create a gems currency and a daily login quest in\n> my Specter project.\"*\n\n---\n\n## Installation\n\n```bash\n# Interactive — choose skills and where to install them\nnpx specter-skills init\n\n# Install everything into this project's .claude/skills/\nnpx specter-skills install\n\n# Install specific skills\nnpx specter-skills install specter specter-economy\n\n# Install globally (available in all your projects)\nnpx specter-skills install --global\n\n# Install into a custom directory (Agent SDK / other hosts)\nnpx specter-skills install --dir ./skills\n```\n\n| Command | What it does |\n|---|---|\n| `npx specter-skills init` | Interactive: pick skills + target (project or global) |\n| `npx specter-skills install [names…]` | Install named skills (default: all). Flags: `--global`, `--dir <path>` |\n| `npx specter-skills update` | Re-install your skills at the latest version |\n| `npx specter-skills list` | Show which skills are available and which you have installed |\n\nSkills are copied into `.claude/skills/` (project) or `~/.claude/skills/` (global). They're plain\nfiles you can commit to your repo.\n\n---\n\n## The skills\n\n| Skill | What it covers |\n|---|---|\n| **`specter`** | Start here — platform overview, the auth model, base URLs, the response envelope, and every error code. |\n| **`specter-players`** | Sign-up & login (email, username, silent device ID, Google, Apple, Steam, Discord, Facebook), tokens, account linking, player profiles & custom data, friends. |\n| **`specter-economy`** | Currencies & wallets, items, bundles, stores & purchases, inventory, gacha / loot boxes with pity, and real-money gaming (deposits / withdrawals). |\n| **`specter-progression`** | Tasks, missions, achievements, daily quests & streaks, **task-rule design**, custom events, battle passes, XP & level systems. |\n| **`specter-competitions`** | Leaderboards, tournaments, instant battles, prize distribution, and schedules. |\n| **`specter-multiplayer`** | Skill-based matchmaking, parties, match sessions, and the full real-time Socket.io event contract. |\n| **`specter-admin`** | Configure the game via admin APIs — projects, currencies, items, tasks, live-ops, members. Used by the MCP server to set things up for you. |\n\nEach skill has a concise guide plus **per-endpoint references** (request fields, response examples)\ngenerated directly from Specter's API, and ready-to-paste **JavaScript / Unity** examples where\nuseful — so the code Claude writes stays accurate.\n\n---\n\n## The MCP server\n\nThe same package ships an MCP server, `specter-mcp`, that lets Claude **inspect and configure** a\nSpecter backend directly. The skills teach Claude the API; the MCP server lets it *use* the API.\n\n> *\"What currencies does my project have?\"* · *\"Is my setup working?\"* · *\"Create a gems currency\n> and a daily quest that rewards 100 coins.\"*\n\n### Setup\n\n**The easy way** — `npx specter-skills init` offers to set this up for you (it writes the config,\nno JSON editing). Or run it any time:\n\n```bash\n# Claude Desktop\nnpx specter-skills mcp\n\n# Claude Code (registers it for all your projects)\nnpx specter-skills mcp --code\n```\n\nThen restart your MCP host and the `specter` tools appear. (Claude Desktop and Claude Code are\ndifferent apps with separate configs — pick the one you actually use.)\n\n<details>\n<summary>Manual setup (if you prefer to edit the config yourself)</summary>\n\nAdd to your MCP host config (e.g. Claude Desktop's `claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"specter\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"-p\", \"specter-skills\", \"specter-mcp\"],\n      \"env\": {\n        \"SPECTER_ENV\": \"staging\",\n        \"SPECTER_ALLOW_MUTATIONS\": \"true\"\n      }\n    }\n  }\n}\n```\n</details>\n\nRead-only tools work immediately; creating things needs a one-time\n[sign-in](#signing-in-no-password-needed) — no api-key or project ID to configure.\n\n### Signing in (no password needed)\n\nTo **create** anything, Claude needs to act as you — so you authorize it once through your browser.\nThe first time it's needed, Claude runs the `specter_login` tool (or run it yourself in a terminal):\n\n```bash\nnpx -y -p specter-skills specter-mcp login\n```\n\nWhat happens:\n\n1. Your browser opens the Specter dashboard.\n2. You sign in **however you normally do** — email/password, **Google**, or **Apple**.\n3. You approve a consent screen (\"Allow specter-mcp to manage your projects\").\n4. Done — a revocable token is saved locally (`~/.specter/credentials.json`). You stay signed in.\n\n**Your password and social credentials never touch the tool or Claude.** Revoke access anytime\nfrom the dashboard. Manage the session with `specter-mcp whoami` and `specter-mcp logout`.\n\n> ℹ️ Run `specter-mcp` commands from any folder **except** the `specter-skills` source folder\n> itself (npx gets confused there).\n\n### Tools\n\n**Read-only** — always available, safe to run:\n\n| Tool | Purpose |\n|---|---|\n| `specter_verify_setup` | Smoke-test the project: auth, currencies, events, tasks |\n| `specter_list_currencies` · `_items` · `_bundles` · `_stores` | Inspect economy content |\n| `specter_list_events` | List custom events (with their ids) that trigger tasks |\n| `specter_list_tasks` · `_leaderboards` · `_tournaments` · `_battlepasses` | Inspect progression & competitions |\n| `specter_list_progression_systems` · `_markers` | Inspect level systems & markers |\n\n> Read tools use your browser sign-in (run `specter_login` once) — no separate api-key to configure.\n\n**Client / runtime** — act as a sandboxed test player to exercise the game-facing `/v2/client` API and **prove your config works**:\n\n| Tool | Purpose |\n|---|---|\n| `specter_get_player_state` | Read the test player's tasks, wallet, and inventory |\n| `specter_send_event` | Fire a custom event (the same call your game makes) to trigger achievements |\n| `specter_test_achievement` | End-to-end: read status → fire the event → re-read → report whether the task progressed |\n| `specter_get_reward_history` · `specter_claim_reward` | List pending rewards, and claim on-claim task rewards (grant-reward-by-source) |\n| `specter_generate_client_code` | Generate ready-to-paste game code (JS or Unity C#) wired with your real api-key + event slug |\n\n**Mutating** — opt-in (`SPECTER_ALLOW_MUTATIONS=true`), gated behind your confirmation:\n\n| Tool | Creates / does |\n|---|---|\n| `specter_create_currency` · `_item` · `_bundle` · `_store` | Economy content |\n| `specter_create_currency_conversion` · `_currency_policy` | Exchange rates + balance/decay/earning-cap policies |\n| `specter_create_event` | A custom event that triggers achievements |\n| **`specter_create_task`** | A single-objective achievement |\n| **`specter_create_mission`** · **`_step_series`** · **`_time_series`** | The 3 grouped achievement types (pool / sequential / streak) |\n| **`specter_schedule_achievement`** · **`_stop_achievement`** · **`_delete_achievement`** | Activate / halt / delete an achievement (the create→schedule two-step) |\n| `specter_create_battlepass` · `_level_system` · `_progression_marker` | Progression content |\n| `specter_create_match` | Multiplayer match template (format / outcome / game) |\n| `specter_create_leaderboard` · `_competition` | Competitions |\n| `specter_edit_currency` · `_edit_task` · `_update_entity` | Edit existing entities (rename, retune, disable, …) |\n| `specter_schedule_liveops` | Schedule a leaderboard / competition live |\n| `specter_grant_reward` | Grant items / currencies to a player |\n| `specter_admin_call` · `specter_client_call` | **Escape hatches** — call *any* `/v1` admin or `/v2/client` endpoint that lacks a dedicated tool (match config, members, games, reward-sets, tags, friends, purchases, …), using the bundled API references for the shape |\n| `specter_login` | Browser sign-in (above) |\n\nThe achievement tools resolve friendly names for you — pass `event` as an event slug/name,\n`rewards` as `[{currency:\"gems\", quantity:50}]` (or `item`/`bundle`/`marker`), and the tool\nresolves them to the right ids. Creating an achievement does **not** make it live — call\n`specter_schedule_achievement` to activate it.\n\nMutating tools change **live game configuration**, so they're flagged non-read-only and your MCP\nhost asks for confirmation before each one. **Point them at a staging project first.**\n\nYour **project is auto-detected** from your sign-in — there's no project ID to look up. (Only set\n`SPECTER_PROJECT_ID` if your organisation has several projects and you want to pin one.)\n\n### Configuration\n\nAll configuration is via env vars in your MCP host config:\n\n| Variable | Required | Default | Purpose |\n|---|---|---|---|\n| `SPECTER_ENV` | — | `staging` | `staging` or `production` |\n| `SPECTER_ALLOW_MUTATIONS` | — | `false` | `true` enables the create / mutate tools |\n| `SPECTER_API_KEY` | optional | — | Client api-key. **Not needed after sign-in** — the dev key from your login is reused. Set it only if you want read tools to work before signing in. |\n| `SPECTER_PROJECT_ID` | optional | — | Auto-discovered from your sign-in. Only set it if your organisation has multiple projects and you want to pin one. |\n| `SPECTER_ADMIN_TOKEN` | optional | — | For CI / non-interactive use instead of browser sign-in |\n\n---\n\n## Things to ask Claude\n\nOnce installed, just describe what you want — the right skill (and MCP tool) kicks in automatically:\n\n- *\"Add silent device login and a coins wallet to my game.\"*\n- *\"Set up a daily quest: play 5 matches → reward 200 coins. Create it in my Specter project and\n  give me the client code.\"*\n- *\"Create a premium gem currency and a starter store that sells a 'Sword' item for 100 gems.\"*\n- *\"Add a weekly leaderboard with top-10 prize distribution.\"*\n- *\"Build a battle pass with 30 tiers.\"*\n- *\"Add skill-based matchmaking with parties — show me the WebSocket events to handle.\"*\n- *\"Why am I getting a 429 from Specter?\"*\n- *\"Is my Specter project set up correctly?\"*\n\n---\n\n## Checking the version & updating\n\n```bash\n# Latest version published on npm\nnpm view specter-skills version\n\n# Which skills you have installed (and their versions)\nnpx specter-skills list\n\n# Update your installed skills to the latest\nnpx specter-skills update\n```\n\n> `npx` caches packages for ~24h. If `update` pulls an old version, force the latest with\n> `npx specter-skills@latest update`. The MCP server (`npx … specter-mcp`) always fetches the\n> latest published version the same way.\n\n---\n\n## Requirements\n\n- **Node.js 18+**\n- A **Specter project + API key** ([console.specterapp.xyz](https://console.specterapp.xyz))\n- A **skills-aware Claude host** (Claude Code, Claude Desktop, or the Agent SDK) for the skills;\n  an **MCP-compatible host** for the server\n\n---\n\n## Troubleshooting\n\n| Symptom | Fix |\n|---|---|\n| `specter-mcp: command not found` | Run it from a folder **other than** the `specter-skills` source folder (e.g. `cd ~` first). |\n| `No api-key available` | Set `SPECTER_API_KEY`, or run `specter-mcp login` (its dev key is then reused). |\n| `Multiple projects` on a create tool | Tell Claude which project (it's auto-detected when you have one). |\n| Create tools don't appear | Set `SPECTER_ALLOW_MUTATIONS=true` and restart your MCP host. |\n| Browser login times out | Re-run `specter-mcp login`; if the browser didn't open, use the printed URL. |\n| Skills don't activate | Confirm they're installed (`npx specter-skills list`) and your host loads `.claude/skills/`. |\n| 401 / 402 / 429 from the API | See the `specter` skill's error reference (auth, billing, rate limits). |\n\n---\n\n## Links\n\n- 🎮 Dashboard: [console.specterapp.xyz](https://console.specterapp.xyz)\n- 📦 npm: [npmjs.com/package/specter-skills](https://www.npmjs.com/package/specter-skills)\n\n---\n\n<details>\n<summary><b>Maintenance (Specter team)</b></summary>\n\n- **Endpoint references are generated.** `npm run generate` regenerates\n  `skills/*/references/endpoints{,/-index}.md` from `gamestarz_dashboard_backend/docs/api/`\n  (override the source dir with `SPECTER_DOCS_DIR`). Unmapped endpoint docs fail the build, so the\n  skills can't silently drift from the API.\n- **Secret linter.** `npm run lint:secrets` (also runs on `prepublishOnly`) blocks secrets and\n  internal hostnames from being published.\n- Hand-written content lives in each skill's `SKILL.md` and the non-generated `references/*.md`.\n  The MCP server lives in `mcp/src/`.\n\n### Releasing\n\n```bash\nnpm version patch        # or minor / major\nnpm run generate         # refresh references\nnpm publish --access public\n```\n\nThe `files` allowlist ships `bin/`, `skills/`, `mcp/src/*.mjs`, and `README.md`. Skills and the\nMCP server publish together as the single `specter-skills` package.\n\n</details>\n",
  "bytes": 15447,
  "sha": "b2ebcd5a0b2cc3140b7f8dff2f97952f04cfbdf3a13b38fb818e72d9ffdfd522",
  "repo_slug": "dirtcubeinteractive/specter-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dirtcubeinteractive_specter_sk_0e3012b4/readme"
}