Cursor Agent Skills Installation: mattpocock/skills

You installed the skills, but Cursor still cannot find them in the repository.

Install mattpocock/skills through skills.sh from the target repository root, keep the installation project-scoped, then run setup-matt-pocock-skills once. Use Skills for procedural workflows and Cursor Rules for always-on project constraints. If your team also uses Claude Code, choose either the managed plugin or editable files. Do not install both.

Who should read this: Individual developers who want TDD, diagnosis, and code review flows in Cursor. Technical leads standardizing Agent behavior through Git. Distributed teams that need the same setup on local and remote Mac environments.

Last updated August 13, 2026. Installation details were checked against the mattpocock/skills README, the Cursor 2.4 changelog, the Cursor Skills documentation, and the skills.sh CLI documentation.

Project scope beats global scope for team repositories

The first decision is not the command. It is the installation scope.

For a personal sandbox, a user-level skill directory can be convenient. For a team repository, project-level installation is the safer default because the skill files can be reviewed, changed, and committed with the codebase.

Cursor supports project and user scopes for Skills. The exact path should be confirmed against the current Cursor documentation before rollout, but the practical distinction is stable:

The repository README describes the central difference: the Claude Code plugin is managed and read-only, while skills.sh copies ordinary editable files into your project. That is why Cursor teams should normally choose the project-level skills.sh route.

Before you run the installer, check these conditions:

• You are inside the repository that should receive the files.
• The repository has a clean or clearly understood Git state.
• Node.js and Git are available in the shell.
• You can write to the repository.
• You are working on a branch where unwanted files can be removed safely.
• You have decided whether the team will commit the installed Skills.
• You have not already installed the same collection through the Claude Code plugin.

Where should you run npx skills add mattpocock/skills?

Run it from the root of the target repository. Do not run it from your home directory, a parent workspace, or a different checkout and assume Cursor will attach the files to the correct project.

A quick check is:

pwd
git rev-parse --show-toplevel
git status --short

The second command should print the repository root where you want the Skills to live. If it points to the wrong checkout, stop there. Installing first and moving files later makes scope errors harder to spot.

First installation: select only the workflows you can support

From the repository root, run:

npx skills@latest add mattpocock/skills

The skills CLI is designed to run through npx, so you do not need to maintain a separate global installation just to start the setup. The official CLI documentation uses the same npx skills add pattern for installing a repository of Skills. (skills.sh)

The installer will ask you which Skills to install and which agents should receive them. For a Cursor project, select Cursor when the installer presents the agent choices.

Select setup-matt-pocock-skills during the first pass. This is not an optional decorative Skill. It establishes repository-specific decisions that other engineering workflows may depend on.

Add other Skills according to your actual workflow. A small first set could include:

• tdd for test-first implementation work.
• diagnose or the current repository name for debugging workflows.
• code-review for structured review.
• triage for issue classification.
• Documentation-oriented Skills if your team maintains domain or architecture records.

Do not select every available Skill just because the collection is popular. More files mean more review surface, more possible triggers, and more maintenance. The skills.sh catalog warns that listed Skills should still be reviewed before installation because catalog availability does not guarantee that every Skill is safe or suitable for your repository. (skills.sh)

After the installer exits, inspect the result before opening Cursor:

find .cursor .agents -name SKILL.md -print 2>/dev/null
git status --short
git diff --stat

You are looking for three things:

1. The files are inside the intended repository.
2. Every selected Skill has a visible SKILL.md.
3. The Git diff contains only the files you expect.

Do not judge success by the installer output alone. A successful command can still produce the wrong scope, the wrong agent target, or an unexpectedly large file set.

What should you commit after installation?

Commit the project-level Skill files that the team expects every contributor and Agent to use. Keep personal experiments, private prompts, and individual preferences outside the repository unless the team explicitly wants them versioned.

Review supporting scripts and reference files as carefully as SKILL.md. A Skill can contain more than prose. Cursor’s release notes describe Skills as SKILL.md files that may include commands, scripts, and instructions. (cursor.com)

First setup: configure the repository instead of relying on defaults

Once the files are present, open the repository in Cursor and invoke the setup Skill manually:

/setup-mattpocock-skills

Run it once for the repository. The upstream README says the setup flow asks about the issue tracker, triage labels, and where generated documentation should be saved.

Treat this as a configuration interview. Do not answer every question with the first default if your team already has conventions.

Record decisions such as:

• Which issue tracker is authoritative.
• Which labels indicate that an issue needs triage, more information, agent work, or human review.
• Where generated domain and process documents belong.
• Whether the repository already uses AGENTS.md, CLAUDE.md, or another instruction file.
• Which files require human approval before an Agent can modify them.

