2026 Cursor Agent Skills Installation: Plugin Version or File Version?

A skill appears twice, or the same setup works in Claude Code but not in Cursor.

Fastest fix: choose the plugin version for Claude Code only with managed updates; choose the file version for Cursor and Claude Code sharing, selective installation, or editable skills. Do not run both installation paths in the same Claude Code environment.

Who this decision is for

This guide is for developers using Cursor and Claude Code together, especially when both tools should share one skill set.

It also helps technical leads deciding whether skills belong to a platform-managed installation or to a version-controlled development repository. Teams standardizing remote Macs should treat this as an environment ownership decision, not just an installation command.

Winner by condition: the Claude Code plugin wins for a single-tool, low-maintenance setup. The file version wins for cross-tool reuse and repository-level control.

Important: “Plugin versus file” is not a compatibility upgrade path. The current mattpocock/skills README treats them as separate installation approaches and warns against installing both together. Verify the README and Claude Code documentation again whenever the plugin name, path, or CLI syntax changes.

Last updated August 24, 2026. Installation behavior was checked against the mattpocock/skills README, the current skills CLI documentation, and Claude Code’s official plugin documentation.

2026 Cursor Agent Skills installation by decision metric

The first decision should be made before any command is copied. The installation target determines who owns the files, where the skills are visible, and how updates enter the environment.

Choose the plugin version when all three conditions are true:

• Claude Code is the only agent that needs the skills.
• Automatic or platform-managed updates are more valuable than fixed repository versions.
• The team does not need to rewrite SKILL.md or maintain internal variants.

Choose the file version when any of these conditions is true:

• Cursor and Claude Code must use the same source.
• A project needs only a subset of the available skills.
• The team needs to add internal rules, examples, or approval notes.
• Skills must be reviewed alongside application code.
• A clean checkout must recreate the same agent behavior on another Mac.

This is the key distinction behind 2026 Cursor Agent Skills installation. The plugin is a Claude Code delivery mechanism. The file approach is a source-controlled asset that can be placed into an agent’s expected skill location.

Compatibility and skill coverage

Plugin scope

The plugin path is designed around Claude Code’s plugin system. Claude Code exposes plugin components through its own management model, including plugin namespaces and scopes. The official documentation distinguishes plugin-installed components from standalone skill files, so a plugin should not be treated as an ordinary folder copied into every agent.

The practical benefit is lower maintenance for a developer who has already standardized on Claude Code. The plugin can remain managed by the Claude Code workflow instead of becoming another directory inside every project.

The limitation is equally important: Cursor does not automatically become a consumer of a Claude Code plugin. If Cursor also needs the skills, the file workflow is generally the more direct model because the skill files can be placed where the supported agent expects them.

File scope

The CLI workflow is intended to add skills from a repository. The current command format is documented as:

npx skills add mattpocock/skills

The skills CLI reference documents options for selecting agents, choosing a global scope, and selecting individual skills. The Vercel Labs skills README also shows the CLI installation parameters and examples.

A broad installation is not always the right one. A team can use the file model in three ways:

1. Add the full collection when every project follows the same agent workflow.
2. Select only approved skills when a repository needs a controlled subset.
3. Install or configure skills at repository scope when different projects require different rules.

The exact visibility depends on the selected agent and scope. A global installation can serve a user across projects, while a repository-level installation keeps the behavior closer to the codebase. The command alone does not prove that Cursor and Claude Code are aligned. The acceptance test must inspect the resulting files and agent visibility.

Editing rights and ownership

The plugin and file approaches differ most sharply in ownership.

With a plugin, the platform manages the delivery object. A developer consumes the skill through Claude Code’s plugin system. Treating the installed plugin content as a project-owned file and editing it directly creates a fragile boundary: a later plugin update may replace, bypass, or conflict with the local change. The safe assumption is that plugin content is managed content unless the current Claude Code documentation explicitly provides a supported override.

With the file version, the repository or selected local scope can own the skill. A maintainer can review a SKILL.md, add an internal coding standard, or remove instructions that do not fit a regulated project. This is useful when the skill must reference private tooling, internal test commands, or organization-specific review rules.

Editable does not mean automatically better. Every local modification creates a comparison problem:

• Which lines came from upstream?
• Who approves changes to the skill?
• How does the team detect a security-sensitive instruction change?
• When should the local version be rebased or replaced?
• Can a new developer reproduce the same content from a clean checkout?

For a personal developer, this cost may be small. For a team, the skill should be reviewed like executable development configuration. It influences agent behavior, tool selection, and generated code. A file-based setup without ownership rules simply moves the maintenance problem from the platform to the repository.

Update control and maintenance cost

The plugin is the better choice for a developer who wants current upstream behavior without manually managing every file. That convenience comes with less control over the exact moment of change. A newly available skill or instruction may enter the environment through the plugin workflow before the team has reviewed it as part of a project change.

The file model reverses that trade-off. The team controls when to run npx skills add, which skills to select, and how the resulting files are committed. The CLI documentation should be checked before each rollout because flags, agent names, and scope behavior can change. Do not rely on a command copied from an old tutorial when the current skills CLI documentation provides the authoritative syntax.

A useful policy looks like this:

• Individual Claude Code user: plugin, unless customization is required.
• Individual Cursor and Claude Code user: file version from one known source.
• Team with strict review: file version committed or generated by a documented setup script.
• Team prioritizing upstream freshness: plugin, but only after confirming that Claude Code is the sole target.
• Team with private extensions: file version, with upstream review and an owner for merges.

The update decision should be explicit. “Automatic” and “controlled” are different operating models. Neither is universally safer. Automatic updates reduce manual work. Controlled updates make behavioral changes visible in code review.

