Cursor Skills in Monorepos: Local, Global, and Cloud Agent Scope

A Skill can work perfectly in one Cursor window and seem to disappear when you open another part of the same repository—or move the task to a Cloud Agent. In a monorepo, the reason may be its location and execution environment, not the instructions inside SKILL.md.

Cursor discovers Skills from documented project and user-level locations. Nested project Skills can be scoped to a subproject, while personal Skills live on your machine unless you configure supported syncing. This guide explains how to organize those locations, diagnose missing Skills, and choose a setup that teammates and remote agents can reproduce.

What is a Cursor Skill?

A Cursor Skill is a reusable set of instructions for a task or workflow. It is a good fit for a repeatable procedure such as preparing a release, reviewing an API contract, generating a migration, or checking a deployment. A Skill typically has a SKILL.md file and may be organized with additional supporting material when the workflow needs it.

Skills are different from persistent rules. A rule is best for a short convention that should apply broadly or to matching files—for example, using named exports in React components. A Skill is better for a longer sequence of steps that the agent can invoke when needed. Keeping those responsibilities separate helps avoid loading a large playbook into every routine coding task.

Cursor documents the Skill format and supported discovery locations in its official Skills guide. The details below follow that documented behavior; if your team uses a particular Cursor release or managed environment, test the setup in that environment too.

Where Cursor discovers Skills

1. Project-level Skills

For a repository-wide Skill, the documented project locations include .cursor/skills/ and .agents/skills/. A Skill is placed in a directory containing its SKILL.md file. For example:

repo/
  .cursor/
    skills/
      api-review/
        SKILL.md
  .agents/
    skills/
      release-check/
        SKILL.md

A project-level Skill is useful when the workflow belongs with the codebase and should be available to teammates who clone the repository. Commit the Skill files to version control, review changes like other developer documentation, and avoid placing secrets or private credentials in the instructions.

2. Nested Skills for a monorepo

Cursor also documents Skills inside nested project directories. Suppose your repository contains a web app, a mobile app, and shared services:

repo/
  apps/
    web/
      .cursor/skills/
        component-audit/SKILL.md
    mobile/
      .cursor/skills/
        release-check/SKILL.md
  services/
    api/
      .agents/skills/
        endpoint-review/SKILL.md

This lets a Skill live close to the subproject it describes. According to Cursor's documentation, nested project Skills are automatically scoped to files inside that nested project. A web-component workflow therefore belongs naturally under apps/web rather than in a global folder that every subproject has to interpret.

Use nesting to express ownership, not to duplicate the same Skill in several directories. If a procedure is truly shared across all packages, place it at the repository-level Skills location. If it depends on the web app's component library or the API service's test commands, keep it close to that package and document the boundary.

3. Personal Skills on your machine

Cursor supports user-level Skill directories such as ~/.cursor/skills/ and ~/.agents/skills/. These are useful for personal workflows that should not be committed to a repository—for example, your own code-review checklist or a preferred way to summarize changes.

The trade-off is portability. A teammate cloning the repo does not automatically receive the private Skill files in your home directory. If a workflow is important to the team, move it into a project location or publish it through the supported team marketplace instead of relying on one developer's local setup.

Why a Skill works locally but not in a Cloud Agent

Local and remote execution environments do not necessarily have the same files. Cursor states that personal Skills under ~/.cursor/skills/ can be synced for Cloud Agents by enabling Sync Skills under Settings → Agents → Context and Tools. The documentation also distinguishes those Skills from other personal locations: unsynced local Skills and Skills in ~/.agents/skills/ are not simply copied into Cloud Agents, Agents Window remote SSH, or self-hosted workers.

That difference is easy to miss because the Skill is visible in your local editor. Visibility on your laptop is not proof that a remote environment has the same directory tree. If a remote agent cannot use a Skill, inspect the remote environment and the documented sync path before rewriting the Skill's instructions.

For self-hosted workers, Cursor's guidance is to use project Skills in the repository or bake the required Skills into the worker image. That makes the dependency explicit and reproducible. For Cloud Agents, check the current sync settings and confirm the relevant Skill is available to the account and environment running the task.

A reliable setup for teams

Choose a source of truth

Decide whether each Skill is personal, project-wide, or specific to a subproject. Write that decision down in your contributor documentation. Do not make a team-critical workflow depend only on one developer's home directory.

• Personal workflow: keep it in a user-level location when only you need it.
• Shared repository workflow: commit it under the project's supported Skills directory.
• Monorepo package workflow: place it near the package it describes and test the scope from that package.
• Remote or self-hosted workflow: verify that the remote environment has the Skill files; use documented sync or package the project-level files with the worker.

Keep the Skill discoverable and specific

