# Team collaboration in Cursor

URL: https://developertoolkit.ai/en/cursor-ide/team/team-collaboration/
Description: Commit Cursor rules, MCP config and skills to the repo, gate agent output in CI and Bugbot, and onboard a developer so their agent matches the team's.

Team collaboration in Cursor works when the agent's configuration lives in the repository instead of on each laptop: project rules in `.cursor/rules/`, MCP servers in `.cursor/mcp.json`, and repeatable workflows as skills. Every clone then runs the same agent, and CI plus Bugbot check the output before a human reviewer spends time on it.

This page is for the tech lead who owns a Cursor team of five to 20 engineers, and for the developer who sets up the shared files. Eight engineers use Cursor and the pull requests look like eight different codebases. One developer's generated routes validate input and log errors, another's swallow exceptions, and a third keeps getting default exports because a personal rule says so. Review slows down because every reviewer re-teaches the same conventions in comments.

## What a shared Cursor setup gives your team

- A layering plan that says which configuration is committed, which is team-level and which stays personal
- A starter set of `.cursor/rules/` files and a prompt that proves the agent actually loads them
- A committed `.cursor/mcp.json` in which the server list is shared and the tokens stay personal
- Team workflows packaged as skills that every developer calls by the same name
- A pre-review gate (CI, Bugbot and an agent self-check) so human review goes to intent and design
- A one-afternoon onboarding checklist and a failure-modes list with recovery steps

If your team runs more than one agent, read the cross-tool version first: [shared context and rules for Cursor, Claude Code and Codex](/en/teams/adopt/team-collaboration/). This page covers only the Cursor side.

## What belongs in the repository and what stays personal?

Decide the layer before you write a single rule. The most common source of "my agent behaves differently" is a convention that lives in one person's settings.

