AI Agent Skills:What They Are and How to Use Them

You keep telling the agent the same things: commit message style, how tests are named, which folder owns deploy scripts. Rules help when the guidance should always be present. Skills help when the guidance should show up only when the task matches — a small package the agent can load on demand.

This page stays on day-one skills: what they are, where to put them, how to write a minimal SKILL.md, and how to trigger one. You do not need scripts folders, path scoping, or migration tools on day one. Those get a short heads-up at the end.

Warm-up: mental model

Think of a skill as a short playbook for one job. The agent sees a short description for every skill at the start of a session. When your request matches that description, it loads the full instructions. When it does not match, the playbook stays out of the way.

That progressive load is the main idea:

1. Discover — Cursor finds skill folders and reads each description.
2. Match — your prompt (or a /skill-name slash) decides relevance.
3. Load — only then does the full SKILL.md body enter context.

Note: Agent Skills is an open standard. Cursor is one place that implements it. The file shape below works in Cursor; other agents that support the same standard use the same idea.

Where skills live

Put each skill in its own folder with a file named exactly SKILL.md (uppercase). Cursor loads skills from these locations:

Location	Scope
.cursor/skills/	This project only (good for team conventions)
~/.cursor/skills/	Your user account, every project
.agents/skills/	Project-level (also supported)
~/.agents/skills/	User-level (also supported)

For this lab, use a project skill so everything stays inside a throwaway folder.

Note: Do not put custom skills under ~/.cursor/skills-cursor/. That directory is reserved for Cursor’s built-in skills.

Hero use case: a tiny commit helper

You want the agent to write commit messages in a fixed style whenever you ask it to commit. You will create one skill, then call it two ways: automatically from a natural request, and explicitly with /.

Create the folder

From a scratch project (or any repo you are fine experimenting in):

mkdir -p .cursor/skills/commit-helper

Write SKILL.md

Create .cursor/skills/commit-helper/SKILL.md:

---
name: commit-helper
description: >-
  Draft git commit messages in this repo’s style. Use when the user asks
  to commit, write a commit message, or stage and commit changes.
---

# Commit helper

## Instructions

1. Run `git status` and `git diff` (and `git diff --staged` if anything is staged).
2. Stage only the files that belong in this commit — ask if the set is unclear.
3. Write a short subject line in imperative mood (for example, "Add commit-helper skill").
4. Keep the subject under ~72 characters. Add a body only when the why is not obvious from the subject.
5. Show the proposed message and wait for approval before running `git commit`.

Two frontmatter fields are required on day one:

• name — lowercase letters, numbers, and hyphens. Must match the folder name (commit-helper).
• description — what the skill does and when to use it. This line is how the agent decides relevance, so be specific.

The markdown body is plain instructions for the agent: steps, conventions, and what not to do.

Use it automatically

Open a new Agent chat (skills are discovered when the session starts). Make a small change in the project, then ask something that matches the description:

Stage my changes and draft a commit message.

If the skill is discovered and the description fits, the agent should follow your playbook — status/diff first, then a proposed message — instead of inventing a random style.

Use it on purpose with /

In Agent chat, type / and search for commit-helper, or type:

/commit-helper

Manual invocation is useful when you want that playbook now, even if your wording is vague. It is also how you run skills that are set to slash-only (see the heads-up below).

Check that Cursor sees it

Open Customize in the sidebar and go to Skills. Your project skill should appear alongside other agent skills. If it is missing, confirm the path is .cursor/skills/commit-helper/SKILL.md (folder + that exact filename) and start a new agent session.

Skills vs rules (just enough)

	Rules	Skills
When they apply	Often always-on, or tied to file globs	When the task matches the description (or you type /)
Best for	Standing house rules (“never commit secrets”)	Repeatable jobs (“how we commit”, “how we review”)
Context cost	Easy to bloat every chat	Loads the full body only when needed

If you already pasted the same workflow into chat three times this week, that workflow wants a skill. If the guidance must be true on every turn, prefer a rule.

Cursor also ships built-in skills (/create-skill, /create-rule, and others). Type / in Agent chat to browse them. You can ask /create-skill to scaffold a new skill when you would rather describe the workflow in English first.

Common beginner mistakes

• Wrong filename or path — .cursor/skills/commit-helper.md will not load. It must be .../commit-helper/SKILL.md.
• Vague description — “Helps with git” is too soft. Say what and when: “Draft commit messages… Use when the user asks to commit…”
• Name ≠ folder — name: commit-helper must match the parent folder commit-helper.
• Old session — create the skill, then open a fresh Agent chat so discovery runs again.
• One skill that does everything — keep each skill focused on one job. Split “commit” and “PR review” into two skills.

Heads-up: what comes next (advanced, skip for now)

You do not need these on day one. Know they exist so you are not surprised later:

• paths — limit a skill to certain files (for example only **/*.tsx).
• disable-model-invocation: true — skill loads only when you type /skill-name (slash-command style).
• scripts/, references/, assets/ — optional folders for helper scripts, long docs, and templates; the agent can load them when needed.
• Nested category folders — you can group skills under .cursor/skills/shipping/...; the skill identity is still the folder that contains SKILL.md.
• Install from GitHub / migrate rules — Cursor can import remote skills and includes /migrate-to-skills for eligible rules and slash commands. Use those after the basic loop feels natural.

Official reference: Cursor Agent Skills docs.

Quick checklist

1. Create .cursor/skills/<name>/SKILL.md (or the user-level twin under ~/.cursor/skills/).
2. Set matching name and a description that includes when to use it.
3. Write short, step-by-step instructions in the body.
4. Start a new Agent chat; try a natural request and a /skill-name invoke.
5. Confirm the skill appears under Customize → Skills.

That is the whole beginner loop: one folder, one file, a clear description, and a way to call it. Everything else is optional power once this feels boring — which is when it is working.