Hype StackHypeStack

Cursor Skills: What They Are, Skills vs Rules, Which to Install

GuideThe answer first, the product second.

All stacks

By Maciej Pyrc, who maintains Hype Stack.Updated .

A skill is a folder with a SKILL.md in it. The agent reads one line of it on every request and the rest only when the task calls for it. That loading model is the whole feature, and it decides what belongs in a skill and what does not.

Most of what is written about cursor skills is a directory of several hundred of them or a walkthrough of the file format. Both skip the first-day question: which of these would change what the agent does in my repository.

This page answers that for one job, building an application. If you use Cursor for scripts and one-off edits, you can stop here: a skill pays off on procedures you repeat, and a repo where nothing repeats does not need any.

What a skill is

Agent Skills is an open format that Cursor, Claude Code, Codex and others read, which is why the same folder works across them. A skill is a directory named after the skill, holding a SKILL.md with two required frontmatter fields: name and description. Next to it you can keep a scripts/ folder the agent may execute, references/ for longer documents it opens when needed, and assets/ for templates and data.

Cursor's documentation lists where it looks. In a project, .agents/skills/ and .cursor/skills/. For your user account, the same two folders under your home directory. It also reads .claude/skills/ and .codex/skills/ for compatibility, so a skill written for Claude Code usually loads in Cursor without being moved.

The agent sees every skill's description and decides from that whether to load the body. You can also call one yourself by typing / in the agent chat and picking it. A skill with disable-model-invocation: true in its frontmatter only runs that way, which is the right setting for anything with side effects, such as a release. A paths field limits a skill to matching files, so a migration skill surfaces only when the agent reads or edits your schema. The roots are walked recursively, and a nested project's own skills folder applies to that directory only, which helps in a monorepo.

Skills versus rules

The two get confused because both are markdown that steers the agent. They differ in when they load and what they are for.

Rules
Skills
What it holds
Conventions: how code in this repo is written
Procedures: how a task is carried out, step by step
When it loads
Every session, or whenever a file matching its globs is open
Only the description, until the task matches
Where it lives in Cursor
.cursor/rules as .mdc files, or an AGENTS.md
.agents/skills or .cursor/skills, one folder each
Can carry code
No, text only
Yes, a scripts folder the agent can run
Travels between repos
Poorly. It describes one codebase
Well, when the procedure is general

The test I use: if breaking it would show up in a diff, it is a rule. "Throw a typed error, do not catch it locally" is a rule, because the agent needs it on every backend edit and it costs three lines. "How to cut a release" is a skill, because it is forty lines the agent needs twice a month.

The boundary is not perfectly clean. Cursor rules have a mode where the agent picks a rule by its description, which is the same mechanism a skill uses, and Cursor ships a /migrate-to-skills command that converts those rules into skills. That tells you where the line is meant to sit: always-on and glob-scoped text stays a rule, and anything the agent chooses on demand is better as a skill.

What a good one contains

A skill is worth keeping when

  • The description says when, not whatThe description is the only part loaded on every request, so it is the trigger. 'Run before any push to main, or when asked if a change is safe to ship' fires. 'Helps with deployment' does not.
  • The body is a procedure with an end stateNumbered steps, the command for each, and what done looks like. A skill that is a list of principles is a rule in the wrong folder.
  • It names real commands and paths'Run the tests' leaves the agent to guess the runner. 'pnpm --filter backend test' does not. This is the line between a generic skill and one written against a codebase.
  • Long material is in referencesThe body loads whole once triggered. A style guide or an API reference belongs in a file the skill points to, so it is read only on the step that needs it.

Read a third-party skill before installing it, scripts folder included. It is instructions and code that an agent with access to your shell will follow.

The third item is why a skill from a directory often underdelivers. A general "write a database migration" skill has to hedge across every ORM and every folder layout, so it says things like "locate your schema file". The same skill written for one repository names the file, the command, and the check that has to pass afterwards.

When a Cursor skill will not load

Most reports on Cursor's forum come down to a few causes. Work down this list before you rewrite anything.

Skill not showing or not firing

  • The folder shape is wrongIt has to be .agents/skills/<name>/SKILL.md, one folder per skill, with the frontmatter name matching the folder. Lowercase letters, numbers and hyphens only. A loose SKILL.md directly under skills is not a skill.
  • The frontmatter does not parseAn unquoted colon in the description is the usual culprit, and it fails quietly. Wrap the description in quotes.
  • The description says what, not whenIt appears in the slash menu and never fires by itself. Rewrite the description around the words you actually type when you want it, then try again in a new chat.
  • A setting is hiding itdisable-model-invocation: true means it only runs from the / menu. A paths field means it only surfaces once the agent touches a matching file.
  • The window has not picked it upSkills are discovered at startup, so a new one may need a window reload before it appears.
  • You are in the CLI, or using a symlinkForum reports say the Cursor CLI has been less reliable than the editor at auto-triggering, and at reading .claude/skills, and that symlinked folders may not be followed. If it works in the editor and not there, copy the folder into .cursor/skills or call it with /.

