Skip to content
Founding Lifetime: every Pro skillfirst 100 members · $169 onceUpgrade
Lookbk
Sign In

Cursor agent skills: add a skill from GitHub, step by step

How to get a skill from a GitHub repository into Cursor: the folders it loads, the plugin route in its docs, Cloud Agents and the frontmatter.

For
Cursor users adding skills they found on GitHub
Written for
Cursor
Time
11 min read · updated Nov 21, 2026

The short answer

Cursor’s documentation says skills are not imported on their own. A skill folder (one with a SKILL.md) goes in one of four places Cursor loads skills from: .agents/skills/ or .cursor/skills/ in a project, ~/.agents/skills/ or ~/.cursor/skills/ for everything you do. Restart Cursor and look under Customize, then Skills; or run gh skill install OWNER/REPOSITORY SKILL --agent cursor. To bring in a whole GitHub repository, package its skills as a plugin: Customize, From GitHub Repository only works when the repository has a .cursor-plugin/marketplace.json. Cloud Agents see only project skills and ~/.cursor/skills after you turn on sync.

Most skills on GitHub are written as plain folders, and a search for “Cursor agent skills” usually wants one thing: how to get one of them working in Cursor. Cursor’s own documentation answers it in three places, a skills page, a plugins page and a plugin reference, and the answer has more than one route. This page walks through each, using those pages as they stood on 21 November 2026, and says where the docs stop and our reading begins.

What Cursor loads, and from where

Cursor’s documentation says that when it starts it discovers skills from skill directories and makes them available to Agent, which decides when one is relevant. These are the folders it lists.

Folders Cursor loads skills from, per its skills page
FolderScopeNote
.agents/skills/ProjectAlso found in nested project folders
.cursor/skills/ProjectAlso found in nested project folders
~/.agents/skills/You, on this machineNot copied to Cloud Agents
~/.cursor/skills/You, on this machineThe only folder that can sync to Cloud Agents
.claude/skills/, .codex/skills/ and the same two under ~Project and youLoaded “for compatibility”

A skill is a folder that holds a SKILL.md. Cursor’s docs say it walks a skills folder recursively and picks up any SKILL.md it finds, so you can group skills under category folders, and the skill’s identity is the folder that holds the SKILL.md, not the category. A skills folder inside a subfolder of your repository, such as apps/web/.cursor/skills/, is scoped to files inside that subfolder.

Route 1: copy the skill folder in

This is the fastest route and the one that works for a single skill. The docs list the folders above as the places Cursor loads skills from, and do not describe a command that copies one in; copying the folder is our reading of that list, not a step the docs spell out.

  1. Step 1: Find the skill’s folder in the repository

    Open the repository and look for a folder that contains a SKILL.md. Repositories that collect skills usually put them under a skills/ folder, one folder per skill. Claude skills on GitHub compares the main collections.

  2. Step 2: Read it before you copy it

    Read the SKILL.md and any file in its scripts/ folder. A skill can include scripts that the agent runs with your permissions, and nothing in Cursor reviews it for you. Safety checks before running a skill is the short list.

  3. Step 3: Copy the folder, not just the file

    Copy the whole folder, keeping its name, into .agents/skills/ or .cursor/skills/ for one project, or into ~/.agents/skills/ for every project. Cursor’s docs say name in the frontmatter must be lowercase letters, numbers and hyphens, and must match the parent folder name, so don’t rename the folder.

    Terminal
    git clone https://github.com/owner/repo.git
    mkdir -p .agents/skills
    cp -r repo/skills/my-skill .agents/skills/my-skill
  4. Step 4: Restart Cursor and check

    Cursor discovers skills when it starts. Open Customize in the sidebar and go to Skills. Per the docs, skills from plugins or your project appear there in the Agent Decides section.

  5. Step 5: Run it

    Type / in Agent chat and search for the skill name. The docs say a skill invoked that way attaches to one message. Without that, the agent decides from the skill’s description whether it fits.

To keep a skill on for a whole session, the docs say to use it as a Custom Mode with Option+Enter on Mac or Alt+Enter on Windows. Cursor reads .agents/skills and .claude/skills both, so if a skill sits in both it can show up twice. Keep one copy.

Route 1b: one command with gh skill

GitHub CLI has a gh skill command, which GitHub calls a public preview, that installs a skill from a GitHub repository and can target Cursor. We ran it on GitHub CLI 2.104.0 against a local test skill, with a temporary home folder: --agent cursor at the default project scope wrote .agents/skills/<skill>/SKILL.md inside the repository, and --agent cursor --scope user wrote ~/.cursor/skills/<skill>/SKILL.md. That second folder is the one Cursor can sync to Cloud Agents. The command’s help says Cursor shares .agents/skills with several other agents at project scope.

GitHub CLI
gh skill preview OWNER/REPOSITORY SKILL
gh skill install OWNER/REPOSITORY SKILL --agent cursor

