[deve1993]

Summary

Two connected changes:

1. SkillBrain serves skill support files. Files next to a skill's SKILL.md / AGENT.md (formats, templates, references/, rules/) are now imported and readable through skill_read({ name, file }). Until now only SKILL.md was served, so existing skills that cite sibling files were broken over MCP: ads and aso references/, vercel-react-best-practices rules/, hallmark LICENSE.
2. 17 skills from mattpocock/skills (MIT, @3cca18b), limited to the ones the superpowers plugin does not already cover, wired into AGENTS.md / CLAUDE.md.

Design: docs/superpowers/specs/2026-09-14-mattpocock-skills-integration-design.md · Plan: docs/superpowers/plans/2026-09-14-mattpocock-skills-integration.md

Changes

Part 1 — support files

• Storage. Migration 037_skill_files.sql and SkillsStore.replaceFiles / listFiles / getFile.
• Importer (packages/storage/src/import-skills.ts):
  • Collects every file inside a directory skill.
  • Skips dotfiles, binaries (NUL in the first 8 KB), files over 256 KB, and anything past 2 MB per skill (logged).
  • Skips unreadable files and directories with a warning instead of failing the whole import.
  • Each import replaces the skill's whole file set.
• Symlinks:
  • walkDir now follows symlinked skill directories. Without that, the entrypoint change below would have silently dropped every process skill from the prod import.
  • Support-file links must resolve inside the skill directory, and each directory is walked once.
• Dual-zone skills. About 29 bundle skills live in both data/skill/ and data/lifecycle-skills/, and the lifecycle copy has only SKILL.md. These keep the non-empty file set.
• Security gate scans SKILL.md together with its support files; the stored content is still SKILL.md.
• skill_read:
  • Lists "Supporting files".
  • Accepts file and ignores a leading ./.
  • Looks files up by exact key only, with no filesystem access.
  • Records telemetry only on reads without file.
• entrypoint.sh links whole lifecycle-skills/<name> directories, not only their SKILL.md.

Part 2 — 17 Matt Pocock skills

• The skills: grilling, grill-me, grill-with-docs, to-questionnaire, wait-what, domain-modeling, codebase-design, improve-codebase-architecture, setup-matt-pocock-skills, to-tickets, triage, wayfinder, research, teach, wizard, resolving-merge-conflicts, handoff.
• Where: vendored verbatim into .agents/skills/ (Codex, local import) and packages/codegraph/data/lifecycle-skills/ (prod bundle), plus _ATTRIBUTION-mattpocock-skills.md and CATEGORY_MAP → Process.
• Not imported:
  • tdd, diagnosing-bugs, code-review, implement, to-spec, prototype, writing-for-agents: covered by superpowers.
  • ask-matt, misc/*, in-progress/*.
  • The attribution file maps upstream cross-references to the superpowers equivalents.
• AGENTS.md gains a "Skill di Matt Pocock (da SkillBrain)" routing table. The 11 skills marked disable-model-invocation: true upstream start only on the user's explicit request. It also notes upstream side effects: setup-matt-pocock-skills edits CLAUDE.md, and resolving-merge-conflicts commits on its own.
• CLAUDE.md: do not install the mattpocock-skills plugin, since it duplicates superpowers. DEPLOY-SKILLS.md documents support files.

First prod boot

A final review simulated the new boot layout over the real bundle with the branch's importer:

• 344 skills imported, none lost, none retyped or recategorised, no new BLOCK
• 447 support files, 1.35 MB, about 315 ms
• all 17 new skills active, 34 support files

The bundle hash changes, so the boot import re-runs. Migration 037 applies on openDb().

Test plan

• pnpm --filter @skillbrain/storage test: 51/51. New: store files, support-file collection with limits, deletion on re-import, symlinked skill directory, unreadable file, malicious support file quarantined, dual-zone precedence, symlink containment, category mapping.
• packages/codegraph: tsc --noEmit clean, build ok, 315/315 (new: skill_read formatters, ./ normalisation).
• pnpm --filter @skillbrain/skill-guard test: 17/17.
• Entrypoint: sh -n plus a simulated double boot over the old layout.
• Vendored copies diff -r identical to upstream at the pinned SHA.
• Per-task spec and quality reviews, and a whole-branch review. Its fixes landed in 44ffe1f and passed re-review.
• After deploy: skill_read("teach") lists support files; skill_read({ name: "teach", file: "MISSION-FORMAT.md" }) returns it; skill_read("aso") and skill_read("vercel-react-best-practices") list their files; skill_route surfaces grilling, setup-matt-pocock-skills, codebase-design.

Known follow-ups (not in this PR)

• skill_update and skill_scan still scan only SKILL.md, and review findings don't name the support file. No catalog skill is affected today.
• Add an importer version to the entrypoint's bundle hash, so future importer-only changes re-import in prod.
• The skill_read handler wiring is covered by tsc only; the formatters have unit tests.

🤖 Generated with Claude Code