Cursor skills: how Agent Skills work in Cursor, and when to use them instead of rules

Cursor skills are Agent Skills: folders with a SKILL.md file that Cursor discovers when it starts and hands to its agent, which decides from each skill’s description whether the current task needs it. Cursor reads them from .agents/skills and .cursor/skills in a project, from ~/.agents/skills and ~/.cursor/skills on the machine, and from Claude and Codex skill folders for compatibility. A skill can also be run on demand by typing / in Agent chat. Skills sit alongside two older Cursor mechanisms, project rules in .cursor/rules and AGENTS.md, and choosing between the three is most of the work. This guide explains how Cursor decides to load a skill, how skills differ from rules and AGENTS.md, how to install shared skills with npx skills add ... -a cursor, and three skills that address the problems Cursor users hit most: MCP tool sprawl, no visibility into model traffic, and skills drifting across a team.

TL;DR

• Cursor loads skills from .agents/skills, .cursor/skills, ~/.agents/skills and ~/.cursor/skills, plus .claude/skills and .codex/skills for compatibility. The agent picks a skill from its description; /skill-name forces it for one message.
• Rules are text inserted at the start of context (always, by glob, by description or by @-mention). Skills are portable folders with scripts and references, loaded progressively. AGENTS.md is plain Markdown with no metadata.
• npx skills add <owner/repo> -a cursor writes to .agents/skills, which Cursor reads directly. A test install on October 28, 2026 confirmed it with six skills and no .cursor folder.
• Only ~/.cursor/skills syncs to Cloud Agents. Project skills and ~/.agents/skills stay local unless committed to the repository.
• For Cursor teams, the most useful open-source skills cover one MCP endpoint instead of many, observability for model and tool calls, and keeping team skills versioned.

How Cursor decides to load a skill

When Cursor starts, it discovers every skill and presents the list to its agent, which “decides when they are relevant based on context.” The description is what it reads to make that call; Cursor notes that without one, “the agent is unlikely to pick the skill on its own.” Two frontmatter fields and two manual controls change the default.

Cursor’s skills documentation lists the controls:

• Automatic (default). The agent applies a skill when it judges it relevant. Cursor’s frontmatter table says the description is “used by the agent to determine relevance.”
• paths. Glob patterns that limit a skill to matching files. The skill “is only surfaced when the agent works with files that match,” which keeps file-specific guidance out of unrelated work.
• disable-model-invocation: true. The skill is included only when the user types /skill-name, which makes it behave like a classic slash command.
• Manual for one message. Typing / in Agent chat and choosing a skill attaches it to that message only.
• Custom Mode for a session. Option+Enter on Mac or Alt+Enter on Windows turns a skill into a Custom Mode, keeping it in context for the whole session with a badge in the chat input.

Underneath, Cursor follows the Agent Skills specification: about 100 tokens of name and description per skill at startup, the full SKILL.md body (under 5,000 tokens recommended) when activated, and scripts/, references/ and assets/ only when the body points to them. Cursor’s own guidance is the same: “Keep your main SKILL.md focused and move detailed reference material to separate files.”

To see what Cursor found, open Customize in the sidebar and go to Skills. Skills from plugins or the project appear alongside rules in the Agent Decides section, which is a quick way to confirm an install worked before testing whether the agent picks it.

Skills vs rules vs AGENTS.md

Cursor has three ways to give its agent standing instructions, and they differ mainly in when the text enters the context and what it can carry. Rules and AGENTS.md put their content at the start of the model context when they apply. Skills arrive as a one-line description first and load their body and files only when chosen.

The table compares them from Cursor’s rules and skills documentation:

Rule content “reach[es] Agent as written” at the start of context; a file mentioned with @ is read by the agent when needed, not inlined. Team Rules, set from the dashboard on Team and Enterprise plans, take precedence in the order “Team Rules → Project Rules → User Rules,” and an admin can enforce one so it cannot be switched off. Cursor adds a caution of its own: “AI guidance should not be your only security control.”

A working split for most repositories:

• AGENTS.md for short facts that apply everywhere: the test command, the package manager, directory conventions. It is also read by Codex, so one file serves both.
• Rules for conventions tied to file types (globs: src/components/**/*.tsx) or that must always apply, especially enforced Team Rules.
• Skills for procedures: a release runbook, a migration checklist, a security audit with a grep list, anything with a script or a long reference that should cost nothing until needed.

Cursor ships /migrate-to-skills, added in 2.4, which converts “Apply Intelligently” rules (no alwaysApply, no globs) and slash commands into skills. Rules with alwaysApply: true or globs are left alone, because their triggering is explicit rather than judged.

Where Cursor skills live