The setup result should be visible in the repository. Inspect the diff immediately:

git status --short
git diff -- AGENTS.md CLAUDE.md docs

If the setup Skill creates or modifies an instruction file and documentation directory, review the changes as policy, not as generated noise. These files affect future Agent behavior. They should have an owner, a review path, and a clear rollback method.

Cursor Skills can be invoked manually from the slash-command interface. They can also be surfaced automatically when the Agent decides that a Skill matches the current context. Cursor introduced Skills as a way to provide dynamic, procedural guidance without loading every workflow into every conversation. (cursor.com)

That creates two different test cases:

• Manual invocation confirms that the Skill is installed and callable.
• Automatic discovery confirms that the Skill description gives the Agent enough information to select it in the right context.

A Skill that works only when you remember its exact slash command is usable, but not fully integrated into the team workflow.

Skills versus Cursor Rules: keep procedures separate from constraints

How should Cursor Skills and Rules be divided?

Use a Skill for a workflow that should be loaded when relevant. Use a Rule for a constraint that should remain active across ordinary work.

A useful boundary looks like this:

Put these in Skills:

• How to clarify a vague requirement.
• How to run a TDD loop.
• How to diagnose a failing test.
• How to perform a structured code review.
• Which scripts or documents to inspect during a particular engineering task.
• A step-by-step release or triage procedure.

Put these in Cursor Rules:

• Required language or framework conventions.
• Directory boundaries.
• Naming rules.
• Security restrictions.
• Testing commands that apply to every change.
• Pull request requirements.
• Files that must not be edited without approval.

Cursor’s own release notes describe Skills as better suited to dynamic context discovery and procedural instructions, while always-on Rules are better for declarative constraints.

A common failure is putting a complete TDD procedure into a global Rule. That loads process instructions even when you are reviewing documentation or changing deployment configuration. The opposite failure is putting a security requirement into a Skill that the Agent may not select.

Use this test:

• If the instruction starts with “Always,” consider a Rule.
• If it starts with “When you are doing X, follow these steps,” consider a Skill.
• If it needs scripts, references, or task-specific investigation, use a Skill.
• If violating it would make the change unacceptable regardless of task, use a Rule.

During the first real task, ask the Agent to explain which Skill it selected and why. Do not treat that explanation as proof. Check the files it actually read, the scripts it actually called, and the diff it produced.

First development task: validate composition instead of activating everything

Choose a small task that contains a real engineering decision but has a limited blast radius. A failing test, a narrow bug report, or a small review is better than a large feature.

Use a sequence such as:

1. Ask the Agent to restate the requirement and list unknowns.
2. Invoke the relevant planning or questioning Skill.
3. Use tdd only if the task needs a test-first change.
4. Use a diagnosis Skill if the task begins with a failure.
5. Run the repository’s actual validation commands.
6. Ask for a review of the final diff.
7. Record which Skills were useful and which created noise.

Do not enable every workflow in one prompt. You want to know whether each Skill activates in the correct context. Otherwise, a poor result could come from unclear requirements, conflicting instructions, an unsuitable Skill, or a bad repository state.

The repository’s current Skill names are the source of truth. Names can change as the upstream project evolves. If a Skill has been renamed or removed, do not keep copying its old name from team notes or an outdated article. Re-run the installer’s listing or inspect the current upstream repository before updating internal documentation.

A useful acceptance record includes:

Task:
Expected Skill:
Manual or automatic invocation:
Files read:
Scripts called:
Tests run:
Unexpected behavior:
Decision:

This is more valuable than a screenshot showing that the Skill exists. It tests behavior in context.

Why the Skill may not appear in Cursor

Why is mattpocock/skills installed but missing from Cursor?

Check the failure in this order:

1. Wrong directory
   Confirm that the files are under the repository currently open in Cursor. A project-level installation in another checkout will not help the current workspace.

2. Missing SKILL.md
   Each Skill needs the expected file name and directory structure. A renamed file, nested extra directory, or incomplete copy can prevent discovery.

3. Invalid front matter
   Inspect the metadata at the beginning of SKILL.md. The name and description must be valid for Cursor’s Skill discovery rules. Do not edit upstream metadata casually. Compare it with the current file in the repository.

4. Wrong scope
   A user-level installation may be available in one workspace but not behave as expected in a team repository. Confirm whether you intended project scope or user scope.

5. Stale Cursor state
   Close and reopen the workspace, or reload Cursor after correcting the files. Test manual slash invocation after the reload.

6. Agent target was not selected
   The installer asks which agents should receive the files. Recheck the installation output and local directory structure.

7. Conflicting installations
   If the same collection was installed through both the Claude Code plugin and skills.sh, remove the duplicate route before troubleshooting discovery.