gh skill preview shows the skill’s SKILL.md and file tree without installing anything, which is the read-first step above done for you. GitHub’s own documentation warns that skills are not verified by GitHub and can contain hidden instructions or malicious scripts. Restart Cursor afterwards and look under Customize, then Skills. GitHub’s command reference (opens in a new tab) lists the other subcommands.

Route 2: a plugin, for a whole repository

Under “Installing skills from a repository”, Cursor’s skills page says skills aren’t imported on their own. To bring skills in from a GitHub repository, package them in a plugin and publish that plugin through a marketplace. In Customize, choose From GitHub Repository; the repository needs a .cursor-plugin/marketplace.json. The skills then arrive with the plugin and appear alongside your other skills.

So a repository that only holds skills/<name>/SKILL.md folders can’t be imported as it stands. Either copy the folders you want (route 1), or ask the maintainer for a marketplace file, or make your own. Cursor’s plugins page describes two plugin layouts. An Agent Plugin has a plugin.json at its root and can package skills and MCP servers; a Cursor Plugin has .cursor-plugin/plugin.json and can also carry rules, agents, commands and hooks. A plugin that follows the open Agent Plugins specification loads in Cursor.

Cursor’s plugin reference describes the marketplace file for a repository with several plugins: .cursor-plugin/marketplace.json at the repository root, with a required name, a required owner (with a name) and a required plugins array. Each plugin entry needs a name and a source, the path to the plugin’s folder. For a source of my-skills, the parser looks for my-skills/.cursor-plugin/plugin.json, and a Cursor Plugin manifest only requires a name. Put together from those pages, a repository that holds one skills plugin looks like this.

Layout, after the multi-plugin example in the plugin reference
my-repo/
├── .cursor-plugin/
│   └── marketplace.json
└── my-skills/
    ├── .cursor-plugin/
    │   └── plugin.json
    └── skills/
        └── code-reviewer/
            └── SKILL.md
.cursor-plugin/marketplace.json
{
  "name": "my-marketplace",
  "owner": { "name": "Your Org" },
  "plugins": [
    {
      "name": "my-skills",
      "source": "my-skills",
      "description": "Skills for code review"
    }
  ]
}
my-skills/.cursor-plugin/plugin.json
{
  "name": "my-skills",
  "description": "Skills for code review",
  "version": "1.0.0"
}

We have not run this layout through Cursor, so treat it as the documented shape, not a tested recipe. To test a plugin before you publish it, the plugins page says to copy it into ~/.cursor/plugins/local/<name>, then restart Cursor or run Developer: Reload Window, and check Customize for the skills you expect. On Enterprise plans an admin setting, Allow Local Plugin Imports, controls this and is off by default. For the official marketplace, the reference says plugins are reviewed by the Cursor team and submitted at cursor.com/marketplace/publish as a public Git repository.

Route 3: share a skill with your team

Two things are available on Teams and Enterprise plans. A member can publish a personal skill from ~/.cursor/skills/ to the team’s Default marketplace: Customize, Skills, open the skill, Publish. Cursor packs it into a plugin, stores a copy in a repository it hosts for the team, and the skill then loads from that plugin instead of your local folder. Installs are opt-in for teammates, and one skill becomes one plugin. Admins can also import a repository as a team marketplace under Dashboard, Plugins & MCPs, and choose per plugin whether it is Default Off, Default On or Required. The Teams plan allows one team marketplace; Enterprise allows unlimited ones.

Publishing is different from putting the skill in your repository. A skill committed to .cursor/skills/ or .agents/skills/ goes to everyone who clones that repository.

Route 4: Cloud Agents and automations

This is where skills most often seem to vanish. The docs are specific: Cursor does not copy ~/.agents/skills/ or unsynced local skills to Cloud Agents, Agents Window remote SSH sessions or self-hosted workers. For those, use project skills from the repository, or bake skills into the worker image.

  • Sync, for your own Cloud Agents. Under Settings, Agents, Context and Tools, turn on Sync Skills for Cloud Agents and confirm. Cursor moves the contents of ~/.cursor/skills/ into synced storage. Only that folder syncs; project skills and ~/.agents/skills/ stay local. Synced skills stay private to you.
  • Automations don’t get synced skills. The docs say automation runs don’t load them, including those set to run as you. Put the skill in the repository’s .cursor/skills/ folder instead.
  • Team admins can switch sync off for everyone under Team Settings, Security & Identity.

The header that decides when a skill runs

Each SKILL.md begins with a YAML header. These are the fields on Cursor’s skills page.

SKILL.md frontmatter fields in Cursor
FieldRequiredWhat the docs say it does
nameYesThe identifier: lowercase letters, numbers and hyphens, and it must match the parent folder name
descriptionYesWhat the skill does and when to use it; the agent uses it to decide relevance. A Cloud Agent run warns about a skill with none
pathsNoGlob patterns, as a comma-separated string or a list. The skill is surfaced only when the agent works with matching files. The older globs field is still accepted
disable-model-invocationNoWhen true, the skill is included only when you type /skill-name, like a slash command
icon, colorNoThe badge when the skill is used as a Custom Mode
metadataNoFree key-value pairs