Cursor loads skills from two project folders and two user folders, and also reads the folders Claude Code and Codex use. Project skills can be nested anywhere in a repository; a skill inside a subfolder is automatically scoped to files under that folder.

The directory section is explicit on sync: “Only ~/.cursor/skills/ syncs. Project skills, ~/.agents/skills/, and other files on your machine stay local.” Cursor also does not copy ~/.agents/skills to Agents Window remote SSH sessions or self-hosted workers. Automations do not load synced personal skills at all; Cursor’s advice is to put a skill an automation needs in the repository’s .cursor/skills/ folder. On Teams and Enterprise plans, admins can switch sync off for everyone under Security & Identity.

The nested skill directories behaviour suits monorepos. A skill in apps/web/.cursor/skills/deploy-web/ “is only surfaced when the agent works with files under apps/web/,” while root skills are available everywhere. Category folders are organizational only; the skill’s identity is the folder that holds SKILL.md.

Writing a Cursor skill

A Cursor skill needs a folder and a SKILL.md with two required fields: name (lowercase letters, numbers and hyphens, matching the folder) and description. Cursor adds optional fields that the open spec does not define, which matters when the same skill is meant to work in other agents.

---
name: react-component-patterns
description: Conventions for writing React components in this codebase, including file
  layout, named exports and test placement. Use when creating, splitting or reviewing a
  component, or when the user mentions "new component" or "props drilling".
paths:
  - "**/*.tsx"
metadata:
  version: "1.2.0"
---

# React component patterns
...

paths, disable-model-invocation, icon and color are Cursor fields. The specification defines name, description, license, compatibility, metadata and the experimental allowed-tools. An agent that implements only the spec will not apply Cursor’s scoping or invocation behaviour. The agent-skills-for-teams skill gives the rule of thumb for mixed teams: “keep shared skills to spec fields and put harness-only behavior in a separate, clearly named skill.”

Cursor’s built-in /create-skill generates the folder and frontmatter from a description of the task. Whether written by hand or generated, the description deserves most of the effort. The agent-skills-for-teams reference on triggering offers a formula (capability, then situations, then phrases users type, then a “Not for…” boundary) and a warning that agents “skip skills for tasks they believe are simple.” Scripts in scripts/ are referenced from the body by relative path; Cursor’s docs ask that they be “self-contained, include helpful error messages, and handle edge cases gracefully.”

Installing skills with npx skills -a cursor

The open-source skills CLI installs GitHub-hosted skills into Cursor in one command. With -a cursor, project installs go to .agents/skills/<name>, a path Cursor reads natively, so the CLI writes no .cursor folder at all. Global installs with -g go to ~/.cursor/skills, the one user folder that can sync to Cloud Agents.

The CLI’s agent table lists Cursor with a project path of .agents/skills/ and a global path of ~/.cursor/skills/. Both match Cursor’s documentation.

In a test install on October 28, 2026, The Frontier Wire ran npx -y skills@1.7.4 add build-with-ai-hq/<name> -a claude-code -a codex -a cursor -y for each of six skills in an empty Git repository. Every run reported “Installed 1 skill,” wrote the files to ./.agents/skills/<name>, and classified the install as “universal: Codex, Cursor” with a symlink for Claude Code. The repository afterwards contained .agents/, .claude/ and a skills-lock.json, and no .cursor/ directory. npx skills list showed each skill available to Cursor. The CLI also printed: “Review skills before use; they run with full agent permissions.”

Cursor’s own documented route is different. Its docs say skills “aren’t imported on their own”; to bring them in from GitHub, package them as a plugin with a .cursor-plugin/marketplace.json and import the repository from Customize or add it as a team marketplace. The plugin route suits org-wide distribution through Cursor’s dashboard. The CLI route suits repositories where the skill should be committed next to the code and shared with Codex and Claude Code users on the same team.

Skills worth adding for Cursor users

Six MIT-licensed skills from the build-with-ai-hq GitHub organization, published in October 2026, cover infrastructure work that Cursor users building LLM applications run into. Each pairs vendor-neutral practice with Bifrost, Maxim AI’s open-source AI gateway, as the default control point. Three map closely onto Cursor-specific problems and get detailed treatment below:

• mcp-gateway-best-practices: too many MCP servers in mcp.json, credentials in config files, and tools the agent misuses.
• llm-observability-stack: no record of what Cursor, or the application being built in it, sends to model providers.
• agent-skills-for-teams: skills copied between .cursor/skills, .agents/skills and home folders until nobody knows which version is live.

Example prompts that match phrases in their descriptions, typed into Cursor’s Agent chat without a / so the agent has to choose:

• “We have too many MCP servers and the agent picks the wrong tool.”
• “Give Cursor and Claude Code one MCP endpoint instead of five.”
• “Add OpenTelemetry to every LLM call in this service and alert on errors.”
• “This skill never triggers; fix the SKILL.md description.”

