Skills

Plugin skills, vendored skills, how to install them, and what is deliberately not vendored.

A skill teaches an agent how: patterns, gotchas and the order to decide things in. An MCP server gives it live data: the component list for the installed version, a running app. Both are needed. heroui-react teaches composition, and the HeroUI MCP says which components exist today.

Three kinds, and where each lives

Kind	Lives in	Managed by	Edit it?
Spec engine commands	spec-kit, .claude/skills/speckit-* and .opencode/commands/speckit.*, plus the Stackra preset in .specify/presets/stackra	specify (pinned in mise.toml), pnpm speckit:sync	Only the preset. The rendered copies are generated
Upstream skills the repository uses	.agents/skills/<upstream-name>	npx skills add, update, remove, pinned in skills-lock.json	No. Never in place
House skills	.agents/skills/<category>-<name>	A normal change	Yes

The spec engine

The spec flow is GitHub spec-kit, described on Spec lifecycle. The sdlc plugin no longer applies in this repository (ADR 0121 D3). Its failure-loop and durable-findings skills and eight of its roles are being ported into .agents/ under MIT (D2, D9); until they land, the procedures on Spec lifecycle are the reference.

Vendored upstream skills

Skills are checked into .agents/skills/ so that a clone, a second workspace and CI carry the guidance. Skills installed in a user’s home directory belong to one machine.

npx skills add <owner/repo> -s <skill> -y   # install one skill
npx skills update                            # update to upstream
npx skills remove <skill>                    # remove

skills-lock.json records each source. Install and update through the CLI only. Do not edit an installed skill in place: write a house skill, or open a change upstream.

That portability has a price. A vendored copy drifts from its source, silently, and nothing detects it. The mitigation is a rule: re-vendor deliberately, and when a vendored skill and its upstream disagree, upstream is the source. The families to install are listed below. Record each in this page when you add it.

Family	Install when
Monorepo and release (pnpm, turborepo, changesets, lefthook, commitlint, vite, vitest)	Now. They match the toolchain
Web UI (heroui-react, tailwind-4-docs, tanstack-query, react-hook-form, vercel-react-best-practices)	An app uses the package
Mobile (heroui-native, uniwind, expo-*, eas-*)	The mobile app grows past hello-world
Quality (tdd, code-review, security-review, accessibility, core-web-vitals, performance)	Now
Motion and design process	When design work starts

Fenced: the Encore reference

The fourteen encore-* skills from encoredev/skills teach hand-written Encore.ts. Here Encore is only the output of stackra gen in .stackra/encore/ (ADR 0124), so the skills live in .agents/reference/encore/, which is never projected: no session loads them by description match. compiler-engineer reads them on purpose as the reference for what the Encore emitter produces, and guardians may read them to judge generated output (ADR 0258). encore-getting-started, encore-migrate and encore-frontend were removed: they bootstrap, migrate to, or hand-connect a hand-written Encore app.

House skills

A house skill that this repository writes carries a category prefix: backend-, frontend-, mobile-, devops-, security-, db-, ai-, domain-, testing-, docs-, and code- for code conventions (ADR 0258). Upstream skills keep their upstream names, so npx skills update keeps working. The tree is flat on purpose: a skill is one SKILL.md in one top-level folder, so categories live in the name, not in folders.

House skills in this repository

Each is grounded in the ADRs it cites, uses one running example (refunding an invoice, billing.invoice.refund@1), ends with the check that enforces it, and says that the package’s own docs win once the package ships.

