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

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.

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.

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

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.

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.

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 ten skills from seven of them: the six named in the list above, plus teach, landing-page-design, better-ui and emil-design-eng. 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.

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.