Cursor Skills

Project skills live under .agents/skills/. The skills CLI installs there for -a cursor (project scope). Cursor also reads .cursor/skills/ if present, but this repo commits the CLI layout only.

Cursor requires name in each SKILL.md to match the folder that contains it. That is why tech skills use a versioned dirname (fastify-v5, not fastify).

Rules override skills. Skills override the model. Indexed docs are advisory.

Catalogs

Two catalogs. Do not merge them.

FIRST stations — blockmatic/first. Nested /f-* playbooks.

npx skills add blockmatic/first

Tech — blockmatic/basilic-skills on skills.sh. Workflow (workflow) is a local preview until that catalog's main publishes the restored unprefixed tags.

Install or refresh tech skills (interactive — pick skills and agents):

pnpm dlx skills@latest add blockmatic/basilic-skills

Do not use --skill '*' from GitHub during this preview if main still ships a different workflow package. Refresh playbooks from the local catalog:

pnpm dlx skills@latest add /path/to/basilic-skills --skill workflow -a cursor --copy -y

That writes tech skills under .agents/skills/<name>/ and playbooks under .agents/skills/workflow/<name>/. Full installer options: catalog README.

Root skills-lock.json tracks catalog hashes. FIRST is source: blockmatic/first. The web-design-guidelines-v1 entry also records the pinned command.md commit digest. Commit the lock with .agents/skills/ after every refresh.

Two kinds

FIRST — .agents/skills/f/ plus nested f-<name>/. Slash-only station and role skills. Refresh from blockmatic/first, not basilic-skills.

Tech — .agents/skills/<topic>-v<major>/ (example: fastify-v5). Agent-invocable. Required sections: Scope, Assumptions, Principles, Constraints, Interactions. Force with @.agents/skills/<topic>-v<major> or /<topic>-v<major>.

Workflow — install the parent workflow skill; nested children are not independent install targets. .agents/skills/workflow/<name>/ (example: workflow/plan-feature). Slash-only. Set disable-model-invocation: true. One-line description. Not versioned. Type /plan-feature in Cursor. If a harness has no matching menu, read the SKILL.md file directly.

name is lowercase letters, digits, and hyphens, max 64 characters, equal to the folder name.

Skill descriptions are always in the agent’s discovery context. One folder per skill. Do not keep foo/ next to foo-v1/. Prefer fewer, focused skills.

Workflow migration

The local workflow package is workflow: .agents/skills/workflow/SKILL.md dispatches to 51 unprefixed children, including /build and /use-frontend. Shared authoring and completion references travel inside this tree. FIRST and technology skill names are unchanged.

The catalog changes are prepared in the local basilic-skills checkout and are not yet published. Until they reach the canonical source, preview from that checkout:

pnpm dlx skills@latest add /path/to/basilic-skills --skill workflow -a cursor --copy -y

After publication, substitute blockmatic/basilic-skills for the local path. Inspect the generated lockfile and installed files; do not assign an unpublished local preview a made-up GitHub hash.

After verifying the new install, remove any leftover b package with the skills CLI, preserving local edits first. This repository should have one workflow tree. Slash tags are /workflow and /plan-feature (not /b or /b-plan-feature). /workflow plan is a dispatcher shortcut to /plan-feature. Names from /b-* chats can be translated; they are not separate installed aliases.

Packaging validation runs in the catalog with pnpm validate. It checks metadata, counts, grouping, and workflow reference targets. These checks do not prove that an agent follows the workflow or that a particular desktop menu has refreshed.

Versioning

<topic>-v<major> is the library or SDK major, not a skill-file revision.

Library major change → new folder (next-v17). Drop the old folder when the repo no longer uses that major.
Upstream wording, references, or bugfixes → edit the catalog; re-run the skills CLI in this repo.
Design skills with no npm package keep -v1 until the skill format itself breaks (frontend-design-v1, emilkowal-animations-v1, vercel-react-v1). Library skills (including Motion) use the npm major (motion-v13 for motion ^13).
Workflows stay unversioned.

This repo’s Expo app is SDK 57; Expo skills are still *-v55 because that is what upstream publishes. Do not invent empty *-v57 folders. When Expo ships v57 skills, add those folders in the catalog and drop v55.

Update procedure

Until workflow with unprefixed playbooks is on GitHub main, refresh playbooks from the local catalog (do not add blockmatic/basilic-skills --skill b or --skill '*' from GitHub):

pnpm dlx skills@latest add /path/to/basilic-skills --skill workflow -a cursor --copy -y

Tech skills that already exist on GitHub may still refresh from blockmatic/basilic-skills by name. After publication, a GitHub --skill '*' (or --skill workflow) refresh is valid.

Review the diff; commit .agents/skills/ and skills-lock.json.

Do not git pull inside nested .git under skills. Do not store project skills only in ~/.cursor/skills/.

Repo-specific overlays stay in .cursor/rules/ (example: Playwright app E2E paths in e2e-playwright.mdc).

When grepping skill names, match the folder or name: exactly (motion-v1/, name: motion-v1). Do not use a substring (motion-v1 also hits motion-v13).

Upstream provenance

Catalog copies may differ from upstream. Original sources:

expo-cicd-workflows-v55 ← eas-workflows in expo/skills
expo-deployment-v55 ← eas-app-stores
expo-dev-client-v55 ← expo-dev-client
expo-tailwind-setup-v55 ← expo-tailwind-setup
expo-upgrading-v55 ← expo-upgrade
expo-use-dom-v55 ← expo-dom
vercel-react-v1 ← react-best-practices in vercel-labs/agent-skills
web-design-guidelines-v1 ← web-design-guidelines in vercel-labs/agent-skills (fetches a pinned web-interface-guidelines command.md revision)
composition-patterns-v1 ← composition-patterns in vercel-labs/agent-skills
next-v16 ← nextjs in pproenca/dot-skills
nuqs-v2 ← nuqs in pproenca/dot-skills
vitest-v4 ← vitest in pproenca/dot-skills
viem-v2 ← viem-integration in uniswap/uniswap-ai
nodejs-keccak256-v1 ← nodejs-keccak256 in affaan-m/ecc
frontend-design-v1 ← anthropics/skills frontend-design
emilkowal-animations-v1 ← pproenca/dot-skills emilkowal-animations

Basilic-maintained in the catalog: fastify-v5, file-organization-v1, wagmi-v3, solana-v1, ahooks-v3, ai-sdk-core-v7, ai-sdk-ui-v7, drizzle-orm-v0, motion-v13, openapi-ts-v0, playwright-v1, shadcn-v3, tailwind-design-system-v4, tanstack-query-v5, typescript-v6, and all workflow playbooks.

Intended unused stack (catalog skills for future work, not installed app deps yet): wagmi-v3, motion-v13, emilkowal-animations-v1.

Omitted from the catalog (and why): Vercel writing-guidelines (conflicts with docs sentence case); react-view-transitions (extra animation API); react-native-guidelines (Expo skills already cover native). Impeccable (Apache 2.0) is not a skill: competing PRODUCT/DESIGN generators, CLI, and detector hooks are out of scope. A few craft ideas (harden loading/empty/error/success; bounded screenshot critique) are adapted in original wording in /use-frontend and frontend-design-v1 references/product-ui.md.

New or reshaped UI: /use-frontend or /workflow ui. Visual direction only: @frontend-design-v1 (tokens win when present). Component APIs: @composition-patterns-v1. UI code audit: @web-design-guidelines-v1. Quality a11y report: /audit-accessibility. Runtime bugs: /debug-browser.