Cross-tool reuse and customization

For mattpocock/skills, the central question is not whether the skill can be downloaded twice. It is whether both agents should receive one authoritative copy.

If Cursor and Claude Code share a skill, the file version gives the team a place to inspect the source, apply project-specific changes, and document the selected scope. It also makes the source easier to include in a new Mac setup or a clean repository bootstrap.

If only Claude Code is in use, the plugin avoids unnecessary file management. There is no benefit in creating a second editable copy simply because the CLI can add one.

Selective installation also favors files. A repository may need one review skill and one testing skill, but not the entire collection. Installing everything increases the surface area that developers must understand and maintain. A narrow file set is easier to test and explain.

The boundary is not absolute. Claude Code can use standalone skill files, while plugins use their own packaging and namespace behavior. The Claude Code plugin reference explains plugin caching and management details that matter when a team assumes the plugin is reading directly from the project directory. It should not make that assumption without checking the current documentation.

Installation and acceptance procedure

This is not a migration timeline. It is a decision-controlled installation sequence. The purpose is to prevent a duplicate source from becoming the team’s default by accident.

1. Record the target agents

Write down whether the environment supports Claude Code only, Cursor only, or both. Include the intended scope: one repository, the developer account, or a managed workstation.

If the answer is “both,” stop considering the Claude Code plugin as the shared source. Use a file-based source unless a current first-party document confirms a supported cross-tool plugin workflow.

2. Select one ownership model

Choose one owner before installing:

• Claude Code plugin management.
• Repository-controlled skill files.
• User-level files controlled by a documented bootstrap process.

Do not describe the plugin as a temporary first step before adding files. The mattpocock/skills README warning exists because this creates duplicate exposure rather than a clean fallback.

3. Install the selected source

For the file route, begin with the current documented command:

npx skills add mattpocock/skills

Use the current CLI options when the team needs a selected agent, global scope, or individual skill. For the plugin route, follow the installation sequence in the current mattpocock/skills README and Claude Code plugin documentation rather than relying on an older shell snippet.

This matters because plugin names, marketplace commands, and CLI parameters are implementation details. They must be rechecked at installation time.

4. Inspect source and scope

After installation, record:

• The repository or plugin source.
• The visible skill names.
• The namespace shown by Claude Code.
• The filesystem location for file-based skills.
• Whether the installation is global or repository-scoped.
• Whether Cursor sees the same files as Claude Code.

A successful command is not an acceptance result. The environment is accepted only when the expected agent can discover the intended skills and no unintended source is also active.

5. Test one real task

Run a small task that exercises the skill’s actual instruction. For example, ask the agent to inspect a test command, follow a repository review rule, or produce a structured implementation plan. Check whether the result reflects the expected SKILL.md.

Do not use a generic “hello world” prompt. The test should prove the skill is active, visible to the intended agent, and reading the expected version.

6. Test a clean environment

Create a clean test repository or fresh development account. Repeat the documented setup without copying hidden directories from the original Mac. This reveals whether the setup depends on an unrecorded global file, a cached plugin, or a developer-specific path.

For teams, place the setup notes near the project’s development documentation. If a remote Mac is involved, verify the same source and scope after connecting through the team’s normal ProxyMac console. The goal is not to claim identical machines. The goal is to make the skill source and installation responsibility observable.

7. Remove the duplicate safely

If both a plugin and file version are already present, first identify which source should remain. Export or copy any local customizations before removing anything. Then use the current official management method to disable or remove the unwanted source.

Avoid deleting a directory based only on its name. A file may contain the team’s only customized instruction set. Confirm the source, preserve the content, and then remove the duplicate through the supported plugin or CLI workflow.

FAQ: common installation decisions

The following answers cover the search questions that usually appear after the first installation attempt.

Final review criteria

Three questions settle most ambiguous cases:

1. Must the same skill work in Cursor and Claude Code?
   If yes, prefer the file version.

2. Must the skill be customized or reviewed in a repository?
   If yes, prefer the file version and assign an owner for upstream changes.

3. Who controls updates?
   If Claude Code should manage them and no local edits are needed, prefer the plugin. If the team requires approval and fixed content, use files.

The file version is not a permanent advantage. It carries merge work and creates a responsibility to test local changes. The plugin is not automatically more portable. It is simpler inside Claude Code, but it does not by itself create a shared Cursor environment.

For a team, the acceptance record should contain the source, scope, namespace, editable state, update method, and clean-environment result. Those fields are more valuable than a screenshot showing that an installation command completed.

Current setup versus a rented Mac environment

A local Mac can work well for one developer who controls the machine and rarely rebuilds the environment. It becomes less attractive when the team has to maintain separate global skill folders, repeat Cursor and Claude Code setup by hand, and troubleshoot differences between a developer Mac and a remote development machine. Those are three real costs: configuration drift, unclear file ownership, and duplicated environment checks.

A rented Mac from ProxyMac can be a better fit when the requirement is temporary AI-agent capacity, a clean test environment, or a repeatable remote workstation. It does not remove the need to choose plugin or file ownership, but it gives the team a separate environment in which the same acceptance checklist can be applied. Access and account procedures can be verified through the ProxyMac help center, while the skill decision remains under the developer team’s control.

If the workload requires long-term, stable heavy usage or direct physical peripherals, buying and managing a local Mac may still be the better choice. For short-lived testing, remote onboarding, or parallel environment validation, renting a Mac can avoid tying the experiment to one developer’s machine. Once the installation model is chosen, the next step is to apply the same source, scope, and duplicate-skill checks to every environment.

FAQ

Further Reading

• Cursor Privacy Mode Checklist for Teams
• AI Coding Compute Guide: Cursor, Copilot, and Claude Code