The last item comes from user reports, not the docs, so test it on your version.

Which to install for building an app

Directories such as skills.sh list skills by install count. For app work, sort the examples by the mistake they prevent instead.

Skill types that earn their place on an app

A skill finder

find-skills, from the vercel-labs/skills repository, tells the agent to search the directory before improvising a workflow. Small, and it makes every other skill discoverable from inside a session.

find-skills
Design and UI

Agents produce recognisably generic interfaces by default. frontend-design from Anthropic's skills repository and web-design-guidelines from Vercel's push against that with concrete rules on spacing, focus states and accessibility.

frontend-designweb-design-guidelines
Framework performance

vercel-react-best-practices covers rendering and data-loading patterns in React. Useful when the agent writes components, and a candidate to remove if your stack is not React.

vercel-react-best-practices
Planning and review

Matt Pocock's grill-with-docs makes the agent question a plan against the documentation before writing code, and improve-codebase-architecture looks for seams to refactor toward.

grill-with-docsimprove-codebase-architecture
Your own procedures

Release, migration, adding a feature in your folder structure, the pre-push check. Nobody publishes these because they only work in your repository, and they are the ones that change the most.

releasemigrationpre-push

The first four you install. The fifth you write, and it needs a codebase with settled conventions to be written against.

How we wire this in Hype Stack

Hype Stack is a full-stack TypeScript template with a CLI that scaffolds it. The create command does two separate things for the agent, and they map onto the split above.

Rules, written for the template's own code. They are authored as Cursor .mdc files and stay in .cursor/rules when Cursor is one of the editors you pick. Scoping is kept, so a rule on apps/backend/** only loads when the agent opens a backend file. That is where the conventions live: route validation, central error handling, the feature folder layout.

Skills, fetched from skills.sh at scaffold time. create runs npx skills@latest add once per source repository and installs eleven skills from eight of them: the six named in the list above, plus teach, landing-page-design, better-ui, emil-design-eng and no-ai-slop. They land in .agents/skills, which Cursor reads directly, and Claude Code gets a .claude/skills link to the same folder so there is one copy. They are fetched fresh instead of being copied from the template, because a skill is prose its authors keep editing. The installer records each one by content hash in skills-lock.json, and npx skills update moves them forward.

The install names the target agents explicitly, so the skills CLI does not guess from whichever editors happen to be on the machine running it. And a source repository that cannot be reached does not fail the scaffold: create prints the installer's output and the exact command to retry, and --no-skills skips the step for CI.

Templates with the rules and starter skills in placeEach one scaffolds a working app with Cursor rules scoped to its own folders and a shared .agents/skills directory, so the agent starts with conventions instead of a blank repo.Browse templates

What is not in it

The skills create installs are other people's general-purpose skills. None of them is written against the template's code. The template-specific knowledge sits in the rules and in the MCP server, which has a pack_authoring_guide tool for the one long procedure we do document, writing your own pack. There is no shipped skill for your release process, your migrations or your domain, and there cannot be.

So the fifth layer is still yours. What the template changes is how hard it is to write: the routes, the error handling and the folder structure are already fixed and already described in rules, which means a skill for "add a feature" can name real paths on the first draft. Put it in .agents/skills/<name>/SKILL.md, give it a description that says when to fire, and commit it with the code it describes.

Skills are half of a Cursor setup; the working habits are in Cursor Best Practices From Running an Agent on a Large Codebase, and the equivalent files for Claude Code in Claude Code Templates.

What is Hype Stack?

Every product starts with the same month of work nobody pays you for: sign-up and login, teams and permissions, taking payments, notifications, an admin panel to run the business. Hype Stack is that month, already built and tested. Start from the free open-source app, add the pieces you need with one command, and keep going on the part that is actually your idea.

Everything lands as real code in your own repository, so there is nothing to rent and nothing anyone can switch off. For the engineers: React 19, Hono, Postgres, and a desktop build, typed end to end.

See it running.

Curated starters built on this stack: a layout, feature packs, a theme, and bonus pages. The previews are recordings of the real apps.
See all 8 templates

Two ways to install.

Same features underneath. Either command resolves what the packs need, copies the source into your repo, and merges the Prisma schema.

Take a template

A landing page, a design system, a themed layout, and the features already wired in. Rebrand it, put your product in the middle, ship.

$npx @hype-stack/cli template
Browse templates

Compose your own design

Your design and your choices, without rebuilding auth, billing, or notifications. Tick the packs you want and the CLI wires them into the open-source starter.

$npx @hype-stack/cli compose
Browse packs

Questions, answered.

In a project, Cursor loads skills from .agents/skills and .cursor/skills. The same two folders under your home directory hold skills for every project. It also reads .claude/skills and .codex/skills for compatibility, so a skill written for Claude Code usually loads without being moved.

More stacks.

Your SaaS is one sentence away.

Add a Pro plan at $19 a month with a 14-day free trial.. Let customers invite their team and choose who can do what.. Send a welcome email the moment someone signs up.. Show me which customers are close to their limit this month.. Let people sign in with Google.

Free to start. Works in the AI tool you already use.