Agent skills
Published October 6, 2026 · by the AQ team
Agent skills are folders of instructions that an AI agent discovers by description and loads only when a task needs them. Each skill is a directory containing a SKILL.md file: YAML frontmatter with a name and a description, then a Markdown body of instructions, optionally alongside scripts, reference documents, and templates. As of October 2026 the same format is loaded by Claude Code, Codex, Cursor, OpenCode, Gemini CLI, GitHub Copilot, and dozens of other agents, which makes a skill the most portable way to teach a coding agent a procedure: how your deploys work, how to review a migration, what your release notes look like.
Where the format came from
Anthropic shipped Agent Skills across Claude Code, the Claude apps, and its API in October 2025, with an engineering post (October 16, 2025) describing the design. On December 18, 2025 Anthropic released the format as an open standard at agentskills.io, with a specification, a reference validation library, and a public repository of example skills. Adoption moved fast: as of October 2026 the standard's own client showcase lists OpenAI (Codex and ChatGPT), Microsoft (VS Code and GitHub Copilot), Google's Gemini CLI, Cursor, OpenCode, JetBrains Junie, Amp, Goose, Factory, OpenHands, Roo Code, Kiro, and many more. The trajectory mirrors the Model Context Protocol: a format one lab published that became ecosystem infrastructure because every other vendor's users asked for it.
What a SKILL.md file contains
The specification is deliberately small. A skill is a directory whose name matches the required name field (1 to 64 characters, lowercase letters, numbers, and single hyphens). The required description field (up to 1024 characters) says what the skill does and when to use it; it is the only text the agent sees before deciding to load the skill, so it carries the trigger keywords. Optional fields are license, compatibility (environment requirements, up to 500 characters), metadata (free-form string key-value pairs), and the experimental allowed-tools (tools the skill is pre-approved to use). Everything after the frontmatter is plain Markdown instructions.
deploy-staging/
SKILL.md (required: frontmatter + instructions)
scripts/ (optional: executable code)
references/ (optional: docs loaded on demand)
assets/ (optional: templates, data files)The load discipline is called progressive disclosure, and it is the reason skills scale where giant instruction files do not. At startup the agent loads only each skill's name and description (roughly 100 tokens per skill). When a task matches a description, the agent reads the full SKILL.md body into context (the spec recommends staying under 5000 tokens and 500 lines). Bundled scripts and reference files load only if the work actually calls for them. Fifty installed skills cost almost nothing until one is used.
Which coding agents load skills, as of October 2026
| Tool | Project skills (committed to the repo) | Personal skills | Invocation |
|---|---|---|---|
| Claude Code | .claude/skills, including nested folders in monorepo subdirectories, plus plugin and managed enterprise locations | ~/.claude/skills, and skills enabled on a claude.ai account | Automatic from the description, by typing the skill name as a slash command, or by the agent's own Skill tool |
| Codex | .agents/skills | ~/.codex/skills (where OpenAI also ships system skills); available in the CLI, IDE extension, and Codex app | Automatic from the description, or explicit mention (a dollar-sign mention or the /skills command) |
| Cursor | .agents/skills or .cursor/skills, anywhere in the repo including monorepo subdirectories | ~/.agents/skills and ~/.cursor/skills | Automatic from the description; a built-in /create-skill scaffolds new ones |
| OpenCode | .opencode/skills, plus compatibility reads of .claude/skills and .agents/skills | ~/.config/opencode/skills, plus ~/.claude/skills and ~/.agents/skills | Automatic from the description |
Two details matter in practice. First, discovery locations differ even though the file format does not; OpenCode and Cursor reading the .claude and .agents trees means a single committed directory can serve several tools, and the team-sharing patterns exist to close the remaining gaps. Second, vendors extend the core spec differently: Claude Code adds fields for disabling automatic invocation, forking a skill into a subagent, binding hooks, and overriding the model, and those extensions do not travel. A skill that sticks to the six spec fields runs everywhere.
How skills differ from MCP servers, prompts, subagents, and memory files
Each of these extends an agent, and they are easy to conflate. One-sentence definitions first: an MCP server is a running process that gives an agent tools and data over the Model Context Protocol; a prompt (or slash command) is text you send once; a subagent is a separate agent instance with its own context window that works on a delegated task; a memory file (CLAUDE.md or AGENTS.md) is project instruction text loaded at the start of every session.
| Topic | What it is | When it loads | Best at |
|---|---|---|---|
| Skill | A folder of instructions plus optional scripts | On demand, when the task matches the description | Procedures and domain knowledge |
| MCP server | A process exposing tools over a protocol | Tool definitions load up front, every session | Connecting external systems (issue trackers, databases, browsers) |
| Prompt / slash command | Text sent to the agent once | When you send it | One-off instructions |
| Subagent | A separate agent with its own context | When spawned | Isolating a subtask's context from the main thread |
| Memory file | Project instructions (CLAUDE.md, AGENTS.md) | Every session, unconditionally | Facts every task needs: build commands, conventions |
The practical rule that falls out of the table: anything every session needs belongs in the memory file, anything only some tasks need belongs in a skill, and anything that requires reaching a live external system needs an MCP server. Skills and MCP also differ in cost: a large MCP server's tool definitions occupy context in every session whether used or not, while a skill costs its description until invoked. Teams migrating bloated always-on instructions into skills consistently report smaller contexts; Cursor's own docs now recommend skills over always-on rules for exactly this reason.
How a team distributes skills
Three patterns cover nearly every team, in order of preference. Commit project skills to the repository: a skill that encodes codebase knowledge rides along with every clone, gets code review and history, and updates for everyone on the next pull. Keep personal skills (your commit style, your debugging ritual) in a dotfiles repo linked into each tool's personal directory. For organization-wide libraries that span many repositories, use a distribution layer: Claude Code has plugins and marketplaces (a plugin bundles skills, and a marketplace is a git repo teams install from), and other teams run a central skills repo with a bootstrap script. The full comparison, including the multi-tool symlink tricks, is in the team-sharing guide. Anthropic's public skills repository and the skills-ref validator (both linked from agentskills.io) are the reference starting points.
One rule applies regardless of pattern: a skill can tell the agent to run bundled scripts, and those scripts run with the permissions and credentials of whoever runs the agent. Review a third-party skill the way you would review a shell script from the internet, because that is what it can contain.
Where AQ fits
AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. AQ runs the stock CLIs, so skills behave exactly as they do on a laptop: every workspace is an isolated git worktree of your repository, which means skills committed to the repo are present in each workspace's checkout, and whichever CLI a teammate launches there picks them up from its usual paths. Because teammates can open the same workspace and watch the same live session, a skill's effect on an agent's behavior is something the team can actually observe and refine together rather than reconstruct from one person's terminal scrollback.
Frequently asked questions
What is the difference between a skill and CLAUDE.md or AGENTS.md?
Load timing. A memory file like CLAUDE.md or AGENTS.md is read at the start of every session and occupies context for every task, so it should hold only what every task needs. A skill loads on demand: the agent sees its one-line description up front and reads the full instructions only when a task matches. Move anything task-specific (deploy steps, review checklists, report formats) out of the memory file and into a skill.
Do agent skills work with any model?
Skills are plain Markdown read by the harness, not the model, so they work with whatever model the harness runs. The same SKILL.md folder works in Claude Code on Anthropic models, Codex on OpenAI models, and OpenCode or Cursor on anything those tools support. Quality still varies: following multi-step instructions reliably is itself a model capability.
Can a skill run code on my machine?
Yes. A skill can bundle scripts and instruct the agent to execute them, and they run with the permissions and credentials of the user running the agent, subject to the harness's own permission prompts. That is the point (a tested script beats improvised commands) and the risk: treat third-party skills as code, review them before installing, and prefer skills that went through your normal code review by committing them to the repository.
How many skills can I install before they bloat the context?
Many. Under progressive disclosure each installed skill costs roughly 100 tokens (its name and description) until it is actually invoked, so dozens of skills have a smaller footprint than one long always-on instruction file. The practical limit is discovery quality, not context: with hundreds of skills, overlapping descriptions start to confuse selection, so keep descriptions specific about when to use each skill.
Where do I find existing skills to install?
Anthropic's public skills repository (linked from agentskills.io) carries reference and example skills, including the document skills Claude's own products use. OpenAI ships system skills with Codex and documents a curated set. Claude Code installs skill bundles through plugin marketplaces (git repositories teams add with one command), and several community catalogs index thousands more. For team workflows, the usual best source is your own repo: write the skill once, commit it, and it distributes itself.