Cursor skill examples

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

  1. Create the folder, for example mkdir -p .cursor/skills/debug-root-cause.
  2. Copy the example into SKILL.md in that folder, and change commands such as npm test or branch names to match your project.
  3. 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.
.cursor/skills/scoped-repo-edit/SKILL.md
---
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.
.cursor/skills/debug-root-cause/SKILL.md
---
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.
.cursor/skills/safe-refactor/SKILL.md
---
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.
.cursor/skills/map-codebase/SKILL.md
---
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.
.cursor/skills/review-changes/SKILL.md
---
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.
.cursor/skills/api-route-conventions/SKILL.md
---
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.
.cursor/skills/plan-feature/SKILL.md
---
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?

Usually a little. Replace commands such as npm test, branch names such as main and folder paths such as app/api with the ones your project uses. The structure (when to use, steps, output and limits) can stay as it is.

Why does the review example use disable-model-invocation?

A review should run when you ask for it, not whenever the Agent decides it might help. With disable-model-invocation: true in its frontmatter, the review-changes skill only runs when you type /review-changes in Agent chat.

Should one skill cover debugging, editing and reviewing together?

No. Separate skills work better, because each description can say exactly when to use it and each one can have its own output format and limits. Chain them instead: debug-root-cause to find the cause, scoped-repo-edit to fix it and /review-changes before you commit.

Can a skill point the Agent at files in my repository?

Yes. Name the file or folder in the instructions, for example "read an existing route next to the one you are changing", and the Agent reads it with its tools. Templates that belong to the skill itself can go in its assets/ folder and be referenced by relative path.

Where can I find more Cursor skills?

Type / in Agent chat to see Cursor's built-in skills. Public registries such as ClawHub publish SKILL.md skills you can copy into .cursor/skills/, and agentskills.io documents the format. Read any third-party skill before adding it, because the Agent follows its instructions and may run its scripts.

Related guides

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.