Skills - Stackra

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
Encore (`encore-api`, `encore-service`, `encore-database`, `encore-auth`, `encore-testing` and the rest)	The first service that uses Encore lands
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

House skills

A house skill that this repository writes carries a category prefix: backend-, frontend-, mobile-, devops-, security-, db-, ai-, domain-, testing-, docs-. 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.

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`

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.

Adding a skill

Is it upstream? Install it with npx skills add and record it here.
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”.
Does it contradict an accepted decision or the not-built-yet list? Do not add it. Route to architecture-guardian.
Hand the change to dependency-steward, who owns skills alongside catalogs.

Related: Roster, Hooks.

​Three kinds, and where each lives

​The spec engine

​Vendored upstream skills

​House skills

​What is deliberately not vendored

​Adding a skill