Two of these matter for a skill you took from somewhere else. If it is too eager, set disable-model-invocation: true and call it yourself. If it is meant for one kind of file, paths keeps it out of unrelated work. Neither field changes what the skill does when it runs.

Where to look for skills to add

Searches for the best or an awesome list of Cursor skills have nothing to sort by: Cursor shows no install counts or ratings for skills, and neither does the rest of the web. What you can check is where skills come from.

  • Built in. Cursor’s skills page lists 19 built-in skills, such as /create-skill, /create-rule, /migrate-to-skills, /review, /loop and /split-to-prs. They appear beside the skills you add.
  • The Cursor Marketplace. Official plugins, which the plugins page says are distributed as Git repositories and each manually reviewed before listing. Search in Customize or at cursor.com/marketplace.
  • Community plugins. The plugins page points to cursor.directory for community plugins and MCP servers. It is a third-party site, so read what you install.
  • Public GitHub repositories. Anything with SKILL.md folders. Agent skills marketplaces puts Cursor’s catalog route next to the other agents’, and awesome Claude skills covers the lists that point to more. The folder format is shared, so a list written for another agent still applies.

If you already have rules in .cursor/rules and are wondering whether to convert them, the skills page describes /migrate-to-skills: it converts rules set to “Apply Intelligently” (no alwaysApply, no globs) and slash commands, and leaves rules with alwaysApply: true or globs alone. Cursor rules vs skills sets the two pages side by side and says which to write, and the Cursor page lists the folders and a short rules comparison in one table.

Skills that make a finished file

Lookbk’s skills render something you can open: a title video, a deck, a link-preview image, a landing page. Each skill’s page shows what it made, and the installer’s --shared flag writes only ~/.agents/skills/, which Cursor loads, so one copy doesn’t show up twice. These four are free.

Mono Editorial Landing: an example of what it makes
Free
web
Mono Editorial LandingClaude CodeCodexCursor+3 more agents
Swiss Grid Deck: an example of what it makes
Free
slides
Swiss Grid DeckClaude CodeCodexCursor+3 more agents
Editorial OG Card: an example of what it makes
Free
image
Editorial OG CardClaude CodeCodexCursor+3 more agents
Kinetic Title Drop: an example of what it makes
Free
video
Kinetic Title DropClaude CodeCodexCursor+3 more agents

Run the installer with the last part of a skill page’s address, restart Cursor, then type / in Agent chat. For a Cloud Agent, run it from the repository root with --project and commit the folder it writes.

Terminal
curl -fsSL https://lookbk.dev/cli.js | node - add mono-editorial-landing --shared

Common questions

How do I add a skill from GitHub to Cursor?
Copy the skill’s folder, the one with SKILL.md, into .agents/skills/ or .cursor/skills/ in a project, or ~/.agents/skills/ or ~/.cursor/skills/ for all projects, then restart Cursor. Cursor’s docs say skills aren’t imported from a repository on their own; to import a whole repository it must be packaged as a plugin with a .cursor-plugin/marketplace.json.
Why does Cursor’s “From GitHub Repository” not find my skills?
Per Cursor’s docs, that import needs a .cursor-plugin/marketplace.json in the repository, because it imports plugins through a marketplace. A repository of bare SKILL.md folders has none, so copy the folders you want instead.
Is there a Cursor skills marketplace?
There is the Cursor Marketplace for official plugins, which can bundle skills and are manually reviewed, and team marketplaces on Teams and Enterprise plans. The docs also point to cursor.directory for community plugins and MCP servers. There is no separate store for single skills.
Which folder should I use, .cursor/skills or .agents/skills?
Both are loaded. .agents/skills is the one other agents such as Codex and GitHub Copilot read too, so it avoids keeping two copies. ~/.cursor/skills is the only home folder that can sync to Cloud Agents.
Why does my skill work locally but not in a Cloud Agent?
Cursor doesn’t copy ~/.agents/skills/ or unsynced local skills to Cloud Agents. Turn on Sync Skills for Cloud Agents and keep the skill in ~/.cursor/skills/, or commit it to the repository’s .cursor/skills/. Automation runs don’t load synced skills at all.
How do I stop Cursor from running a skill on its own?
Add disable-model-invocation: true to the skill’s frontmatter. It is then included only when you type /skill-name in Agent chat.
Can I limit a skill to certain files?
Yes. Add paths with glob patterns to the frontmatter, and Cursor surfaces the skill only when the agent works with matching files. A skill in a nested project folder is scoped to that folder without it.

Sources

What this guide says about other companies’ tools comes from their own documentation, checked on Nov 21, 2026.

Did this guide help?

See a skill’s result before you install it.

Every skill page shows what it makes, what it needs and which agents can run it.