Skip to content
agents.cli

Skills

What a skill is

Section titled “What a skill is”

A skill is a folder you drop into your project (or your home directory) containing a SKILL.md file. The frontmatter describes when the skill should fire — a name, a one-line description, a “use this when…” hint. The body is whatever the agent needs to actually do the thing: a checklist, a procedure, domain knowledge, a workflow.

The agent reads every skill’s description at session start, but only loads a skill’s body when it decides the description matches what you just asked for. So a skill is cheap to keep around — it costs almost no context until the moment it’s relevant.

Why you’d want one

Section titled “Why you’d want one”

It’s the fourth time this week. You’re reviewing a PR and you paste the same three sentences into the agent: “check the migration is reversible, confirm the feature flag is wired, make sure the integration test hits the real DB and not a mock.” You wrote it down once in a Notion doc. You wrote it again in a comment on your dotfiles. You’ve now typed it into three separate sessions because you keep forgetting where you saved it.

The instructions aren’t the problem. Reaching them at the right moment is the problem. That’s the gap skills exist to close: write the instructions once, attach a description that tells the model when to pull them in, and from then on the knowledge shows up the moment the situation does — without you remembering it exists.

Real-world examples of what teams put in skills:

  • A release checklist — every step of cutting a version, in order, with the exact commands. Fires when you say “let’s ship.”
  • A library cheat-sheet — “when working with our internal flux-db SDK, here’s the gotchas, the right patterns, the deprecated APIs to avoid.” Fires when the model touches that import.
  • An incident runbook — “when prod is down, here’s the diagnostic order, the dashboards to check, the rollback procedure.” Fires when you paste a stack trace.
  • A style guide — “how we write commit messages, name PRs, structure ADRs.” Fires when the model is drafting one.
  • A domain-specific procedure — “how we model multi-tenant data in this codebase,” “how we handle timezones,” “how we write tests for the payments module.” Fires when the model is about to do that work.

The pattern: anything you’ve explained more than twice, anything that lives in a Notion doc nobody opens, anything where the failure mode is “the model didn’t know we do it this way here.” Skills turn institutional knowledge into something the agent reaches for on its own.

Why this and not…

Section titled “Why this and not…”

This is the part that trips people up. Skills overlap with several other primitives. Here’s how to decide:

You want to…Reach forNot
Run a fixed sequence of commands you’ll type by nameSlash commandSkill
Encode “how we do X here” as knowledge the model uses contextually, without you typing a commandSkillSlash command
Bundle a long, multi-file procedure with helper scripts and reference docsSkillSlash command (too thin)
Isolate a side-quest (research, audit, search) into its own context windowSubagentSkill
Block, gate, or rewrite tool calls deterministicallyHookSkill
Persist facts across every session in this repoRulesSkill
Add a new data source or external tool (Jira, Postgres, Figma)MCP serverSkill

The defining trait of a skill: the model decides when to use it, based on a description you wrote. A slash command waits for you to type its name. A hook fires on an event. A skill activates on intent.

How it works in each tool

Section titled “How it works in each tool”

Locations (precedence: managed > user > project):

  • .claude/skills/<name>/SKILL.md — project
  • ~/.claude/skills/<name>/SKILL.md — user
  • Plugin-bundled skills (namespaced as /plugin:name)

Frontmatter fields:

---
name: deploy
description: Run the team's deploy checklist.
disable-model-invocation: false  # if true, only invokable via /<name>
context: fork                    # optional: run in an isolated subagent
---

Loading model:

  • Skill descriptions load at session start so Claude knows what’s available.
  • Full skill body loads on invocation (manual /<name> or model-decided).
  • With disable-model-invocation: true, the skill is invisible until you type /<name> — useful for skills with side effects.

In subagents: a subagent’s skills: frontmatter field preloads skills into its context — different from on-demand loading in the main session.

The cross-tool standard

Section titled “The cross-tool standard”

In late 2025, Anthropic published Agent Skills as an open specification, and within days OpenAI shipped support in Codex CLI; Cursor and Copilot followed in their own 2026 releases (both explicitly position the format as wire-compatible with the Claude Code spec, and both fall back to .claude/skills/ paths). This is the unusual part of skills as a primitive: a skill you write today is largely portable across tools. A SKILL.md plus its supporting files works in Claude Code, Codex, Cursor, and Copilot with no changes to the body, and opencode reads the Claude Code and Codex skill directories directly. Tool-specific frontmatter keys (Claude’s disable-model-invocation, context: fork) don’t cross-map everywhere, but the core shape — frontmatter name + description, Markdown body, optional bundled scripts/assets — is shared.

That portability is why teams converging on multiple coding agents tend to push knowledge into skills rather than slash commands or per-tool config — it’s the one extension format that survives the choice of CLI.

Cross-tool comparison

Section titled “Cross-tool comparison”
AspectClaude CodeCodexopencodeCursorCopilot
FormatSKILL.md + assetsSKILL.md + assetsSKILL.md + assets (narrower frontmatter)SKILL.md + assetsSKILL.md + assets
Cross-tool portableYes (to Codex / opencode)Yes (to Claude Code / opencode)Yes (reads .claude/skills/ and .agents/skills/ natively; non-opencode frontmatter ignored)Yes (reads .claude/skills/, .codex/skills/, .agents/skills/)Yes (reads .claude/skills/, .agents/skills/)
Project path.claude/skills/.agents/skills/.opencode/skills/ (+ reads .claude/, .agents/).cursor/skills/ (+ reads .agents/, .claude/, .codex/).github/skills/ (+ reads .claude/, .agents/)
Invocation/<name>/skills, $<skill>Built-in skill tool, model-selected/skill-name, @skill-name, or auto/ menu, or auto
Model auto-loadsYes (by description)Yes (by description)Yes (by description)Yes (by description)Yes (by description)
Can be hidden from modeldisable-model-invocation: trueagents/openai.yaml → policy.allow_implicit_invocation: false—disable-model-invocation: truedisable-model-invocation: true
Subagent access controlskills: field preloads[[skills.config]] in agent TOML (note: enable/disable overrides currently buggy — openai/codex#14161)permission.skill rules per agent gate which skills are visible——

Name collisions

Section titled “Name collisions”
  • Don’t confuse a skill (reusable content bundle) with a subagent (isolated worker). They can combine — a skill can run inside a forked subagent context via context: fork in Claude Code — but they solve different problems. See subagents.
  • “Skills” in Claude Code overlap almost completely with slash commands; in Codex and opencode they’re distinct primitives.