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.
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.
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 askills/folder, one folder per skill. Claude skills on GitHub compares the main collections.Step 2: Read it before you copy it
Read the
SKILL.mdand any file in itsscripts/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.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 saynamein the frontmatter must be lowercase letters, numbers and hyphens, and must match the parent folder name, so don’t rename the folder.TerminalStep 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.
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’sdescriptionwhether 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.
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.
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.
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,/loopand/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.mdfolders. 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.
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.
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.jsonin the repository, because it imports plugins through a marketplace. A repository of bareSKILL.mdfolders 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/skillsor.agents/skills? - Both are loaded.
.agents/skillsis the one other agents such as Codex and GitHub Copilot read too, so it avoids keeping two copies.~/.cursor/skillsis 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: trueto the skill’s frontmatter. It is then included only when you type/skill-namein Agent chat. - Can I limit a skill to certain files?
- Yes. Add
pathswith 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?
Read next
All guidesAgent skills marketplaces: how each agent adds a catalog
There is no one skills marketplace for every agent. How Claude Code, Cursor, OpenCode, Gemini CLI, Codex and Copilot each add a catalog, from their own docs.
Where skills live: folders for every agent
The folders Claude Code, Codex, Cursor and other agents read skills from, which copy wins when two share a name, and what cloud agents can see.
Install a skill in any agent
Install a Lookbk skill in Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI or OpenCode: where each looks, how to check it loaded and how to run it.
Claude skills on GitHub: main repos and how to use them
The GitHub repositories that hold Claude skills, checked on the GitHub API: license, last commit, skill count. Then how to copy one into your agent.
Cursor rules vs skills: which to use for what
Cursor rules are .mdc files in .cursor/rules; skills are SKILL.md folders. How each applies, which fits which job, and what /migrate-to-skills converts.
Safety checks before running a skill
A skill is instructions and code your agent may run. Six checks to make first: its source, its commands, its network use and what it may do without asking.
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.



