Source: https://www.hype-stack.dev/stacks/cursor-skills

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

> 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 what** The 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 state** Numbered 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 references** The 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 wrong** It 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 parse** An unquoted colon in the description is the usual culprit, and it fails quietly. Wrap the description in quotes.
- **The description says what, not when** It 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 it** disable-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 up** Skills are discovered at startup, so a new one may need a window reload before it appears.
- **You are in the CLI, or using a symlink** Forum 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](https://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-design, web-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-docs, improve-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. (release, migration, pre-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 place** Each 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 the templates](https://www.hype-stack.dev/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](/stacks/cursor-best-practices), and the equivalent
files for Claude Code in [Claude Code Templates](/stacks/claude-code-templates).