| Layer | Where it lives | Shared how | Owner | Put here |
| --- | --- | --- | --- | --- |
| Project rules | `.cursor/rules/*.mdc` | git, reviewed in pull requests | the team, via code review | stack, architecture boundaries, error handling, test conventions |
| MCP servers | `.cursor/mcp.json` | git; each developer supplies tokens | tech lead | the tools every task needs: GitHub, the dev database |
| Skills | `.cursor/skills/<name>/SKILL.md` | git | whoever owns the workflow | multi-step procedures: new endpoint, pre-PR check, release notes |
| Team-level rules | Cursor dashboard (business plans; confirm on Cursor's pricing page) | applied by Cursor to team members | admin | organisation-wide policy that must not vary by repo |
| Personal settings | each developer's Cursor settings and `~/.cursor/` | not shared | the developer | editor preferences, personal MCP servers, nothing that changes the code's shape |

The rule of thumb: if two developers would disagree in code review about it, it belongs in a committed file, where the disagreement is settled once in a pull request.

## Commit project rules the whole team loads

Project rules are `.mdc` files in `.cursor/rules`, and "A plain `.md` file in `.cursor/rules` is ignored by the rules system". Cursor also supports `AGENTS.md` in the project root and in subdirectories, reads `CLAUDE.md` files the same way, and applies rules only to Agent (Chat), not to Tab completion, Inline Edit or Bugbot PR reviews (Cursor docs and help, checked 2026-10-12). Each rule file starts with frontmatter that tells Cursor when to load it: `alwaysApply: true` for every request, `globs` for matching files, or a `description` the agent uses to decide. Keep always-applied rules short, because they cost context on every message. The rule-listing prompt below confirms what actually loads.

1. Create the directory in the repository root:

   ```bash
   mkdir -p .cursor/rules
   ```

2. Create `.cursor/rules/project-standards.mdc`, the one rule that always applies:

   ```markdown
   ---
   description: Core stack, boundaries and non-negotiables for this repository
   alwaysApply: true
   ---

   Stack: TypeScript (strict), Node 22, Fastify, PostgreSQL via Drizzle, Vitest.

   - No `any`. If a type is genuinely unknown, use `unknown` and narrow it.
   - Errors: throw `AppError` from src/lib/errors.ts; never return raw exceptions to clients.
   - Logging: use `logger` from src/lib/logger.ts; never `console.log`.
   - Named exports only.
   - Before creating a new file, find the closest existing example and follow it.
     API routes: src/routes/users.ts. Services: src/services/user.ts.
   - A task is done only when `pnpm typecheck`, `pnpm lint` and `pnpm test` pass.
   ```

3. Add scoped rules for the parts of the codebase with their own conventions. For example, `.cursor/rules/api-layer.mdc`:

   ```markdown
   ---
   description: HTTP layer conventions for route handlers
   globs: src/routes/**/*.ts
   alwaysApply: false
   ---

   - Route handlers parse, validate (zod) and format responses. No business logic.
   - Business logic lives in src/services/. Services never import from src/routes/.
   - Database access goes through src/repositories/. No raw SQL in services.
   - Every new route gets a test in the matching src/routes/__tests__/ file,
     covering one success case and at least one validation failure.
   ```

4. Commit the rules and review them like code:

   ```bash
   git add .cursor/rules/
   git commit -m "Add shared Cursor project rules"
   ```

Use the `.mdc` extension and the frontmatter shown above. A rule file with the wrong extension or malformed frontmatter still sits in the file tree looking correct, which is why the next check matters. For the full rule syntax and more templates, see [project rules in Cursor](/en/cursor-ide/quick-start/project-rules/) and [custom rules and templates](/en/cursor-ide/automate/custom-rules-templates/).

### Prove the rules load before you trust them

A rule the agent never sees still looks fine in the file tree. Run this check once after you add rules, and ask every new team member to run it on day one:

**Copy-paste prompt: prove which rules apply**

```text
Without changing any files: list every rule from .cursor/rules/ that is
active in this conversation, with its file name. Then tell me which rules
would apply if you edited src/routes/users.ts, and quote the one line from
each that most constrains that edit. If a rule file exists in
.cursor/rules/ but is not active, name it and say why you think it is not
loading.
```

The answer is checkable without reading any code: the file names either match the directory listing or they do not. A scoped rule missing from the answer usually means a wrong `globs` pattern or the wrong file extension.

## Add team-level rules from the Cursor dashboard

Cursor's business plans also let an admin define rules in the Cursor dashboard that apply to team members across every repository. `@cursor/sdk` 1.0.32 lists `team` as a settings source beside `project`, `user`, `mdm` and `plugins`, which is consistent with a team layer.

Use the team layer for the short list of policy that must not vary by repository: no production credentials in prompts, no generated code that disables authentication checks, the licence policy for new dependencies. Keep everything specific to one codebase in project rules, where it is versioned next to the code it describes.

**Team rules outrank project rules**

[Cursor's rules help page](https://cursor.com/help/customization/rules) says "When rules conflict, precedence is: Team Rules > Project Rules > User Rules". It also says that enforced team rules "are required for all members and can't be turned off in their settings", while optional team rules are enabled by default and members can disable them in **Customize** > **Rules** (read 2026-10-13). Dashboard rules are a feature of the business plans, Teams and Enterprise. Because a team rule outranks a project rule, keep team rules to policy and leave code conventions to project rules. The rule-listing prompt above shows you which rules actually reach the agent either way. One change is verified: Cursor 3.21 (2026-09-17) made team rules with file patterns apply only to matching files (Cursor release notes, checked 2026-10-12).

For security policy that belongs at this layer, see [privacy and security in Cursor](/en/cursor-ide/team/privacy-security/).

## Share MCP servers without sharing tokens

Commit `.cursor/mcp.json` so every developer's agent has the same tools, and keep each credential in the developer's own environment. The file below uses GitHub's hosted MCP server and Postgres MCP Pro in read-only mode against the development database:

```json
{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${env:GITHUB_PAT}" }
    },
    "postgres": {
      "command": "uvx",
      "args": ["postgres-mcp", "--access-mode=restricted"],
      "env": { "DATABASE_URI": "${env:DEV_DATABASE_URI}" }
    }
  }
}
```

- **GitHub** runs as a remote server at `https://api.githubcopilot.com/mcp/`, maintained in [github/github-mcp-server](https://github.com/github/github-mcp-server). For a read-only team default, use `https://api.githubcopilot.com/mcp/readonly` instead.
- **Postgres MCP Pro** is the PyPI package `postgres-mcp` (0.3.0, checked 2026-09-26), run with `uvx`. `--access-mode=restricted` means read-only transactions with time limits. Do not use `npx postgres-mcp`: the npm package of that name is unrelated.
- **Tokens** come from each developer's environment through `${env:NAME}` interpolation (taken from Cursor's MCP docs, which we could not re-fetch on 2026-09-26). List the required variables in `CONTRIBUTING.md` so onboarding knows what to set.

The older `@modelcontextprotocol/server-github` and `@modelcontextprotocol/server-postgres` packages are deprecated and archived; replace any entry that still uses them. For per-server detail, see [MCP setup in Cursor](/en/cursor-ide/quick-start/mcp-setup/), [the GitHub MCP server](/en/ecosystem/mcp/github-mcp/) and [database MCP servers](/en/ecosystem/mcp/database-mcp/).

## Package team workflows as skills

A prompt that three people paste from Slack drifts into three prompts. Save the workflows everyone runs as skills in `.cursor/skills/`, so the agent can pick them up and every developer runs the same procedure. Cursor loads project skills from `.cursor/skills/` and `.agents/skills/` and, "for compatibility", from `.claude/skills/` and `.codex/skills/` (Cursor docs, checked 2026-10-12). A skill is a folder with a `SKILL.md` file whose frontmatter names it and says when to use it.

Create `.cursor/skills/pre-pr-check/SKILL.md`:

```markdown
---
name: pre-pr-check
description: Run before opening a pull request. Runs the gates, fixes failures without weakening tests, and reports what changed.
---

1. Run `pnpm typecheck`, `pnpm lint` and `pnpm test`. Fix every failure.
   Never edit an existing test assertion to make it pass; if you believe a
   test is wrong, stop and say so.
2. Search the diff against main for `console.log`, `TODO`, hardcoded URLs,
   and anything that looks like a key or password. Remove or report each one.
3. Check every new import against package.json. Report any package that is
   not a declared dependency.
4. For each new function with branching logic, confirm a test covers at
   least one failure path. List the ones that do not.
5. Finish with a table: gate, result, what you changed.
```

Three more places a team workflow can live, and when to use each:

- **`.cursor/commands/`** still holds slash commands in many repositories; tools such as OpenSpec 1.13.2 write both `.cursor/commands/` and `.cursor/skills/`. Prefer skills for new workflows: the `SKILL.md` format is shared with Claude Code and Codex, and Cursor also loads `.claude/skills/` and `.codex/skills/` for compatibility (Cursor docs, checked 2026-10-12), so one copy can serve more than one agent. Teams running several agents keep one copy and link it; see [shared skills](/en/cto-scorecard-guide/shared-skills/).
- **Plugins** "package rules, skills, agents, commands, MCP servers, and hooks into distributable bundles" (Cursor docs, checked 2026-08-28). Reach for a plugin when the same setup must reach many repositories. See [running a team plugin marketplace](/en/ecosystem/plugins/team-marketplace/).
- **Hooks** run scripts before or after stages of the agent loop and can block an action. Use them for a check that must never depend on the agent remembering a rule.

For writing and testing skills, see [building custom skills](/en/ecosystem/skills/building-custom-skills/).

## Gate agent output before a human reviews it

Shared rules make agent output consistent. They do not make it correct. The team needs checks that prove each pull request is sound without a reviewer reading every line, and a clear split between what the machines check and what a person signs off.

1. **The developer runs the pre-PR skill** in Cursor. It runs the type, lint and test gates and reports its changes in a table.

2. **CI re-runs the same gates** on the pull request. The agent's own report is not the proof; the CI result is. Make `typecheck`, `lint` and `test` required status checks so a red run blocks the merge.

3. **Bugbot reviews the pull request.** Bugbot "reviews pull requests and identifies bugs, security issues, and code quality problems" (Cursor docs, checked 2026-08-28). It does not read `.cursor/rules/` (Cursor help, checked 2026-10-12); it takes project guidance from `.cursor/BUGBOT.md` (per Cursor's Bugbot help page, second-hand, not re-fetched on 2026-09-26). Copy the non-negotiables from your always-applied rule into that file. Setup and cost are on the [Bugbot page](/en/cursor-ide/ship/bugbot/).

4. **The developer asks the agent to review against the rules** with the prompt below, and fixes or answers each finding.

5. **A human reviewer checks intent**: does the change do what the ticket asked, is the design one the team wants to maintain, and do the tests exercise the behaviour that matters. The reviewer approves; the author owns the merge.

**Copy-paste prompt: review the branch against the team rules**

```text
Review the changes on this branch against main (run `git diff main...HEAD`).
Read every file in .cursor/rules/ first and use those rules as the standard.

Report, for each finding: file and line, the rule or risk it violates,
why it matters, and a concrete fix. Check specifically for:
1. Route handlers containing business logic or raw SQL
2. Async paths with no error handling, or errors not thrown as AppError
3. New behaviour with no test, or tests that only cover the success path
4. Imports of packages that are not in package.json
5. Unvalidated input reaching the database or a shell command
6. Anything that disables or bypasses an auth check

Do not edit files. If you find nothing in a category, say so explicitly.
```

"Say so explicitly" matters: an empty category in the answer tells you the agent checked it, while a missing category tells you it did not. The human reviewer can then read the finding list and the CI result instead of the whole diff. For the team-level version of this split, see [running the review queue when agents open the pull requests](/en/teams/review-queue/) and [helping the team stop reading every diff](/en/teams/trust-transfer/).

## Onboard a new developer in one afternoon

Cloning the repository delivers the rules, the MCP server list and the skills. What is left is the developer's machine and one guided task.

**Copy-paste checklist: Cursor onboarding**

```markdown
# Cursor onboarding

## Setup (about an hour)
- [ ] Install Cursor and sign in with the team account (not a personal one)
- [ ] Clone the repository and let indexing finish
- [ ] Set the MCP variables listed in CONTRIBUTING.md (GITHUB_PAT, DEV_DATABASE_URI)
- [ ] Open Cursor's MCP settings and confirm `github` and `postgres` are connected
- [ ] Run the "prove which rules apply" prompt; the rule list must match .cursor/rules/
- [ ] Confirm your run-mode setting matches the team policy in the security doc

## First task (about two hours, paired)
- [ ] Use Plan Mode to plan a small bug fix from the backlog; review the plan with your pair
- [ ] Let the agent implement it, then run the pre-pr-check skill
- [ ] Run the branch review prompt and resolve every finding
- [ ] Open the pull request; watch CI and Bugbot run

## First week
- [ ] Ship one feature end to end with the same gates
- [ ] Propose one change to a rule or skill, based on something the agent got wrong
```

Pair on the first task. Watching a colleague write a plan the agent cannot misread teaches more than the checklist does. For machine setup detail, see [installing Cursor](/en/cursor-ide/quick-start/installation-setup/).

## Keep the shared setup from going stale

Rules rot the same way code does: a rule that names a file that moved still loads, and now misleads. Three habits keep the setup current:

- **Fix the rule in the same pull request.** When a reviewer catches a pattern the agent got wrong, the fix includes a rule or skill change, so the mistake cannot recur on someone else's machine.
- **Refactor rules with the code.** A pull request that renames `src/lib/errors.ts` also updates every rule that references it.
- **Audit monthly.** Give one person the job and use the prompt below.

**Copy-paste prompt: audit the shared Cursor rules**

```text
Audit .cursor/rules/ and .cursor/skills/ against the current codebase.
Do not edit anything. Report:
1. Every file path, function or package a rule or skill mentions that no
   longer exists (search for each one and show the search you ran)
2. Pairs of rules that contradict each other, quoting both lines
3. Rules marked alwaysApply: true that only matter for one directory and
   should be scoped with globs instead
4. Conventions the last 30 commits follow consistently that no rule states
   (run git log -30 --stat to see them)
Finish with a proposed diff for each rule you would change.
```

The audit's output is checkable: each stale reference comes with the search that proved it stale.

## When a shared Cursor setup breaks down

**Two developers get different output from the same repository.** Run the rule-listing prompt on both machines and compare the lists. The usual causes are an uncommitted rule file on one machine, a personal rule that sets a conflicting convention, or a rule saved with the wrong extension. Move the convention into a committed rule and delete the personal one.

**A scoped rule never fires.** The `globs` pattern does not match the paths the agent edits. Ask the agent which rules would apply to one specific file, fix the pattern, and re-run the check.

**The always-applied rules crowd out the task.** Every always-applied line costs context on every message. Move directory-specific rules to `globs`, and move long procedures into skills that load only when used.

**Bugbot flags what your rules allow, or misses what they forbid.** Bugbot does not read `.cursor/rules/`. Put the conventions it must enforce, and the ones it must not flag, in `.cursor/BUGBOT.md`.

**The agent's review is too noisy to act on.** Add the exceptions to the prompt or the skill: "The GraphQL resolver layer uses `any` on purpose; do not flag it." A review that people stop reading is worse than none.

**An MCP server works for one developer and fails for the rest.** Someone hardcoded a token, or the variable name differs between machines. Keep only `${env:NAME}` references in the committed file and list each variable in `CONTRIBUTING.md`.

**A generated change passed every gate and was still wrong.** The tests did not cover the behaviour. Add the missing test first, then a rule or skill step that requires that kind of test, so the gate catches it next time.

## Where to go next with Cursor team setup

- [Cursor for teams and enterprise](/en/cursor-ide/team/) — the section overview
- [Privacy and security in Cursor](/en/cursor-ide/team/privacy-security/) — Privacy Mode, run-mode policy and security rules
- [Code review in Cursor](/en/cursor-ide/ship/code-review/) — the review surfaces this gate plugs into
- [Token management](/en/cursor-ide/operate/token-management/) — keeping a team's usage under control
- [Shared agent rules: one core, tested adapters](/en/cto-scorecard-guide/shared-agent-rules/) — for teams that run Cursor beside Claude Code or Codex