skill-maintenance
Adds, updates and repairs Pocket Arcade skills to the authoring standard - scaffold, SKILL.md, description, scripts and self-tests, validator, sources, routing evals. Use when creating, editing or checking a skill, or one does not load or trigger. Not for app failures (troubleshooting-playbook).
- License 许可
- MIT
- 最近更新
- 2026-11-05
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- skill-maintenance
- description
- Adds, updates and repairs Pocket Arcade skills to the authoring standard - scaffold, SKILL.md, description, scripts and self-tests, validator, sources, routing evals. Use when creating, editing or checking a skill, or one does not load or trigger. Not for app failures (troubleshooting-playbook).
02 资源文件 70
- 资产文件assets/routing-evals.json15.1 KB
- 资产文件assets/shared.json73 B
- 参考文档examples/new-skill-walkthrough.md7.3 KB
- 参考文档references/authoring-standard.md22.0 KB
- 参考文档references/descriptions-and-routing.md8.3 KB
- 参考文档references/how-skills-load.md8.7 KB
- 参考文档references/library-commands.md16.1 KB
- 参考文档references/writing-scripts.md14.8 KB
- 脚本scripts/check-lib.mjs44.4 KB
- 脚本scripts/check-routing.mjs8.1 KB
- 脚本scripts/check-skill-set.mjs7.1 KB
- 脚本scripts/check-skill.mjs11.8 KB
- 脚本scripts/lib/live-route.mjs5.1 KB
- 脚本scripts/lib/router.mjs3.2 KB
- 脚本scripts/lib/skill-md.mjs5.6 KB
- 脚本scripts/new-skill.mjs6.4 KB
- 脚本scripts/selftest.mjs1.7 KB
- 参考文档templates/new-skill/assets/shared.json73 B
- 其他templates/new-skill/references/background.md.tmpl269 B
- 脚本templates/new-skill/scripts/check-rules.mjs2.4 KB
- 脚本templates/new-skill/scripts/selftest.mjs443 B
- 其他templates/new-skill/SKILL.md.tmpl1.9 KB
- 参考文档templates/new-skill/tests/fixtures/bad-example/EXPECT.txt36 B
- 脚本templates/new-skill/tests/fixtures/bad-example/src/example.ts240 B
- 参考文档templates/new-skill/tests/fixtures/error-missing-root/ARGS.txt15 B
- 参考文档templates/new-skill/tests/fixtures/error-missing-root/EXPECT.txt95 B
- 脚本templates/new-skill/tests/fixtures/good/skills/demo-skill/tests/fixtures/bad-planted/src/planted.ts188 B
- 脚本templates/new-skill/tests/fixtures/good/src/example.ts229 B
- 参考文档tests/fixtures/check-routing/bad-bad-evals/evals.json205 B
- 参考文档tests/fixtures/check-routing/bad-bad-evals/EXPECT.txt63 B
- 参考文档tests/fixtures/check-routing/bad-live-other-tool-first/args.json52 B
- 参考文档tests/fixtures/check-routing/bad-live-other-tool-first/calls.json166 B
- 参考文档tests/fixtures/check-routing/bad-live-other-tool-first/evals.json114 B
- 参考文档tests/fixtures/check-routing/bad-live-other-tool-first/EXPECT.txt50 B
- 脚本tests/fixtures/check-routing/bad-live-other-tool-first/fake-claude.mjs768 B
- 参考文档tests/fixtures/check-routing/bad-miss/args.json21 B
- 参考文档tests/fixtures/check-routing/bad-miss/evals.json112 B
- 参考文档tests/fixtures/check-routing/bad-miss/EXPECT.txt52 B
- 参考文档tests/fixtures/check-routing/good/args.json21 B
- 参考文档tests/fixtures/check-routing/good/evals.json342 B
- 参考文档tests/fixtures/check-routing/pass-live-session-start/args.json52 B
- 参考文档tests/fixtures/check-routing/pass-live-session-start/calls.json235 B
- 参考文档tests/fixtures/check-routing/pass-live-session-start/evals.json114 B
- 参考文档tests/fixtures/check-routing/pass-live-session-start/EXPECT.txt32 B
- 脚本tests/fixtures/check-routing/pass-live-session-start/fake-claude.mjs768 B
- 参考文档tests/fixtures/check-skill-set/bad-budget/args.json26 B
- 参考文档tests/fixtures/check-skill-set/bad-budget/EXPECT.txt37 B
- 参考文档tests/fixtures/check-skill-set/bad-duplicate/EXPECT.txt58 B
- 参考文档tests/fixtures/check-skill-set/bad-index/EXPECT.txt51 B
- 参考文档tests/fixtures/check-skill-set/bad-not-for/EXPECT.txt45 B
- 参考文档tests/fixtures/check-skill-set/bad-overlap/EXPECT.txt47 B
- 参考文档tests/fixtures/check-skill/bad-description/EXPECT.txt37 B
- 参考文档tests/fixtures/check-skill/bad-expect/EXPECT.txt55 B
- 参考文档tests/fixtures/check-skill/bad-mixed-placeholder/EXPECT.txt31 B
- 参考文档tests/fixtures/check-skill/bad-neighbours/EXPECT.txt59 B
- 参考文档tests/fixtures/check-skill/bad-orphans/EXPECT.txt241 B
- 参考文档tests/fixtures/check-skill/bad-placeholders/EXPECT.txt209 B
- 参考文档tests/fixtures/check-skill/bad-rules/EXPECT.txt110 B
- 参考文档tests/fixtures/check-skill/bad-sources/args.json36 B
- 参考文档tests/fixtures/check-skill/bad-sources/EXPECT.txt75 B
- 参考文档tests/fixtures/check-skill/bad-sources/sources.json316 B
- 参考文档tests/fixtures/check-skill/good/args.json36 B
- 参考文档tests/fixtures/check-skill/good/sources.json566 B
- 参考文档tests/fixtures/new-skill/bad-exists/args.json28 B
- 参考文档tests/fixtures/new-skill/bad-exists/EXPECT.txt47 B
- 参考文档tests/fixtures/new-skill/bad-format/args.json36 B
- 参考文档tests/fixtures/new-skill/bad-format/EXPECT.txt34 B
- 参考文档tests/fixtures/new-skill/bad-reserved/args.json23 B
- 参考文档tests/fixtures/new-skill/bad-reserved/EXPECT.txt51 B
- 参考文档tests/fixtures/new-skill/good/args.json56 B
03 SKILL.md 正文
Skill maintenance
Makes every change to a Pocket Arcade skill land finished: built to the authoring standard, self-contained, routed by a sharp description, proven by its own self-test, and recorded against the project files it was copied from. The owner never reads the skills, so a skill is correct only when the checks here say so.
Rules that must hold
- A skill is done only when the checks pass. The library validator, the skill's own self-test and
check-skill.mjsall printRESULT: PASS; nothing else counts, because the owner never reads skill files. - Copy knowledge in; never point at it. No handbook chapter, spec, design file, research note, scratch path, other skill's folder or library internal file is named in a skill; skills are loaded alone and pointers go stale.
- The description decides whether the skill is ever used. At most 300 characters, a verb first, trigger words, "Use when", and "Not for <work> (<neighbour-skill>)"; Claude sees nothing else before it invokes a skill.
- Rules and the definition of done sit at the top, and SKILL.md stays at 300 lines or fewer. After compaction only the first 5,000 tokens of a skill survive.
- Every script proves itself. A good fixture and one bad fixture per rule with an EXPECT naming the rule id; nothing to check exits 2. A check that has only ever passed proves nothing.
- Edit the canonical copy, never a synced or generated file. Shared files change in the library and arrive through sync-shared; generated references change through their generator. The next sync or render erases a hand edit, and the validator fails on drift.
- Record every copy from the project, and re-copy (never just re-record) when a source changes. The staleness check works only with records, and re-recording hides the drift.
- Only frontmatter
nameanddescription. Neverdisable-model-invocation,allowed-tools,hooks,pathsoruser-invocable: the owner names skills in plain words, and those keys hide the skill or make its invocation need approval. - Touch only the skill you were asked to change (plus its prompts in this skill's routing evals). Other builders work in parallel, writes under
.claude/need the owner, and the library belongs to the lead; propose other changes in the report instead.
Workflow
- Decide: new skill or change to an existing one. List
skills/and runnode ${CLAUDE_SKILL_DIR}/scripts/check-routing.mjs --skills-root skills --prompt "<the task>"to see which skill already wins that task. Read references/descriptions-and-routing.md when the boundary is unclear. - New skill:
node ${CLAUDE_SKILL_DIR}/scripts/new-skill.mjs <name> --skills-root skills, thennode skills/_library/sync-shared.mjs <name>. The scaffold (templates/new-skill/) holds the six sections, a reference, a working pattern checker with its self-test and fixtures, and__FILL_...__placeholders wherever you must write. Read references/authoring-standard.md before filling it; examples/new-skill-walkthrough.md shows a complete run. - Knowledge: copy it into
references/(a Contents list over 100 lines),templates/(real files: test them in a scratch copy of a verified workspace withtsc, ESLint and Jest; nevernpm installthrough a symlinkednode_modules),examples/andassets/. After each copy from the project runnode skills/_library/record-sources.mjs <name> <skill-file> <project-files>; references/library-commands.md has every library command. - Scripts: read references/writing-scripts.md. Write each checker on
check-lib.mjs, one bad fixture per rule, and run the checker on a real verified workspace to be sure it has no false findings. - Description: write it with the descriptions reference, then add two realistic prompts for the skill to
assets/routing-evals.jsonin this skill. - Check the skill:
node skills/_library/validate-skills.mjs <name>,node skills/<name>/scripts/selftest.mjs, thennode ${CLAUDE_SKILL_DIR}/scripts/check-skill.mjs skills/<name>. Fix everyFAILline and rerun until all three pass. - Check the set:
node ${CLAUDE_SKILL_DIR}/scripts/check-skill-set.mjs skillsandnode ${CLAUDE_SKILL_DIR}/scripts/check-routing.mjs --skills-root skills. A problem your change caused is yours to fix; one that belongs to a skill still being built goes into the report (--skip-missingturns evals for unbuilt skills into notes). After a new or changed description, confirm with Claude itself:check-routing.mjs --skills-root skills --live --only <name> --runs 3(a few short model calls). - Library round:
node skills/_library/sync-shared.mjs,node skills/_library/validate-skills.mjs,node skills/_library/selftest-all.mjs <name>,node skills/_library/check-staleness.mjs <name>, thennode skills/_library/link-skills.mjsso Claude Code sees a new skill (the owner approves the write under.claude/). - When a skill does not load, trigger or run, match the symptom in the pitfalls table of references/how-skills-load.md.
- Report: the skill, its description, what its scripts check, the
RESULTlines, and anything left for the owner or the lead (links, settings, another group's skill).
Definition of done
- [ ]
node skills/_library/validate-skills.mjs <name>printsRESULT: PASS, and so doesnode skills/<name>/scripts/selftest.mjswhen the skill has scripts. - [ ] Every file copied from the project has recorded sources, and
node skills/_library/check-staleness.mjs <name>printsRESULT: PASS. - [ ]
check-skill-set.mjs skillsshows no problem caused by this change, andcheck-routing.mjs --skills-root skillspasses (with--skip-missingonly while other skills are still being built). - [ ]
node ${CLAUDE_SKILL_DIR}/scripts/check-skill.mjs skills/<name>printsRESULT: PASS
Anti-patterns
- "See the handbook, chapter 14, for the details." The chapter is not there when the skill runs elsewhere; copy the rows you need.
- Fixing a routing miss by pasting the eval's words into the description. Name the category of work, or add a "Not for" to the skill that won.
- Editing
scripts/check-lib.mjsin a skill. It is a synced copy; the next sync reverts it and the validator fails first. - A checker that exits 0 when its folder is missing. A typo then turns the gate green; exit 2.
- A bad fixture whose EXPECT says only "FAIL". It passes on any failure, including a crash; name the rule id and the line.
- Recording sources again to silence a stale warning. Re-copy the changed knowledge first.
- Writing the skill straight into
.claude/skills/. Every write there needs the owner's approval; author inskills/and link.
Files in this skill
| File | What it is | Read/run when |
|---|---|---|
| references/authoring-standard.md | The whole standard restated: placement, self-containment, anatomy, frontmatter, section order, scripts, templates, quality bar, every validator rule, what check-skill adds | Workflow step 2, before writing any skill file |
| references/library-commands.md | Every library command with options, exit codes and when to run it; sources.json; shared files; settings; the library's own tests | Workflow steps 3 and 8 |
| references/writing-scripts.md | The script contract, a complete checker, the check-lib API, self-tests, fixture patterns, packages | Workflow step 4 |
| references/descriptions-and-routing.md | The description formula and rules, good and bad examples, keeping descriptions apart, routing evals offline and live | Workflow steps 1, 5 and 7 |
| references/how-skills-load.md | Discovery, parsing, listing budget, invocation, compaction, permissions, diagnostics, pitfalls by symptom | Workflow step 9, and when a rule of the standard needs its reason |
| examples/new-skill-walkthrough.md | A real new skill from scaffold to PASS, and an update after a stale source | Workflow step 2 |
templates/new-skill/ |
The scaffold new-skill.mjs copies: SKILL.md.tmpl, a reference, check-rules.mjs, its self-test and fixtures, assets/shared.json |
Workflow step 2 (through the script) |
assets/routing-evals.json |
At least two realistic task prompts per skill with the skill that should win | Workflow steps 5 and 7 |
scripts/new-skill.mjs |
Creates a skill from the scaffold; refuses bad, reserved or taken names | Workflow step 2 |
scripts/check-skill.mjs |
Checks one skill is finished (boundaries, reasons, orphans, placeholders, self-test coverage, EXPECT ids, sources) | Workflow step 6 and the definition of done |
scripts/check-skill-set.mjs |
Checks the set: overlapping or duplicate descriptions, hand-offs, listing budget, index coverage | Workflow step 7 |
scripts/check-routing.mjs |
Routing evals, offline ranking or live with Claude Code | Workflow steps 1 and 7 |
scripts/lib/skill-md.mjs |
SKILL.md reader used by the checkers | Never by hand |
scripts/lib/router.mjs |
The offline ranking used by check-routing | When tuning the offline router |
scripts/lib/live-route.mjs |
Runs claude -p and reads the first deciding tool call, past the AGENTS.md session start |
Never by hand |
scripts/selftest.mjs |
Proves all four scripts pass good fixtures and catch every planted bug | After changing a script or the scaffold |
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/ |
Good and planted-bad skills, skill sets, eval files and scaffold cases | When adding a rule |
Related skills
troubleshooting-playbook- failures in the app or its tooling rather than in a skill.git-commits-and-reporting- committing a skill change and reporting it to the owner.
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).