Cursor Skill Examples and SKILL.md Templates
These are seven complete Cursor skills you can copy. Save each one as .cursor/skills/<name>/SKILL.md, with the folder named the same as the skill's name field, and Cursor's Agent can use it in your project.
Last updated By Gizmolab
How to add an example to your project
- Create the folder, for example
mkdir -p .cursor/skills/debug-root-cause. - Copy the example into
SKILL.mdin that folder, and change commands such asnpm testor branch names to match your project. - Open Customize, then Skills, to confirm Cursor found it. Type
/and the skill's name to run it, or just describe the task.
Seven Cursor skill examples
Scoped repo edit
Best for: Small features and fixes that should touch as few files as possible.
- Reads the code before editing, so changes follow existing patterns.
- Lists planned files first, which keeps the diff small and reviewable.
---
name: scoped-repo-edit
description: Makes a small, scoped code change in an existing repository. Use when the user asks to add, change or fix one specific behavior and the change should touch as few files as possible.
---
# Scoped repo edit
## Steps
1. Restate the requested change in one sentence.
2. Find and read the files involved before editing. Note the patterns they already use.
3. List the files you plan to change and why. Keep the list as short as possible.
4. Make the change, reusing existing helpers, naming and structure.
5. Run the relevant tests or the type check if the project has them.
## Output
- What changed, file by file.
- Any assumption you made.
- Follow-up checks worth running.
## Limits
- Do not refactor or reformat code outside the change.
- Do not add a dependency or a new abstraction unless the task needs it.
- If the request is ambiguous, ask one specific question instead of guessing.Debug to the root cause
Best for: Bugs, regressions and errors where the first guess is often wrong.
- Separates diagnosis from the fix, so the Agent does not patch a symptom.
- Ranks causes with evidence, which makes the reasoning easy to check.
---
name: debug-root-cause
description: Investigates a bug and finds its root cause before changing code. Use when something is broken or behaves unexpectedly, or when the user shares an error, a stack trace or a failing behavior.
---
# Debug to the root cause
## Steps
1. Reproduce or locate the failure. Quote the exact error if there is one.
2. Trace the code path from the entry point to the failure. Read before editing.
3. List the likely causes, most likely first, with the evidence for each.
4. Confirm the top cause with a log line, a test, or a reading of the code that proves it.
5. Propose the smallest fix for that cause. Apply it only after stating it.
## Output
- Symptom, root cause and evidence.
- The fix and the files it touches.
- How to verify it, and what else might be affected.
## Limits
- Keep confirmed findings separate from guesses.
- No broad rewrites to fix a local bug.Safe refactor
Best for: Cleanup, splitting large files and removing duplication without changing behavior.
- Checks test coverage first, so behavior changes get caught.
- Works in small steps that can each be reviewed.
---
name: safe-refactor
description: Refactors code for readability or structure without changing behavior. Use when the user asks to clean up, simplify, split or deduplicate code.
---
# Safe refactor
## Steps
1. Describe what the code does today and find the tests that cover it.
2. If no test covers the behavior, say so and suggest one before refactoring.
3. Plan small steps (extract, rename, split, deduplicate), one concern per step.
4. Apply the steps, running the tests after each meaningful change.
## Output
- What became simpler, and why.
- Anything that still deserves a manual review.
## Limits
- Behavior must not change. Public functions and exports keep their signatures unless the user agrees.
- Do not mix formatting changes with logic changes.Map the codebase
Best for: Unfamiliar repositories, onboarding and tracing where a value comes from.
- Read only, so it is safe to run anywhere.
- Produces a file-by-file map that makes the next task faster.
---
name: map-codebase
description: Explains how a feature or flow works across the codebase before any change is made. Use when the user asks where something happens or how a flow works, or is new to the repository.
---
# Map the codebase
## Steps
1. Find the entry points for the flow: routes, handlers, components or jobs.
2. Follow the data from input to output, noting each file it passes through.
3. Mark which modules are central and which are incidental.
## Output
- A short map: the entry point, then each step with its file path.
- Where state is stored and where it changes.
- Open questions the code alone cannot answer.
## Limits
- Read only. Do not edit files.Review changes before a commit
Best for: A self-review of your diff before you commit or open a pull request.
- Runs only when you type /review-changes, thanks to disable-model-invocation.
- Sorts findings by severity, with a concrete fix for each.
---
name: review-changes
description: Reviews uncommitted changes or the current branch like a careful senior reviewer. Use when the user asks for a review before committing or opening a pull request.
disable-model-invocation: true
---
# Review changes
## Steps
1. Run `git diff` (or `git diff main...HEAD` for a branch) and read every changed file.
2. Check correctness first: edge cases, error handling, empty values, async mistakes.
3. Then maintainability: naming, duplication, dead code, missing tests.
4. Then risk: secrets, leftover debug logs, changed public APIs, migrations.
## Output
Group findings as Must fix, Should fix and Optional. For each one, give the file and line, the problem and a concrete fix. If nothing needs fixing, say so.
## Limits
- Review only. Do not edit files.
- Skip style comments a linter would catch.API route conventions
Best for: Projects where every route handler should follow the same pattern.
- Uses paths, so it only appears when the Agent works on files under app/api.
- Points the Agent at a real neighboring route instead of a generic pattern.
---
name: api-route-conventions
description: Adds or changes an API route handler the way this project does it. Use when creating, editing or debugging a route under app/api.
paths:
- "app/api/**/*.ts"
---
# API route conventions
## Steps
1. Read an existing route next to the one you are changing and follow its structure.
2. Validate the request body and query at the top of the handler before using them.
3. Return errors as JSON with a status code and a message. Never return a stack trace.
4. Add or update a test for the new behavior if the project has route tests.
## Limits
- Keep secrets in environment variables and never log them.
- Do not change the response shape of an existing route without saying so.Plan a feature
Best for: Changes that touch more than a few files, before any code is written.
- Surfaces risks and open decisions while they are still cheap to change.
- Ends with small steps you can hand to the scoped repo edit skill.
---
name: plan-feature
description: Plans how to build a new feature before any code is written. Use when the user asks how to implement something, asks for a plan, or the change will touch more than a few files.
---
# Plan a feature
## Steps
1. Restate the goal and list what is out of scope.
2. Read the parts of the codebase the feature touches.
3. List the files to add or change, with one line on each.
4. Call out risks, unknowns and decisions the user needs to make.
5. Break the work into small steps that can each be reviewed and tested.
## Output
A numbered plan, then the open questions. Wait for approval before writing code.Combine the examples by goal
Fix a bug
Run debug-root-cause to find and confirm the cause, then scoped-repo-edit for the patch, then /review-changes before you commit.
Start in an unfamiliar repo
Run map-codebase on the flow you need to change before asking for any edit. The map makes every later request more precise.
Build a larger feature
Run plan-feature, approve the plan, then use scoped-repo-edit for each step so every diff stays small enough to review.
Work on wallets, contracts or chains
Use the Web3-specific skills, which tell the Agent to check network, signer and RPC configuration before writing code.
Wallet, contract and Solana program skills are in Cursor skills for Web3 developers.
What good Cursor skills have in common
- One job per skill, with a description that says exactly when to use it.
- Read before editing, so the Agent works from the real code instead of guessing.
- A small-change bias, so diffs stay reviewable.
- An explicit output format, so every run is easy to compare.
- Limits that say what must not change and when to stop and ask.
Need a rule, not a skill?
If the instruction is one or two lines that should always hold, such as "use named exports in components", write a project rule in .cursor/rules/ instead. Rule templates are in Cursor AI rules.
To write your own skill from scratch, follow How to create a Cursor skill.
FAQ
Do I need to change these examples before using them?
Why does the review example use disable-model-invocation?
Should one skill cover debugging, editing and reviewing together?
Can a skill point the Agent at files in my repository?
Where can I find more Cursor skills?
Related guides
- Cursor skills
What a Cursor skill is, where Cursor looks for SKILL.md files, and how the Agent uses them.
- How to create a Cursor skill
Build a skill step by step, from the folder and frontmatter to testing it in Agent chat.
- Cursor AI rules
Project rules in .cursor/rules, the four rule types, .mdc templates and AGENTS.md.
- How to reload Cursor skills
What to check when a skill or rule does not load, and how to reload Cursor safely.
- Cursor skills for Web3 developers
SKILL.md examples for wallet flows, Solidity reviews, testnet deploys and Anchor programs.
Using a different tool? See Claude Code skills, OpenClaw skills or the AI skills hub.
Sources
This guide was checked against the official documentation on 5 November 2026. Cursor changes quickly, so when something here differs from the docs, the docs win.