A Skill's folder and SKILL.md should make its purpose easy to identify. Prefer a focused name such as api-contract-review or release-readiness-check over a vague name like helper. Give the instructions a clear goal, the inputs they need, the sequence to follow, and how to verify the result.

Avoid turning one Skill into a large manual for unrelated tasks. Split it when the procedures have different triggers, inputs, or verification steps. A smaller Skill is easier to maintain and test, and its instructions are less likely to conflict with other workflows.

Treat paths and prerequisites as real dependencies

If a Skill assumes a package manager, test command, file path, environment variable, or generated artifact, name that dependency explicitly. For a monorepo, specify whether commands run from the repository root or a package directory. Do not assume that the remote agent has the same working directory or local tools as your laptop.

Do not include API keys, passwords, access tokens, or private customer data in SKILL.md. Use the environment's supported secret-management mechanism. A Skill tells an agent how to perform a task; it should not be the place where credentials are stored.

Troubleshooting: a practical checklist

• Confirm the Skill contains a file named exactly SKILL.md in a supported Skills directory.
• Check the folder path: project-wide, nested project, or user-level. Confirm that it matches the environment where the agent is running.
• If the Skill is nested in a monorepo, test it while working with files inside that subproject.
• If it is personal and the task runs in a Cloud Agent, check the documented Sync Skills setting and the source directory.
• For remote SSH or self-hosted workers, verify the files exist in the remote environment; do not assume local home-directory content was transferred.
• Invoke the Skill explicitly using the documented slash-command or @-selection flow to distinguish discovery issues from automatic selection issues.
• Check that the Skill's instructions name valid paths and commands for the current package, and run its verification steps manually.
• After changing a Skill, retest from a fresh task and record the environment and path that worked.

These checks isolate the main variables: discovery location, project scope, remote file availability, and the instructions themselves. Changing all of them at once makes it harder to learn what actually fixed the problem.

Example: a shared release Skill in a monorepo

Imagine a repository with apps/web and services/api. The team wants both packages to have a release-readiness workflow, but each has different checks. A useful design is a repository-level release guide for shared requirements plus a package-specific Skill in each project for its commands and tests.

The shared guide might describe versioning, changelog review, and approval requirements. The web Skill could run the frontend test and build commands; the API Skill could run unit tests, schema checks, and migration validation. Each package-specific Skill should say where commands run and what success looks like. The team can then test each workflow locally and in its actual remote execution environment.

This is more maintainable than one enormous Skill with many conditional branches, or a personal Skill that only one developer can access. It also makes failures easier to diagnose: the team can tell whether a missing Skill is a location problem, a remote packaging problem, or a failed prerequisite.

Skills versus rules: a quick decision

Use a rule when a short instruction should apply broadly or to matching files. Use a Skill when an agent needs a repeatable, multi-step procedure that can be invoked when relevant. For example, “Use the existing API response wrapper” is a rule; “review an endpoint, check authentication and validation, run contract tests, and summarize the findings” is a Skill.

Cursor's official Rules documentation describes project rules in .cursor/rules/ and the conditions that determine when they apply. If you're migrating older project guidance, see our related guide, Migrating from .cursorrules to Cursor's .mdc Rules. For a broader comparison of persistent instructions and task workflows, see Claude Code: CLAUDE.md vs Rules vs Skills.

Frequently asked questions

Does Cursor automatically discover Skills in nested monorepo folders?

Cursor documents recursive discovery and support for nested project Skills. Those nested Skills are scoped to files inside the corresponding project directory, so verify the folder placement against the subproject where you expect to use them.

Why does my personal Skill work locally but not in Cloud Agents?

Personal files may remain on your machine. Cursor documents syncing Skills from ~/.cursor/skills/ for Cloud Agents through Settings → Agents → Context and Tools. Other local Skill locations are not automatically copied to every remote worker.

Should I put every Skill in the repository root?

No. Put genuinely shared workflows in a project-level location and package-specific workflows near the code they describe. Use personal locations only for workflows that do not need to travel with the repository or team.

Can a Skill replace a Cursor rule?

Not always. Rules are suited to short guidance that applies across conversations or matching files; Skills are suited to more detailed procedures. Choose based on when the instruction should be applied and how much workflow it describes.

How can I share a personal Skill with teammates?

Cursor documents publishing personal Skills to the team's Default marketplace. Alternatively, place a team-owned Skill in a supported project directory and commit it to version control. Follow your team's current access and review process.

Official references

Cursor Docs: Skills — discovery paths, nested Skills, Cloud Agent sync, and rule-versus-Skill guidance.

Cursor Docs: Rules — project rule files, frontmatter, and rule activation behavior.