What are Agent Skills?

Agent Skills are an open format for reusable instructions: a folder holding a SKILL.md whose name and description the agent always sees, and whose body loads only when the task matches. Claude Code, Codex and Cursor all read them, and the skills CLI installs one across agents with npx skills add OWNER/REPO.

Last updated
By
Published
In Polish
Agent Skills
First set up at
All levels, free guide
Also searched as
skills, SKILL.md, skills.sh

$59.99 once for 12 months of access. Nothing renews on its own. 30-day refund on a first purchase.

On this page Why it mattersSkill, MCP server or pluginWhere each agent reads skillsHow each tool does itQuestions

Why it matters.

A skill writes a procedure down once, so a fresh session and a teammate on another agent follow the same steps instead of whatever you explained last Monday. Until it fires it costs a few dozen tokens, because the agent sees only the name and description. Skills steer the model rather than enforce, so a rule that must hold belongs in a hook.

Skill, MCP server or plugin

A skill is instructions, not a live connection: it holds no credentials or server of its own.

What a skill, an MCP server and a plugin give the agent, and when to choose each
LayerWhat it gives the agentChoose it when
Skill A procedure or convention The agent should follow a practice: TDD, a release checklist
MCP server Live tools and data The agent must read or change external state: PRs, tickets, a database
Plugin A bundle of skills, commands, subagents, hooks and MCP servers You want a vendor’s skills and tools wired together, or a hook that starts a method

The format is an open standard since 2025-12-18: a skill-name/SKILL.md folder whose frontmatter name is at most 64 characters and whose description at most 1,024. The specification’s showcase listed 46 compatible clients on 2026-09-26. Source: Agent Skills overview, 2026-09-26.

Where each agent reads skills

The agents read different directories, so the skills CLI writes one canonical copy in .agents/skills/ and symlinks it into .claude/skills/ for Claude Code.

Skill directories, invocation and built-in skills in Claude Code, Codex and Cursor
WhereClaude CodeCodexCursor
Project skills .claude/skills/<name>/, also in parent directories .agents/skills/<name>/, from the working directory up to the repo root .agents/skills/, .cursor/skills/, .claude/skills/ and .codex/skills/
Personal skills ~/.claude/skills/ ~/.agents/skills/ per OpenAI’s docs; npx skills add -g writes ~/.codex/skills/ ~/.cursor/skills/, ~/.agents/skills/ (plus the .claude/.codex compatibility paths)
Invoke by name /<name>; plugin skills are /<plugin>:<skill> $<name>; /skills lists them Name it in the prompt
Built in /code-review, /simplify, /verify, /run, /batch, /loop (turn off with disableBundledSkills) imagegen, openai-docs, review-agent, skill-creator, skill-installer (0.162.1; plugin-creator was removed from the bundle in 0.159.0) /loop

Checked on 2026-09-26 against the Claude Code 2.1.283 docs and the codex-cli 0.157.1 binary. The Codex personal directory comes from vendor documentation (secondary, not re-checked on 2026-09-26). The Cursor paths were read in Cursor’s skills docs on 2026-10-12. Source: Agent Skills overview, 2026-09-26.

How each tool does it.

Cursor, Claude Code and Codex each name this their own way. Each note carries the date it was checked.

Cursor

Loads skills too; npx skills add OWNER/REPO -a cursor installs them into .agents/skills/.

Cursor’s docs list .agents/skills/ and .cursor/skills/ as project locations and ~/.agents/skills/ and ~/.cursor/skills/ as home-directory ones, and for compatibility Cursor also loads .claude/skills/ and .codex/skills/ (checked 2026-10-12). Ask Cursor’s agent which skills it can see before you rely on one.

Top practice skills guide, 2026-10-12

Claude Code

Reads project skills from .claude/skills/<name>/ and invokes them as /<name>; the bundled ones include /code-review, /simplify, /batch and /loop.

A skill that comes from a plugin is invoked as /<plugin>:<skill>, and the disableBundledSkills setting turns the bundled ones off.

Agent Skills overview, Claude Code 2.1.283, 2026-09-26

Codex

Reads project skills from .agents/skills/<name>/, from the working directory up to the repo root; invoke one with $<name>, and /skills lists them.

The bundled sample skills in 0.162.1 are imagegen, openai-docs, review-agent, skill-creator and skill-installer; plugin-creator was removed from the bundle in 0.159.0. OpenAI’s docs put personal skills in ~/.agents/skills/, while npx skills add -g writes ~/.codex/skills/.

Agent Skills overview, Codex CLI 0.162.1, 2026-10-12

Questions about Agent Skills.

How do I install an Agent Skill?

With the skills CLI: npx skills add OWNER/REPO installs from a GitHub repository, and -a claude-code -a codex -a cursor names the agents. The CLI keeps one copy in .agents/skills/ and symlinks it into .claude/skills/. Read the SKILL.md and any bundled scripts first, because skills run with the agent’s full permissions.

Should I write a skill or an MCP server?

A skill, when the agent should follow a practice such as a release checklist or TDD. An MCP server, when it must read or change external state such as pull requests, tickets or a database. A plugin bundles skills, commands, subagents, hooks and MCP servers when you want them wired together.

Where do Agent Skills come from?

From GitHub repositories: npx skills add OWNER/REPO reads the repository, and npx skills find searches the skills.sh index. Copycat repositories reuse popular names and install counts measure attention, not quality, so install from the canonical owner and pin a tag or commit with OWNER/REPO#ref.

How do I keep a team on the same skills?

Pin each source with OWNER/REPO#ref, commit the skill folders and skills-lock.json together, and add a CI step that restores from the lockfile and fails on git diff --exit-code. An unpinned lockfile is a manifest, not a pin: a restore fetches whatever is upstream that day.

Does this page answer your questions?

One tap, no sign-in.

not at all fully

Read the guides in the same words.

Open every guide with the Toolkit. Each term is defined once here, and the guides use it the same way.

$59.99 once for 12 months of access. Nothing renews on its own. 30-day refund on a first purchase.