pocket-arcade-index
Routes any Pocket Arcade task to the skills it needs - the skill catalogue, a task-to-skills matrix, build orders for the Shell and each new game, loading and reporting. Use when starting or planning a task, or unsure which skill applies. Not for product rules (pocket-arcade-product-spec).
- License 许可
- MIT
- 最近更新
- 2026-11-05
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- pocket-arcade-index
- description
- Routes any Pocket Arcade task to the skills it needs - the skill catalogue, a task-to-skills matrix, build orders for the Shell and each new game, loading and reporting. Use when starting or planning a task, or unsure which skill applies. Not for product rules (pocket-arcade-product-spec).
02 资源文件 55
- 资产文件assets/index.json134.0 KB
- 资产文件assets/shared.json73 B
- 参考文档references/build-orders.md91.9 KB
- 参考文档references/loading-and-reporting.md9.1 KB
- 参考文档references/skill-table.md17.1 KB
- 参考文档references/task-matrix.md13.7 KB
- 脚本scripts/build-index.mjs5.0 KB
- 脚本scripts/check-index.mjs14.9 KB
- 脚本scripts/check-lib.mjs44.4 KB
- 脚本scripts/lib/index-model.mjs20.9 KB
- 脚本scripts/lib/step-closure.mjs22.2 KB
- 脚本scripts/selftest.mjs1.2 KB
- 参考文档tests/fixtures/build-index/bad-extra-order-shape/EXPECT.txt52 B
- 参考文档tests/fixtures/build-index/bad-index-data/EXPECT.txt39 B
- 参考文档tests/fixtures/build-index/bad-markers-missing/EXPECT.txt29 B
- 参考文档tests/fixtures/build-index/bad-stale-render/EXPECT.txt72 B
- 参考文档tests/fixtures/build-index/bad-unknown-skill/EXPECT.txt52 B
- 参考文档tests/fixtures/check-index/bad-command-unknown/EXPECT.txt101 B
- 参考文档tests/fixtures/check-index/bad-command-unknown/README.md217 B
- 参考文档tests/fixtures/check-index/bad-description-changed/EXPECT.txt44 B
- 参考文档tests/fixtures/check-index/bad-duplicate/EXPECT.txt53 B
- 参考文档tests/fixtures/check-index/bad-extra-order-command/EXPECT.txt108 B
- 参考文档tests/fixtures/check-index/bad-extra-order-command/README.md217 B
- 参考文档tests/fixtures/check-index/bad-extra-order-duplicate/EXPECT.txt109 B
- 参考文档tests/fixtures/check-index/bad-extra-order-duplicate/README.md217 B
- 参考文档tests/fixtures/check-index/bad-index-data/EXPECT.txt34 B
- 参考文档tests/fixtures/check-index/bad-markers-missing/EXPECT.txt47 B
- 参考文档tests/fixtures/check-index/bad-name-mismatch/EXPECT.txt67 B
- 参考文档tests/fixtures/check-index/bad-package-not-installed/EXPECT.txt158 B
- 参考文档tests/fixtures/check-index/bad-package-not-installed/README.md217 B
- 参考文档tests/fixtures/check-index/bad-quick-table-edited/EXPECT.txt27 B
- 参考文档tests/fixtures/check-index/bad-readme-missing/EXPECT.txt54 B
- 参考文档tests/fixtures/check-index/bad-readme-missing/README.md188 B
- 参考文档tests/fixtures/check-index/bad-readme-stale/EXPECT.txt68 B
- 参考文档tests/fixtures/check-index/bad-readme-stale/README.md251 B
- 参考文档tests/fixtures/check-index/bad-related-unknown/EXPECT.txt58 B
- 参考文档tests/fixtures/check-index/bad-skill-missing/EXPECT.txt75 B
- 参考文档tests/fixtures/check-index/bad-skill-stale/EXPECT.txt53 B
- 参考文档tests/fixtures/check-index/bad-slice-core-shape/EXPECT.txt43 B
- 参考文档tests/fixtures/check-index/bad-slice-core-shape/README.md217 B
- 参考文档tests/fixtures/check-index/bad-slice-core-skill-stale/EXPECT.txt62 B
- 参考文档tests/fixtures/check-index/bad-slice-core-skill-stale/README.md217 B
- 参考文档tests/fixtures/check-index/bad-step-import-later/EXPECT.txt147 B
- 参考文档tests/fixtures/check-index/bad-step-import-later/README.md217 B
- 参考文档tests/fixtures/check-index/bad-step-manifest/EXPECT.txt177 B
- 参考文档tests/fixtures/check-index/bad-step-manifest/README.md217 B
- 参考文档tests/fixtures/check-index/bad-task-count/args.json20 B
- 参考文档tests/fixtures/check-index/bad-task-count/EXPECT.txt39 B
- 参考文档tests/fixtures/check-index/bad-test-later-step/EXPECT.txt162 B
- 参考文档tests/fixtures/check-index/bad-test-later-step/README.md217 B
- 参考文档tests/fixtures/check-index/bad-uncovered/EXPECT.txt63 B
- 参考文档tests/fixtures/check-index/bad-verify-green-shape/EXPECT.txt45 B
- 参考文档tests/fixtures/check-index/bad-verify-green-shape/README.md217 B
- 参考文档tests/fixtures/check-index/good/EXPECT.txt74 B
- 参考文档tests/fixtures/check-index/good/README.md217 B
03 SKILL.md 正文
Pocket Arcade index
Every Pocket Arcade task starts here: find its row in the task table, load every skill the row names, build in the documented order, prove the work with each loaded skill's own checks, and report in the owner's format. The index lists exactly the skills that exist, and a script proves it.
Rules that must hold
- Load every skill of the matching row before writing code, plus every skill the owner names. A skill's rules and checks only protect work done with it loaded; loading only the most obvious skill is the most common way a task goes wrong (an unlocalised string, a screen that never met its design screenshot, a save written the wrong way).
- The owner's named skills are binding. "Skills: /toybox-screens /tdd-workflow ..." in a task means those skills are loaded and their definitions of done hold; the row's other skills are added, never swapped for them.
- Code is always test-first and always reported:
tdd-workflowjoins every task that changes code, andgit-commits-and-reportingevery task that commits or reports. The owner never reads code, so the tests and the report are the review. - Every screen task includes
toybox-visual-parity. The owner's rule: every built screen matches its Toybox design screenshot, in light and dark, English and Persian. - Build in the documented order and copy exactly each step's manifest (
references/build-orders.md): a layer starts only when the layer it depends on passes its check, and each step copies the templates, installs the packages and runs the generators its manifest lists, tests included. A screen built on untested rules fails in the wrong place, and a file fetched by following a tsc error means the manifest is wrong: report it instead. - Done means every loaded skill's checks print
RESULT: PASS, plusnpm run -s check:fastonce the repo has it.SKIPlines (a rule a repo fact puts out of reach: a screen outsideshell-slice.json, or a rule not yet due because a later build step creates its target,due at Shell step <n>: <file> not yet created) andNOT APPLICABLE(a fact proves the whole check does not apply) end inRESULT: PASSand count as a pass; exit 2 (nothing to check, bad input) never does. A check that could not run is named in the report with the reason, never skipped silently. - When no row fits, read the one-line descriptions in
references/skill-table.mdand load every skill whose description matches the task; when the task is about what the product must do, loadpocket-arcade-product-specfirst. Never guess a skill's content from its name. - The index lists exactly the skills in the library. After any skill is added, removed, renamed or re-described, run
build-index.mjs --writeandcheck-index.mjs; a stale index routes tasks to skills that are gone.
The task table
Several rows can apply to one task: load the union. The notes for each row, and a longer explanation, are in references/task-matrix.md.
<!-- generated:task-table:start (build-index.mjs; edit assets/index.json instead) -->
| Task | Load these skills (the first one leads) |
|---|---|
| Bootstrap the monorepo from an empty or docs-only repo | monorepo-bootstrap dependency-management quality-gates typescript-and-lint-rules architecture-and-boundaries unit-and-component-tests git-commits-and-reporting |
| Build the Home screen (S4) | toybox-screens toybox-components toybox-design-system i18n-strings-and-catalogs rtl-and-direction accessibility toybox-visual-parity unit-and-component-tests tdd-workflow navigation-and-routing daily-and-statistics admob-ads |
| Build or change any other Shell screen, overlay or dialog (S1-S15) | toybox-screens toybox-components toybox-design-system i18n-strings-and-catalogs rtl-and-direction accessibility toybox-visual-parity react-components-and-hooks navigation-and-routing unit-and-component-tests tdd-workflow android-emulator-build |
| Build the Settings screen or add a setting (S11) | settings-and-preferences toybox-screens state-stores save-persistence-and-migrations i18n-strings-and-catalogs rtl-and-direction toybox-visual-parity tdd-workflow |
| Sell Premium or change the purchase flow (S12) | premium-purchase toybox-screens state-stores save-persistence-and-migrations i18n-strings-and-catalogs toybox-visual-parity privacy-and-network-audit tdd-workflow android-release-play |
| Add or change ads, consent, the ATT tracking permission or a rewarded perk | admob-ads architecture-and-boundaries game-host-integration settings-and-preferences privacy-and-network-audit unit-and-component-tests tdd-workflow android-emulator-build |
| Add or restyle a Toybox component | toybox-components toybox-design-system code-drawn-art-and-icons accessibility react-components-and-hooks unit-and-component-tests tdd-workflow toybox-visual-parity |
| Change colours, fonts, dark mode or a game's palette | toybox-design-system accessibility toybox-visual-parity toybox-components |
| Add an icon, a game logo, the app icon or the splash | code-drawn-art-and-icons toybox-design-system golden-tests ios-simulator-build |
| Add or change visible text, a message key or a translation | i18n-strings-and-catalogs rtl-and-direction naming-conventions accessibility |
| Fix right-to-left layout, mirrored icons or Persian digits | rtl-and-direction i18n-strings-and-catalogs toybox-visual-parity e2e-maestro |
| Add a route or wire navigation between screens | navigation-and-routing toybox-screens react-components-and-hooks state-stores tdd-workflow |
| Add a store, an action or a selector | state-stores save-persistence-and-migrations react-components-and-hooks unit-and-component-tests tdd-workflow |
| Change what is saved or the save format | save-persistence-and-migrations state-stores golden-tests git-commits-and-reporting tdd-workflow |
| Build the daily challenge, streaks or the statistics | daily-and-statistics level-generation-and-solvers state-stores save-persistence-and-migrations toybox-screens toybox-visual-parity tdd-workflow |
| Start a new game app | new-game-scaffold pocket-arcade-product-spec dependency-management architecture-and-boundaries git-commits-and-reporting |
| Write or change a game's rules, moves or scoring | game-rules-engine tdd-workflow unit-and-component-tests naming-conventions game-balance-and-bots |
| Add levels, a solver, par, stars, packs or the daily level | level-generation-and-solvers game-rules-engine golden-tests daily-and-statistics tdd-workflow |
| Draw or animate a game board | board-rendering-skia board-gestures-and-input golden-tests accessibility performance-budgets rtl-and-direction tdd-workflow |
| Add taps, swipes, drags or aim on a board | board-gestures-and-input board-rendering-skia game-rules-engine accessibility tdd-workflow |
| Build a real-time game or a simulate-then-replay phase | realtime-game-loop board-rendering-skia board-gestures-and-input game-rules-engine game-balance-and-bots performance-budgets golden-tests |
| Add or tune sounds, music or haptics | game-audio-and-haptics settings-and-preferences board-rendering-skia game-host-integration |
| Balance difficulty or add bots and sims | game-balance-and-bots game-rules-engine level-generation-and-solvers git-commits-and-reporting |
| Wire a game into the Shell (Game screen, Pause, Result, run end) | game-host-integration state-stores daily-and-statistics navigation-and-routing toybox-screens board-rendering-skia admob-ads i18n-strings-and-catalogs |
| Write or fix end-to-end flows or the screenshot matrix | e2e-maestro ios-simulator-build toybox-visual-parity privacy-and-network-audit golden-tests android-emulator-build |
| Prove a screen matches its Toybox design screenshot | toybox-visual-parity ios-simulator-build toybox-screens toybox-components toybox-design-system android-emulator-build |
| Build, run or smoke-test on the iOS simulator | ios-simulator-build troubleshooting-playbook architecture-and-boundaries |
| Port a game to Android | android-emulator-build pocket-arcade-product-spec architecture-and-boundaries unit-and-component-tests privacy-and-network-audit toybox-visual-parity e2e-maestro tdd-workflow git-commits-and-reporting |
| Build, run or smoke-test on the Android emulator | android-emulator-build troubleshooting-playbook architecture-and-boundaries |
| Release a game to TestFlight | ios-release-testflight premium-purchase privacy-and-network-audit e2e-maestro toybox-visual-parity game-balance-and-bots i18n-strings-and-catalogs git-commits-and-reporting |
| Release a game to Google Play internal testing | android-release-play premium-purchase privacy-and-network-audit android-emulator-build git-commits-and-reporting |
| Add, upgrade or remove an npm package | dependency-management privacy-and-network-audit performance-budgets ios-simulator-build quality-gates |
| Move to a new Expo SDK or Xcode version | expo-sdk-upgrade dependency-management board-gestures-and-input unit-and-component-tests golden-tests ios-simulator-build e2e-maestro |
| A quality gate, hook or verify run fails | quality-gates troubleshooting-playbook typescript-and-lint-rules unit-and-component-tests |
| Fix a TypeScript or ESLint error, or split a file that is too long | typescript-and-lint-rules naming-conventions architecture-and-boundaries quality-gates |
| Place a new file, package, port or adapter | architecture-and-boundaries naming-conventions typescript-and-lint-rules unit-and-component-tests |
| Something errors, crashes, hangs or renders wrong | troubleshooting-playbook quality-gates ios-simulator-build |
| Check or improve performance | performance-budgets board-rendering-skia react-components-and-hooks realtime-game-loop |
| Review accessibility or VoiceOver | accessibility toybox-components i18n-strings-and-catalogs e2e-maestro |
| Prove the app makes no network requests, or answer App Privacy (tracking, ATT, the privacy manifest) | privacy-and-network-audit admob-ads premium-purchase e2e-maestro dependency-management android-emulator-build |
| A golden or snapshot test shows a diff | golden-tests level-generation-and-solvers board-rendering-skia git-commits-and-reporting |
| Commit, tag, report to the owner or ask the owner a question | git-commits-and-reporting pocket-arcade-product-spec quality-gates |
| Find out what the spec requires (a screen, rule, feature or game) | pocket-arcade-product-spec pocket-arcade-index |
| Create, change or repair a skill | skill-maintenance pocket-arcade-index git-commits-and-reporting |
| <!-- generated:task-table:end --> |
Workflow
- Match the task. Find its row (or rows) in the table above. A spec ID in the task (S4, N3, 8.8) points at a screen or rule: the row for that screen or area, plus
pocket-arcade-product-specto quote it exactly. - Load the skills. Load each skill of the row with the Skill tool (or
/skill-name), the lead first, and read each one's Rules and Definition of done before starting. references/loading-and-reporting.md explains loading, the owner's "Skills:" line and what to do when a skill will not load. - Place the work. For building the Shell or a new game, find the current step in references/build-orders.md; do not start a step whose predecessor has not passed its check. Copy exactly what the step's manifest ("What each Shell step copies, installs and generates"; Shell step 9 screen by screen, each screen with the files it borrows) lists, from the named skill's
templates/orexamples/by the repo path on each template's first line, install its packages withplan-dependency.mjs(dependency-management), and run its generators; every SKIP line the step's done-when names is expected, any other SKIP or FAIL is not. Run each step's "done when" commands exactly as written there (repo root as the first argument, never--root). A repo without every Shell screen declares it inshell-slice.json(the same reference says how, lists the partial Shell core every Shell app keeps whatever the slice, gives the order for adding the pilot's Game, Pause and Result to an existing slice, and says that a slice never ships), and its table "When npm run verify is green" says which verify steps are still expected red at the current step. - Do the work as the lead skill's workflow says, test-first, with the other loaded skills' rules applied to the parts they own.
- Prove it. Run every loaded skill's definition-of-done checks and
npm run -s check:fast; fix everyFAILline and rerun until each printsRESULT: PASS. - Report. Write the owner report as references/loading-and-reporting.md ("Reporting") says: outcome first, the skills used, their
RESULTlines, what was not verified, the owner's own checks under "Owner steps (not blocking)" (the fa and ckb review, the play-test, the sound previews: listed, never waited for), at most one question. - Keep the index exact (only when skills changed):
node ${CLAUDE_SKILL_DIR}/scripts/build-index.mjs --write, thennode ${CLAUDE_SKILL_DIR}/scripts/check-index.mjs --readme skills/README.md(the library README's catalogue is checked too; add the new skill there by hand), fixing everyFAILline until it printsRESULT: PASS.
Definition of done
- [ ] Every skill of the matching rows, and every skill the owner named, was loaded before the work started.
- [ ] Each loaded skill's definition-of-done checks print
RESULT: PASS(SKIP lines and NOT APPLICABLE included; an exit 2 is not a pass, and the report names any check that could not run and why), andnpm run -s check:fastis green. - [ ] Build work followed the build order; no step started before its predecessor passed.
- [ ] The report names the skills used, their
RESULTlines and what was not verified. - [ ] After any change to the skill set or a description,
build-index.mjs --writeran. - [ ]
node ${CLAUDE_SKILL_DIR}/scripts/check-index.mjsprintsRESULT: PASS
Anti-patterns
- Loading one skill because its name matches. "Build the Home screen" with only
toybox-screensmisses the texts, the mirroring, the VoiceOver names and the design comparison; load the whole row. - Starting the board before the rules are proven. The build order exists because a layer debugged through the layer above it costs many times more.
- Declaring done from
check:fastalone. Each loaded skill has its own check for the things lint and Jest cannot see (testIDs, copy keys, save order, parity). - Reading an exit 2 as "not applicable". Exit 2 means the check found nothing to check or got bad input (often a guessed
--root); rerun it with the command from the build order. OnlySKIPlines andNOT APPLICABLEbeforeRESULT: PASSmean a rule did not apply. - Editing
references/skill-table.mdor the task table by hand. The next generation overwrites it andcheck-index.mjsreports it; editassets/index.jsonor the skill's description, then regenerate. - Inventing a skill name ("the audio skill", "/ads"). Use the exact names from the catalogue; a wrong name loads nothing.
- A report that lists work instead of outcome. The owner reads the first lines only: what now works for players, then the evidence.
Files in this skill
| File | What it is | Read/run when |
|---|---|---|
| references/skill-table.md | Every skill with its description, by group (generated) | When no task row fits, or to see what a skill covers |
| references/task-matrix.md | The task table with a note per row (generated) | Workflow step 1 |
| references/build-orders.md | Build order for the Shell with the pilot game and for every new game: step, skills, the exact "done when" commands (with the not-yet-due SKIP lines each step expects); the partial Shell (shell-slice.json), its core files and owners, the pilot game into an existing slice, and when npm run verify is green (generated) |
Workflow step 3 |
| references/loading-and-reporting.md | Loading skills by name or /name, the owner's "Skills:" line, compaction, reporting, asking the owner |
Workflow steps 2 and 6 |
assets/index.json |
The curated data: groups, task rows, build steps with their manifests (copies, installs, generates, and Shell step 9's screens), the partial Shell core (buildOrders.sliceCore) and the extra orders (buildOrders.extraOrders, with the Shell steps they start from in base) (the one place to edit) |
When the skill set, a task pattern, a build step or a template's place changes |
scripts/build-index.mjs |
Renders the generated parts from assets/index.json and every skill's frontmatter; without --write it only reports |
Workflow step 7 |
scripts/check-index.mjs |
Proves the index (and, with --readme, the library README's catalogue) lists exactly the skills present, routes to each, is current, that every <name>.mjs command in the build orders is a real script of the skill named after it (command-unknown), and that every step's manifest is import-closed (step-import-closure: each copied file's imports are copied or generated by then, its npm packages installed, its test copied in the same step; step-manifest: each copy names real templates of a skill the step loads, each install brings its companions) |
Workflow step 7 and the definition of done |
scripts/lib/index-model.mjs |
Frontmatter reader, data loader (with the step-manifest shape) and renderers shared by both scripts | Never by hand |
scripts/lib/step-closure.mjs |
The build-order contract: finds each copied template by its line-1 repo path and plays an order step by step (imports, installs, tests, coverage) | Never by hand; read it when a step-import-closure line is unclear |
scripts/selftest.mjs |
Proves both scripts pass a good library and catch each planted bug | After changing a script |
scripts/check-lib.mjs |
Shared script helper, synced from the library (do not edit here) | Never by hand |
assets/shared.json |
Declares the shared files this skill copies in | When adding a shared file |
tests/fixtures/ |
Small skill libraries, good and planted-bad, for both scripts | When adding a rule |
Related skills
pocket-arcade-product-spec- what the product must do: screens, rules, features, games and open decisions.tdd-workflow- the test-first loop every code task follows.git-commits-and-reporting- commit messages and the owner report format.skill-maintenance- adding or changing a skill (then regenerate this index).
04 同仓库更多 Skills
unit-and-component-tests
Sets up Jest and writes Pocket Arcade test code - three projects, RNTL 14 async via renderWithShell, root SDK mocks, fakes, fast-check, coverage, Stryker. Use when a test needs the Shell wrapper, a mock or a fake, or Jest fails. Not for the red-green loop (tdd-workflow) or goldens (golden-tests).
typescript-and-lint-rules
Enforces Pocket Arcade's strict TypeScript 6 tsconfigs, ESLint 9 flat config, Prettier and size limits. Use when writing or splitting .ts/.tsx or fixing a tsc or lint error. Not for gate wiring (quality-gates), names (naming-conventions) or import zones (architecture-and-boundaries).
demo-skill
Builds a demo. Use when testing the pitfall checker.
demo-skill
Builds a demo. Use when testing the pitfall checker.
troubleshooting-playbook
Diagnoses and fixes Pocket Arcade failures with a catalogue of 300+ known ones (symptom, cause, fix). Use when something errors, crashes, hangs or renders wrong, or an error or log needs explaining. Not for gate setup (quality-gates) or running builds (ios-simulator-build, ios-release-testflight).
toybox-visual-parity
Proves a built Pocket Arcade screen matches its Toybox design screenshot (light/dark, en/fa) and drives the fixes: capture, element gates, sheets, sign-off. Use when any screen is built or changed, or for visual parity, design match, screenshot compare. Not for building screens (toybox-screens).