mcp-gateway-best-practices: one MCP endpoint for Cursor

mcp-gateway-best-practices turns an ad hoc MCP setup into one that is small, scoped and logged. For Cursor users it addresses a familiar pattern: the same servers configured in ~/.cursor/mcp.json, a project .cursor/mcp.json, Claude Desktop and app code, each with its own copy of a token. Its description triggers on “one MCP endpoint for Claude Code and Cursor.”

The skill’s quick diagnosis checks both Cursor config locations, greps them for literal tokens, lists which MCP config files are committed to git, and measures the tool surface with the MCP Inspector CLI at “roughly 1 token per 4 characters of JSON.” Its heuristic is blunt: “past roughly 30 to 40 tools visible at once, tool selection accuracy usually drops.” It then classifies every tool as read, write, destructive or external side effect, and checks approval paths, including “Cursor auto-run lists.”

The practices that follow are ordered by impact: choose a topology (direct stdio is fine for one developer and one or two local servers; a gateway once a team shares servers or uses several clients), enforce a budget of “5 to 20 tools per agent task,” name tools verb_noun with narrow arguments, give every identity its own credential, require approval for destructive tools in code, treat tool results as untrusted, move credentials off laptops, and log every call.

For the gateway step, the skill registers servers once on Bifrost and gives each person a virtual key. In Cursor, that replaces several server entries with one:

{
  "mcpServers": {
    "bifrost": {
      "url": "https://bifrost.internal.example.com/mcp",
      "headers": { "Authorization": "Bearer ${env:BIFROST_VK}" }
    }
  }
}

The ${env:...} syntax is Cursor’s config interpolation, which resolves variables in url and headers, so the key stays out of a committed .cursor/mcp.json. On the gateway side, a key sees only the tools listed in its mcp_configs; with no list, Bifrost’s docs say “no MCP tools are available.” Request headers can narrow that set but never widen it.

Two Cursor-specific notes from the skill are easy to miss. First, approvals stay with Cursor: when a host runs the agent loop and connects to /mcp, the gateway’s auto-execute list “is ignored,” and Cursor’s own tool approval and Run Mode decide. Cursor asks before using MCP tools by default. Second, for many servers the skill recommends Code Mode, where Cursor sees a handful of meta-tools instead of every definition; Bifrost’s published benchmark reports input tokens down 92.8% at 508 tools across 16 servers, with pass rates unchanged. The skill’s gotcha: “zero tools from server X” can be correct in Code Mode.

Enterprise Cursor admins have a matching control: the MCP Allowlist approves remote servers by URL pattern, which pairs naturally with a single gateway URL. The Frontier Wire’s MCP guide and its comparison of MCP gateways cover the wider options.

llm-observability-stack: what Cursor and your app send

llm-observability-stack makes every LLM call answerable: what was sent, which provider and model served it, how long it took to the first token and in total, what it cost, who triggered it and whether it was any good. For Cursor teams it covers two things at once: the application being built, and the coding agent’s own traffic when it runs on the team’s keys.

The skill opens with a six-part grep: every LLM call site, existing instrumentation, prompts written to plain logs, streams without usage capture, swallowed errors around model calls, and whether user or feature identity travels with the request. Its core practices define a fixed per-call record (identity, routing, usage, timing, outcome, attribution, gated content), measure time to first token separately from total latency, classify errors by “whose fault,” and keep metric labels low-cardinality: “One label per user ID will take down a Prometheus server.” For agents, it lays out one trace per run using the OpenTelemetry GenAI conventions, with a child span per model call and per tool, and warns that those conventions are still marked “development” and have renamed attributes between releases.

The Cursor-specific piece is routing. Cursor’s bring-your-own-key help page says keys are sent to its backend because “all requests are routed through Cursor’s servers for final prompt building,” and that custom keys “only work with chat models,” while Tab keeps using Cursor’s built-in models. The governance skill’s Cursor notes follow from that: a gateway behind Cursor’s Override OpenAI Base URL must be publicly reachable over HTTPS, because Cursor’s backend makes the call, and requests to Cursor’s own hosted models never reach it. Bifrost’s Cursor guide documents the /cursor path. Once traffic does flow through, the observability skill’s dashboard reference includes a panel for “traffic by calling client (Claude Code, Cursor, API, …).”

Its sampling advice is worth adopting regardless of tooling: metrics at 100%, metadata at 100% if storage allows, and for content, keep every error, slow request, fallback and negative-feedback trace. The Frontier Wire’s review of agent observability tools compares backends that consume these spans.

agent-skills-for-teams: keeping Cursor skills from drifting

