The short answer

Create .agents/skills/<name>/SKILL.md in your project or use a supported personal skill directory. Add valid name and description frontmatter, reopen the project if needed, and invoke the skill from the slash menu in Agent chat. Test a small task before relying on automatic selection.

Inspect your Cursor skills in Skiller

If you already use several coding agents, start by looking at your installed library in Skiller. Open Skills Manager, find the skill you want to use and inspect its SKILL.md content and associated agents. This lets you compare an existing copy before adding another directory with the same name.

For a community skill, open Marketplace, search for the workflow and preview its source repository and target agents before installation. Review the package first, then choose the intended target. For a skill you wrote yourself, the manual project layout below gives you a small reproducible starting point. After either route, verify selection and execution in Cursor.

Keep project scope deliberate. A procedure for one repository should not become a personal skill applied across all your projects. Skiller provides project-scoped management; Cursor's documentation determines which directory the running client actually reads.

Choose project or personal scope

Cursor supports skills as directories containing a SKILL.md file. The first decision is where that directory belongs. A project skill travels with the repository and can describe a workflow shared by contributors. A personal skill belongs to your local environment and is useful across projects. Avoid putting private preferences or machine-specific paths into a shared repository.

The current Cursor documentation lists .agents/skills/ and .cursor/skills/ for project skills, and ~/.agents/skills/ and ~/.cursor/skills/ for personal skills on the local machine. It also documents compatibility with Claude and Codex skill directories. Choose one source for your example instead of installing duplicate copies into every supported location.

Create a complete skill directory

For a portable project example, create this structure at the repository root. The directory name and frontmatter name should match. Keep the exact capitalization of SKILL.md; a file called skill.md is a different filename on a case-sensitive filesystem.

.agents/
└── skills/
    └── review-release-notes/
        └── SKILL.md

Use an editor to create the file with the following content. This example is intentionally limited to a review: installing it does not authorize publishing a release.

---
name: review-release-notes
description: Review release notes against a supplied Git diff. Use when checking a release announcement for missing or unsupported claims.
---

# Review release notes

1. Read the repository instructions.
2. Ask for the release notes and Git range if missing.
3. Compare each user-visible claim with the diff.
4. Flag missing changes and unsupported statements.
5. Report findings with file locations and suggested wording.

Do not publish, tag, push, or edit unrelated files.

If your skill references a template or script, copy those files into the same skill directory too. A discovered instruction that points to a missing resource is still an incomplete installation. See the SKILL.md authoring guide for the shared format.

Invoke it in Agent chat

Open the project in Cursor. Type / in Agent chat and search for the skill name. Cursor documents manual invocation as attaching the skill to a message. Select it and ask for a small review using a known diff and a short release note. Confirm that the response addresses the supplied material rather than merely describing the skill.

Automatic discovery and successful execution are separate checks. Once explicit invocation works, start a fresh chat and ask naturally for the workflow. If the agent does not select it, improve the description so it names the real task and trigger. Adding broad keywords can make a skill fire on unrelated requests.

Check remote environments separately

A personal skill on your laptop is not automatically available wherever Cursor runs an agent. The documentation distinguishes local personal skills from Cloud Agents, remote SSH sessions and self-hosted workers. For team workflows, repository skills are easier to make available with the project. Use the documented synchronization or team publication path when you need personal skills in a supported remote environment.

Check resources as well as instructions: a local absolute path, installed CLI or credential may be absent remotely. Document dependencies, then run the same bounded task in the actual target environment. A successful local invocation proves local behavior only.

Verify before adding more skills

  • Confirm the intended project and discovery directory.
  • Check frontmatter, filename and supporting files.
  • Run an explicit invocation with recognizable inputs.
  • Test automatic selection in a fresh chat.
  • Check permissions and dependencies where the agent runs.

If the skill remains missing, follow the troubleshooting checklist before reinstalling. Skiller can help inspect your library and copies, but the final check belongs in Cursor itself.

FAQ

Can Cursor use the shared SKILL.md format?

Yes. Cursor supports agent skills, with shared and client-specific discovery conventions. Check the official documentation for your installed version before choosing a directory.

Are Cursor rules the same as skills?

No. Rules preserve project guidance; skills preserve reusable procedures that are selected for a task. Avoid maintaining duplicate instructions in both places.

How do I verify a Cursor skill after syncing from Skiller?

Inspect the content and target in Skills Manager, open Cursor in the intended project and test the skill on a small task. Confirm which discovery path the client uses.

Your skills. One place.

Inspect, edit and sync your skill library across coding agents.

Download Skiller

Sources