Skill	Teaches	ADRs
backend-author-an-action	@Action and @Query, the pipeline, idempotency, refusal codes, UX, adapters	0098, 0099, 0136–0139, 0155
backend-module-and-root-module	@Module key and name, the root module, kind folders, scopes, lifecycle, testing	0090, 0111, 0126, 0130, 0131, 0143
backend-decorator-package-with-explorer	A decorator over the metadata registry and its Explorer, with the gen conformance test	0005, 0117, 0144, 0247
backend-define-family	defineToken, defineConfig with secret refs, permissions, events, meters, skills	0132, 0145, 0146, 0215, 0216, 0245, 0247
backend-errors	StackraError, the ten categories, the envelope, client entries, testing	0137, 0140, 0232
backend-assets-and-storage	Module assets/, <module>::path keys, filesystem disks, client storage	0222, 0234, 0256
backend-gen-and-encore-target	What stackra gen reads and emits, the Encore target, --check, inspect and diff	0090, 0091, 0124, 0157, 0158, 0237
frontend-resource-console	@Resource, @Page, @Widget rendered by @stackra/panel	0110, 0164, 0165, 0183
db-models-and-migrations	Models, classification, RLS equality, gen-ordered migrations, raw SQL rule	0014, 0097, 0133, 0134, 0159, 0160, 0238, 0239
ai-mcp-tools	Which actions become MCP tools, approvals, context providers, skills, plans	0098, 0155, 0156, 0245
code-naming-and-casing	The naming table, # imports, enums, classes, components, docblocks	0006, 0007, 0128, 0231, 0233
docs-spec-flow	Lanes, change risk, spec-kit order, Linear, traceability, merge	0065, 0067, 0119, 0120, 0198
mobile-eas-setup	EAS profiles, channels, environments, fingerprint policy, .easignore	0061, 0180
mobile-release	Binary or OTA, gates, staged rollout, minimum version, rollback, human-only steps	0180
mobile-store-listing	Store metadata, privacy answers, screenshots, demo accounts	0134, 0180, 0190
docs-adr	Writing or superseding an ADR in the house format	0016

What is deliberately not vendored

A skill that is confidently wrong is worse than a missing one, because an agent follows it. The excluded set is not “less useful”. It is “would mislead someone working here”. Every absence has a recorded reason so nobody re-adds it as an oversight.

Skill or family	Why not
nestjs-development	Nest is on the not-built-yet list
drizzle-orm-patterns, db-schema-comments	Contradict the ORM decision
Worker templates (cloudflare-worker-development, hono-worker-development, node-worker-development, wrangler)	No Worker in the API path, and no Worker template
go-service-development, python-service-development	No Go or Python workspace
nextjs-development, react-development, vite-react-development, react-native-development	Superseded by the specific web and mobile skills
multi-tenant-safety-checker, security-tenancy-isolation-test, security-iam-model	Tenancy skills return with the first tenant-owned table
domain-billing-payments, domain-design, domain-scheduling-attendance, ai-mcp-tools	Product domains, not framework
stripe-*, resend, aws-*, astro	A vendor or platform this repository does not use
documentation-and-adrs	Duplicates docs-adr
sanity-best-practices	Sanity is dropped (0114)
typescript-patterns	Its @/* alias rule contradicts the # subpath aliases of ADR 0233
encore-getting-started, encore-migrate, encore-frontend	Teach authoring or adopting a hand-written Encore app (0124)

The rule behind the table: this repository must not presume a product domain, a vendor or a technology it ships no configuration for. Anything that contradicts an accepted decision is excluded outright. The same skills were also moved out of the owner’s user-level ~/.claude/skills (ADR 0193 decision 3), so they no longer load into Stackra sessions from there.

The rejected-technology check

pnpm agents:check (and node tools/scripts/agents-sync.mjs --lint) scans every skill in .agents/skills/ for technology the not-built-yet list rejects: other ORMs, Nest, reflect-metadata, encore.dev, expo-router, Next.js, Jest, ESLint, Prettier, Zustand, i18next, class-validator, Express, Fastify, Sanity, Tauri, Better Auth, XState, Storybook, GraphQL, and .spec test files or a root tests/ folder. A hit fails the check unless SKILL_TECH_ALLOWED in tools/scripts/agents-sync.mjs records why the mention is harmless, for example turborepo’s example task names. A vendored skill is never edited in place, so the exception lives in the script, with its reason.

Adding a skill

1. Is it upstream? Install it with npx skills add and record it here.
2. Is it a procedure someone re-derived, twice? Write a house skill with a category prefix. This is also where a finding that outlives its fix lands when the class is “procedure”.
3. Does it contradict an accepted decision or the not-built-yet list? Do not add it, or fence it in .agents/reference/ for the one agent that needs it. Route to architecture-guardian.
4. Hand the change to dependency-steward, who owns skills alongside catalogs.

Related: Roster, Hooks.