agent-skills-for-teams handles the problem that Cursor’s generous discovery creates: with six skill folders read on every machine, the same skill tends to exist in several copies. Its description triggers on “SKILL.md files copy-pasted or drifting across repos” and “our agents behave differently than last week.”

The quick diagnosis finds every SKILL.md, prints name and content hash side by side to expose drift, sizes each body, lists executable scripts inside skill folders, and checks personal folders including ~/.cursor/skills. The bundled scripts/lint_skills.py checks spec rules (name format, name matching the folder, description length), weak descriptions, oversized bodies, broken relative links, missing metadata.version, same-name drift, and risky script patterns such as piping a download into a shell. In the October 28 test, it scanned the six installed skills and reported “0 error(s), 0 warning(s).”

The rest is process: one canonical source per skill, SemVer in metadata.version with a changelog, releases from tags rather than main, CODEOWNERS on the skills folder, a trigger eval of about 20 prompts run three times each, and a documented rollback per distribution model. For Cursor, its warning against keeping a team skill and a personal skill with the same name is practical: which one wins “is harness-specific.”

The other three, briefly

ai-coding-agent-governance plans a governed rollout of Cursor, Claude Code, Codex and others: per-developer gateway keys with daily and monthly budgets, model allowlists, central MCP and log retention. Its Cursor notes cover the public-URL requirement, the fact that the base URL override is “global to all OpenAI-compatible models in Cursor,” and the advice to assign tool-calling models to Agent. The Frontier Wire’s guide to AI gateways for Claude Code, Codex and Cursor covers the same ground; the Codex skills guide covers this skill in depth.

llm-cost-reduction measures cost per feature before changing anything, then right-sizes models with an eval set, caps output and agent loops, fixes prompt-cache prefixes, adds exact and semantic response caching, and moves offline work to batch APIs.

secure-llm-apps audits an LLM feature against the OWASP LLM Top 10: keys in client bundles, indirect prompt injection, over-broad tools, PII sent to providers, model output in SQL or HTML, unbounded spend and prompts in logs. Its MCP section complements the MCP skill: “Tool descriptions are prompt input.” See also The Frontier Wire’s MCP security tools comparison.

Install the skills for Cursor

Each repository holds one skill at its root. Preview with --list, then install for Cursor:

npx skills add build-with-ai-hq/mcp-gateway-best-practices --list

# The three most relevant to Cursor users
npx skills add build-with-ai-hq/mcp-gateway-best-practices -a cursor
npx skills add build-with-ai-hq/llm-observability-stack -a cursor
npx skills add build-with-ai-hq/agent-skills-for-teams -a cursor

# The rest of the set
npx skills add build-with-ai-hq/ai-coding-agent-governance -a cursor
npx skills add build-with-ai-hq/llm-cost-reduction -a cursor
npx skills add build-with-ai-hq/secure-llm-apps -a cursor

# Personal install that can sync to Cloud Agents, no prompts
npx skills add build-with-ai-hq/mcp-gateway-best-practices -a cursor -g -y

npx skills list     # confirm Cursor is listed for each
npx skills update   # upgrade deliberately

Add -a codex -a claude-code to share the same .agents/skills copy with teammates on other agents. Then open Customize → Skills to confirm Cursor sees them, and try one of the prompts above without /. The explainer on npx skills and skills.sh covers the CLI in detail, and MCP best practices expands on the MCP skill’s topics.

Limits worth knowing

Skills run with the agent’s permissions. A scripts/ folder is code that Cursor’s agent may execute, and the CLI’s warning applies to every third-party skill: read every file before installing, pin it with the lockfile, and re-read on update. The agent-skills-for-teams review checklist (no curl | sh, no sudo, no reads of credential files, every network call documented) is a reasonable gate.

Skills are guidance, not enforcement. Cursor says the same of rules. The controls that hold are elsewhere: Cursor’s MCP Allowlist and tool approval, enforced Team Rules, and a gateway that rejects a tool or model a key does not allow.

The six skills are new: the organization was created in October 2026 and each skill is at version 1.0.0. The test install confirmed that they install into Cursor’s path, are listed by the CLI, and pass their own linter with no errors or warnings. It did not measure how often Cursor’s agent selects them unprompted, or their effect on a real codebase. Teams should run a trigger eval before relying on automatic invocation, and consider disable-model-invocation: true for any skill whose steps change infrastructure.

The Frontier Wire’s take

Cursor reads skills from eight locations, which makes adoption easy and drift likely. The decision that matters is placement: AGENTS.md for facts every session needs, rules for file-scoped conventions and enforced team policy, skills for procedures with scripts and references that should cost nothing until used. For Cursor teams building LLM applications, the MCP skill is the one to install first, because tool sprawl in mcp.json is where most Cursor setups lose both context and control: npx skills add build-with-ai-hq/mcp-gateway-best-practices -a cursor.