The Cursor documentation and current product interface may change. If the directory or metadata behavior differs from this runbook, follow the current official documentation and update your team record rather than forcing the old layout.

Claude Code plugin or editable files: choose one path

The upstream repository gives two different operating models.

The Claude Code plugin is a managed, read-only bundle. It is suitable when you want upstream updates to arrive as part of the plugin model and do not need to edit the installed files.

The skills.sh route copies editable files into your project. It is suitable for Cursor teams that want to review the files, adapt instructions, and commit the configuration with the repository.

Can Claude Code and skills.sh be installed at the same time?

Do not install both for the same collection. The README explicitly warns that using both leaves duplicate Skills in the environment. (github.com)

Make the decision per repository or team policy:

• Choose the plugin when upstream ownership and managed updates matter more than local edits.
• Choose skills.sh when Git review, project-specific changes, and Cursor compatibility matter more.
• If different team members use different agents, document the chosen source and verify that they do not receive duplicate copies through separate setup scripts.

The fact that the two routes exist does not mean they should be layered.

First week: turn installation into a maintenance process

Installing once is easy. Keeping the workflow trustworthy is the engineering work.

Create a lightweight ownership rule for the first week:

• One person reviews upstream changes.
• One person validates the update in a temporary branch.
• One person confirms that team customizations still exist.
• The repository owner approves the merge.
• A rollback commit or previous known-good revision remains available.

Before running:

npx skills update

inspect the upstream changes and compare them with your local files. The upstream README describes npx skills update as the manual update path for editable files.

Do not update directly on the default branch. Use a branch and record:

git diff --name-status
git diff --stat

Review more than changed instructions. Check:

• New or removed scripts.
• New reference files.
• Shell commands.
• File write locations.
• Network calls.
• Permission assumptions.
• Changes to setup behavior.
• Changes to Skill descriptions and trigger conditions.

A popular Skill still requires review. Install counts on skills.sh describe catalog activity, not your organization’s security approval. The catalog itself recommends reviewing Skills and notes that it cannot guarantee the quality or security of every listed item.

Local Mac to remote Mac: use an acceptance gate

A team that develops locally and delivers through a remote Mac should compare behavior, not just file presence.

Use this checklist after installing the same repository on both environments:

• [ ] Confirm the same Git revision is checked out locally and remotely.
• [ ] Confirm the same project-level Skill directories exist.
• [ ] Confirm each selected directory contains the expected SKILL.md.
• [ ] Confirm Cursor opens the intended repository root.
• [ ] Confirm manual invocation of setup-mattpocock-skills.
• [ ] Confirm the setup output and generated documentation match the team decision.
• [ ] Confirm the same Skill appears in Cursor after reload.
• [ ] Run one small TDD, diagnosis, or review task on both environments.
• [ ] Compare the files read, commands requested, and final diff.
• [ ] Record permission prompts, missing tools, and initialization failures.
• [ ] Save the result as pass, needs adjustment, or hold.

Do not infer remote Mac behavior from public documentation. The remote environment may differ in Cursor version, shell configuration, permissions, repository mounting, or preinstalled tools. Record only what your team actually verifies.

Use these acceptance outcomes:

• Pass: Installation scope, discovery, setup, and the representative task match the local baseline.
• Needs adjustment: Files are correct, but reload, permissions, paths, or tool availability differ.
• Hold: The Agent cannot discover the Skill, setup writes to the wrong location, or the representative task produces materially different behavior.

For repeatable delivery, keep the acceptance record with the repository or team runbook. You can also use the MacHTML console when your team needs a controlled remote workspace, but validate the actual Cursor initialization sequence rather than assuming that a remote shell is identical to your laptop.

The decision in one minute

Choose project-level skills.sh installation when you need editable files, Git review, and consistent Cursor behavior across a team.

Choose user-level installation only for personal workflows that do not need repository reproducibility.

Choose the Claude Code plugin when you want the managed bundle and will not also copy the same Skills into the project.

Keep Skills procedural. Keep Cursor Rules persistent. Run setup once, inspect the diff, test one real task, and establish an update branch before allowing the collection into shared development.

If your current setup relies on individual laptops, undocumented shell state, and manual Cursor configuration, it has three real weaknesses: new contributors cannot reproduce it reliably, remote environments may discover different files, and rollback depends on memory instead of Git. After local validation, review the MacHTML help resources and decide whether a repeatable remote Mac workspace would make initialization, permissions, and rollback easier to control. For temporary Agent testing or a short-lived team environment, renting a Mac can be more practical than rebuilding the same setup on every machine; for permanent heavy workloads or workflows that require direct physical hardware access, owning the Mac remains the better fit.