Where should an Agent Skill live: project vs user scope?
Cursor loads skills from project folders and user-global folders differently. A 4 October 2026 guide to picking .cursor/skills vs ~/.cursor/skills — and what actually syncs to Cloud Agents.
People keep installing Agent Skills with npx skills add and then asking why a teammate cannot see them — or why a Cloud Agent ignores a personal skill. On 4 October 2026 the writable question is scope: project vs user, not another “install five skills” roundup.
Google Trends teammate was unavailable this run; the demand signal is the public Cursor Agent Skills docs (paths and sync rules), the Agent Skills open standard, and Skill Rank chatter around skill-creator packages.
The locations Cursor actually loads
From Cursor Docs — Agent Skills (checked today):
| Location | Scope |
|---|---|
.agents/skills/ | Project |
.cursor/skills/ | Project |
~/.agents/skills/ | User (this machine) |
~/.cursor/skills/ | User (this machine) |
Compatibility dirs (.claude/skills/, .codex/skills/, and their home equivalents) are also loaded. Each skill is a folder with a SKILL.md.
Pick project scope when…
- The workflow is repo- or team-specific (deploy this app, land PRs in this monorepo, house style for this codebase).
- You want the skill version-controlled with the project.
- Nested
.cursor/skills/under a package should only fire in that subtree — Cursor scopes nested project skills to their directory automatically.
Commit project skills so clones and CI agents see the same SKILL.md.
Pick user scope when…
- The habit is yours across many repos (personal review checklist, writing voice, machine-local ops).
- You are still experimenting and do not want to pollute a shared repository.
Caveat from the same docs: only `~/.cursor/skills/` syncs to Cloud Agents when Sync Skills is enabled. Cursor does not copy ~/.agents/skills/ or unsynced local skills to Cloud Agents, Agents Window remote SSH, or self-hosted workers. For remote workers, prefer project skills in the repo or bake skills into the worker image.
Description still decides discovery
Wherever the folder lives, the agent mainly sees name + description until the skill activates. A vague description (“helpful coding tips”) will not be selected; a concrete when-to-use line will. Skill Rank already lists several skill-creator helpers if you want a structured authoring pass — for example Anthropic’s and Vercel’s skill-creator entries — without adding new catalogue rows today.
A one-minute decision tree
- Teammates must get the same behaviour from a git clone → project (
.cursor/skills/or.agents/skills/). - Only you need it, on this laptop → user (
~/.cursor/skills/if you also want Cloud Agent sync). - Cloud / remote agent must see it → project skill in the repo, or user skill under
~/.cursor/skills/with Sync Skills on — not~/.agents/skills/alone. - Skill should stay slash-only → that is
disable-model-invocation, covered in the 2 October post; scope does not replace that flag.
Limits
- Catalogue unchanged today — matching skill-creator skills were already listed on Skill Rank.
- Open-standard packaging details live at agentskills.io; Cursor-specific sync rules come from Cursor’s own docs.
- Install counts and stars still do not prove a skill is safe.
Sources & checks
How we write and check articles: Editorial method