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.
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
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.
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.
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.
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.
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.
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.
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.