Agent Skills is an open format for giving AI agents new capabilities: a skill is a folder with a SKILL.md file (a name, a description and instructions) plus optional scripts, references and assets. Anthropic created it, published it as an open standard at agentskills.io in December 2025, and donated it to the Linux Foundation's Agentic AI Foundation in October 2026. The same skill folder now works in Claude Code, OpenAI Codex, Gemini CLI, Cursor, GitHub Copilot and many other agents.
This article explains the specification, which tools support it (only those we could confirm in their own docs), what actually stays portable between agents, where skills are published, the security risks of installing other people's skills, and how to share skills inside a team without making them public.
What the Agent Skills standard is
Anthropic introduced skills for Claude in October 2025. On December 18, 2025 it released the format as an open specification with its own site and GitHub organization (SiliconANGLE coverage). On October 22, 2026, Anthropic donated Agent Skills to the Agentic AI Foundation (AAIF), the Linux Foundation body that already hosts MCP and AGENTS.md. The donation covered the name and logo, the GitHub organization and the agentskills.io domain. The Linux Foundation's press release adds that the spec is licensed under Apache 2.0 and CC BY 4.0 and will be governed by a multi-company technical steering committee.
In that announcement Anthropic says more than 70 agent platforms have integrated the format, including ChatGPT, Cursor, GitHub Copilot and VS Code. The spec itself is developed in the open at github.com/agentskills/agentskills.
The idea is simple. Agents are capable but lack your context: your deploy steps, your report format, your company's review checklist. A skill packages that know-how into a version-controlled folder the agent loads only when a task needs it.
Which agents support Agent Skills
The agentskills.io client showcase lists more than 40 products, among them Goose, OpenCode, OpenHands, Junie, Kiro, Amp, Factory, Roo Code and Databricks. The table below covers the five most common coding agents, with the folders each one reads according to its own documentation:
| Agent | Project skills | Personal skills | Explicit invocation |
|---|---|---|---|
| Claude Code | .claude/skills/ | ~/.claude/skills/ | /skill-name |
| OpenAI Codex | .agents/skills/ (from the current directory up to the repo root) | ~/.agents/skills/ | $skill-name or /skills |
| Gemini CLI | .gemini/skills/ or .agents/skills/ | ~/.gemini/skills/ or ~/.agents/skills/ | Activated by the model after a consent prompt |
| Cursor | .agents/skills/, .cursor/skills/ (also reads .claude/skills/, .codex/skills/) | ~/.agents/skills/, ~/.cursor/skills/ | / menu in Agent chat |
| VS Code / GitHub Copilot | .github/skills/ (also reads .claude/skills/, .agents/skills/) | ~/.copilot/skills/ | / menu in chat |
Two trends stand out. First, every one of these agents also picks skills automatically by matching the task against the description. Second, .agents/skills/ is becoming the shared path: Codex uses it natively, Gemini CLI treats it as an alias that takes precedence over its own folder, and Cursor and VS Code read it too. Claude Code still uses .claude/skills/, which Cursor and VS Code read as well. For Codex specifics, see our Codex CLI commands and subagents guide.
The SKILL.md format
The specification is short. A skill is a directory containing at least SKILL.md, which must start with YAML frontmatter:
| Field | Required | Constraint |
|---|---|---|
name | Yes | 1–64 characters, lowercase letters, numbers and hyphens; no leading, trailing or double hyphens; must match the folder name |
description | Yes | 1–1,024 characters; what the skill does and when to use it |
license | No | License name or bundled license file |
compatibility | No | Up to 500 characters of environment requirements |
metadata | No | String-to-string map for anything else (author, version) |
allowed-tools | No | Space-separated pre-approved tools; experimental, support varies |
A minimal, valid skill:
---
name: commit-message
description: Writes Conventional Commits messages from the staged git diff. Use when the user asks to commit, write a commit message, or describe staged changes.
---
# Commit messages
1. Run `git diff --staged`. If it is empty, say nothing is staged and stop.
2. Write: type(scope): imperative summary under 72 characters, then one
short paragraph on why.
3. Allowed types: feat, fix, docs, refactor, test, chore.
4. Show the message and ask before committing.Optional folders follow conventions: scripts/ for executable code, references/ for documentation the agent reads on demand, and assets/ for templates and data. The spec asks you to reference files with relative paths, one level deep from SKILL.md.
Progressive disclosure
Every compliant agent loads skills in three stages. At startup it reads only the name and description (about 100 tokens per skill). When a task matches, it reads the full SKILL.md (the spec recommends under 5,000 tokens and under 500 lines). Scripts and reference files are touched only when the instructions call for them. That is why you can install many skills without filling the context window. We go deeper on writing good ones in Claude Code skills: best practices and examples.
How the same skill works across agents
The format is portable; the extras are not. You can see exactly where the line is with skills-ref, the reference validator in the spec repository (the README notes it is for demonstration, not production). We ran it on two skills: the one above, and a Claude Code skill that uses Claude-specific frontmatter:
$ uvx --from "git+https://github.com/agentskills/agentskills#subdirectory=skills-ref" \
skills-ref validate ./commit-message
Valid skill: commit-message
$ skills-ref validate ./pr-summary
Validation failed for pr-summary:
- Unexpected fields in frontmatter: disable-model-invocation. Only ['allowed-tools',
'compatibility', 'description', 'license', 'metadata', 'name'] are allowed.Claude Code accepts disable-model-invocation, and so do Cursor and VS Code, but it is not part of the core spec, and an agent that ignores it may trigger a skill you meant to be manual-only. The same applies to Claude Code's !`command` context injection and context: fork, or Codex's optional agents/openai.yaml. Rules of thumb for skills you want to share across agents:
- Stick to the six spec fields, and make sure
namematches the folder. - Put agent-specific behavior in the instructions as plain language ("ask before committing") rather than relying on one client's frontmatter.
- Write scripts in a language any machine running the skill will have, and list dependencies in
compatibility. - Keep paths relative and use forward slashes.
The validator can also print the block an agent puts into its system prompt, which shows how little each skill costs before it is used:
$ skills-ref to-prompt ./commit-message
<available_skills>
<skill>
<name>
commit-message
</name>
<description>
Writes Conventional Commits messages from the staged git diff. Use when the user asks to commit, write a commit message, or describe staged changes.
</description>
<location>
/private/tmp/skilltest/commit-message/SKILL.md
</location>
</skill>
</available_skills>Agent skills on GitHub and in directories
- anthropics/skills, Anthropic's public repository, with over 190,000 GitHub stars as of November 2026. It holds the document skills (docx, pdf, pptx, xlsx, Apache 2.0),
skill-creator,mcp-builderand examples. In Claude Code it installs as a plugin marketplace with/plugin marketplace add anthropics/skills. - OpenAI's curated skills, installed from inside Codex with the built-in
$skill-installer, which per the Codex docs installs "curated skills from openai/skills or other repos". - skills.sh, Vercel's cross-agent directory, with the
npx skills add <owner/repo>installer. - Gemini CLI installs straight from a git URL with
gemini skills install <url>. - Plugin marketplaces for Claude Code, including Anthropic's official
claude-plugins-official, which bundle skills with hooks and MCP servers.
Underneath, nearly all of these are GitHub repositories. That makes publishing easy and also means anyone with a GitHub account can publish something that looks official.
Security: a skill is code you run
Installing a skill is closer to installing software than to reading a prompt. Instructions steer an agent that has shell, file and network access, and bundled scripts run with your user permissions. Anthropic's Agent Skills documentation says to use skills only from trusted sources, warning that "a malicious Skill can direct Claude to call tools or run code in ways that don't match the Skill's stated purpose." VS Code's docs say the same: "Only reuse skills you trust."
This is not theoretical. In February 2026, Snyk reported on an audit that found 341 malicious skills among 2,857 on ClawHub, the registry for the OpenClaw agent, published during a few days in late January. Most used a fake "Prerequisites" section telling users to paste a shell command or download an archive, which installed the Atomic Stealer infostealer. The attack lived in plain Markdown, and the only barrier to publishing was a GitHub account at least a week old.
Practical defenses:
- Read every file before installing:
SKILL.md, scripts and anything they download. Be suspicious of "first install this" steps and of URLs fetched at runtime. - Pin what you reviewed. Install a specific commit or version, and turn off auto-update for third-party sources so the files cannot change after review.
- Keep the agent's permissions tight: approval prompts or a sandbox for shell commands, especially for new skills. Gemini CLI asks for consent on each skill activation; other agents rely on their normal tool permissions.
- Keep secrets out of reach. A skill that convinces an agent to print your environment file has a real payoff. If the agent only ever sees opaque references, as with EnvSave's
es_keys, there is nothing useful to steal. - Scan with tools built for this, such as
snyk mcp-scan, which Snyk recommends for skill and MCP configurations.
Sharing agent skills privately across a team
For skills that encode your company's process, public directories are the wrong place. You have three reasonable options:
- Commit them to the repository (
.claude/skills/or.agents/skills/). Everyone on the project gets them; nobody else does. Works well for project-specific skills. - A private plugin marketplace in a private git repo, if your whole team uses Claude Code.
- One private repo per skill, shared per person, for skills that cross projects or go to people outside the team. That is the model Skylls uses.
Skylls publishes each skill to its own private GitHub repo, tags every version, writes a changelog, and runs a gitleaks secret scan before every push. Access is plain GitHub repo access, so you can share one skill with one client and revoke it later. Because it is the same Agent Skills folder, one install serves several agents:
$ skylls add --help
usage: skylls add [-h] [--from OWNER] [-y] [-g] [-a AGENT] name
-g, --global Use the global (home) skills folder.
-a, --agent AGENT claude, codex, gemini, comma list, or all.| Command | Claude Code | Codex | Gemini CLI |
|---|---|---|---|
skylls add pdf -a all (this project) | ./.claude/skills/pdf/ | ./.agents/skills/pdf/ | ./.gemini/skills/pdf/ |
skylls add pdf -g -a all (global) | ~/.claude/skills/pdf/ | ~/.agents/skills/pdf/ | ~/.gemini/skills/pdf/ |
A global install for several agents keeps one real copy and links the others to it, so an update reaches all three. The publisher's side is skylls push <name> -m "what changed" and skylls share <name> @user; the receiver runs skylls source add <owner> once and skylls pull --update for new versions. The secret scan also helps with the security problem above: what you share with others should never contain your keys.
Agent Skills has become the common way to package what an agent knows how to do. Write to the spec, review what you install, and keep your own skills versioned and shared on purpose. To give every skill its own private repo with versions and a secret scan, try Skylls. If you want help turning your team's processes into skills and agents, get in touch.