> ## Documentation Index > Fetch the complete documentation index at: https://docs.stackra.figentra.com/llms.txt > Use this file to discover all available pages before exploring further. # 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/` | `npx skills add`, `update`, `remove`, pinned in `skills-lock.json` | No. Never in place | | House skills | `.agents/skills/-` | A normal change | Yes | ### The spec engine The spec flow is GitHub spec-kit, described on [Spec lifecycle](/agents/spec-lifecycle). The `sdlc` plugin no longer applies in this repository ([ADR 0121](/adr/0121-sdlc-tooling-roles-and-linear) 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](/agents/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. ```bash theme={"system"} npx skills add -s -y # install one skill npx skills update # update to upstream npx skills remove # 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](/adr/0124-encore-is-the-generated-runtime-target)), 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](/adr/0258-agent-roster-v2-and-skill-fencing)). `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](/adr/0258-agent-roster-v2-and-skill-fencing)). 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/`, `::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](/adr/0227-rejected-and-deferred-technologies-refreshed) | | `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](/adr/0114-page-builder-for-every-page)) | | `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](/adr/0124-encore-is-the-generated-runtime-target)) | 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](/adr/0227-rejected-and-deferred-technologies-refreshed) 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](/agents/spec-lifecycle) 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](/agents/roster), [Hooks](/agents/hooks). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.