Agent Skills — vendor extensions reference¶
The Agent Skills open specification defines a small, portable core — two required frontmatter fields (name, description) and a handful of optional ones (license, compatibility, metadata). The Anthropic, GitHub, and OpenAI implementations all read that core identically, which is what makes SKILL.md cross-vendor in the first place. Each vendor then adds its own optional extensions for things the core does not cover — tool allow-listing, picker UI hints, invocation policy, MCP dependencies, execution context isolation. The extensions do not interoperate.
This page is a single reference table of every vendor-specific extension and location convention as of May 2026, with worked examples and portability advice. Use it as the answer sheet when a Skill needs to bend toward a particular host without breaking on the others.
1. The portable core¶
Every Skill, on every vendor, starts with this open-spec frontmatter:
---
name: my-skill # required, kebab-case, ≤64 chars, matches directory name
description: … # required, ≤1024 chars, prose
license: Apache-2.0 # optional, SPDX identifier
compatibility: … # optional, free text
metadata: # optional
author: example-org
version: "1.0"
---
Everything below is additive. Keeping the portable core clean and pushing every vendor-specific field into a clearly-labelled section at the bottom (or into the Codex sidecar) is what lets the same Skill run everywhere without runtime warnings.
2. Anthropic — allowed-tools¶
Anthropic adds one experimental optional frontmatter field that affects Skill behaviour:
| Field | Type | Honoured by | Purpose |
|---|---|---|---|
allowed-tools |
space-separated list of tool names with optional argument patterns | Claude Code CLI (experimental) | Restricts which tools the Skill can call when active |
Example:
---
name: pdf-processing
description: Extracts text and tables from PDFs, fills forms, merges PDFs. Use when the user mentions PDFs.
allowed-tools: Bash(pdftotext:*) Read Write
---
The Claude Code CLI honours this field today and will refuse tool calls outside the allowlist when the Skill is active. The Claude Agent SDK does not yet enforce it; the Claude apps ignore it. Status as of May 2026: experimental; the field name is stable but enforcement is incomplete and may change before GA.
There is no Anthropic-side equivalent of Copilot's disable-model-invocation or Codex's policy.allow_implicit_invocation. If you need the Skill to be user-invoked only, the only available approach is to lean on the user-visible invocation channel (the slash-command surface in Claude Code) and write the description so the model is unlikely to auto-pick it.
2.1 Where Anthropic looks for Skills¶
| Path | Scope | Precedence (high → low) |
|---|---|---|
.claude/skills/<n>/ |
Project | 1 |
~/.claude/skills/<n>/ |
Personal | 2 |
Inside a plugin (.claude-plugin/plugin.json → components.skills) |
Plugin-bundled | 3 |
Skills are exposed through the Agent SDK via ClaudeAgentOptions(skills=[...]) and --skill CLI flags. The Claude apps load them via Settings → Capabilities → Skills, and org-level deployment shipped December 18, 2025.
3. GitHub Copilot — four VS Code extensions¶
VS Code Copilot adds four optional frontmatter fields beyond the open spec, all VS-Code-only and ignored by other hosts:
| Field | Type | Purpose |
|---|---|---|
argument-hint |
string | Hint text shown in the picker when the Skill takes arguments |
user-invocable |
boolean (default true) |
Whether the user can invoke the Skill explicitly via slash command |
disable-model-invocation |
boolean | Force user-only invocation; the model will not auto-select the Skill |
context |
inline or fork |
inline runs the Skill in the parent chat context; fork runs it in an isolated sub-context similar to a sub-agent |
Example:
---
name: deploy-staging
description: Pushes the current branch to the staging cluster, runs smoke tests, and posts a status update.
disable-model-invocation: true
argument-hint: "<branch-name>"
context: fork
---
The context: fork field is interesting because it bridges the gap between Skills and sub-agents — a forked Skill behaves like a short-lived sub-agent in VS Code, with its own tool surface and its own scratch space. inline is the default and matches the behaviour of other hosts.
3.1 Where Copilot looks for Skills¶
| Path | Scope |
|---|---|
.github/skills/<n>/ |
Project, Copilot-native path |
.claude/skills/<n>/ |
Project, interop with Claude |
.agents/skills/<n>/ |
Project, vendor-neutral path |
~/.copilot/skills/<n>/ |
Personal, Copilot-native |
~/.claude/skills/<n>/ |
Personal, interop with Claude |
~/.agents/skills/<n>/ |
Personal, vendor-neutral |
Surface support as of May 2026:
| Surface | Agent Skills support |
|---|---|
| VS Code | GA |
| JetBrains IDEs | Preview |
| GitHub.com (Copilot Chat) | GA |
| Copilot CLI | GA |
| Visual Studio (the IDE) | Not yet (per the April 30, 2026 release notes) |
| Eclipse, Xcode | Not yet |
If your audience uses Visual Studio specifically, plan around the gap — Skills will not load in that IDE until Microsoft ships parity.
3.2 Don't confuse Skills with Skillsets or Custom Agents¶
- Copilot Skillsets (Nov 19, 2024) — an architecture for building Copilot Extensions (GitHub Apps) with up to 5 HTTP endpoints. Not a
SKILL.mdanalogue. Author is the GitHub App owner; distribution is via the GitHub Marketplace. - Copilot Custom Agents (
.github/agents/AGENT-NAME.md) — user-defined chat personas with their own system prompt and tool allowlist. Invoked by explicit@<name>in chat. Closer to Claude sub-agents than to Skills.
Both share root words with Agent Skills and create lasting confusion in vendor documentation. The cross-vendor SKILL.md analogue is Copilot Agent Skills, documented at code.visualstudio.com/docs/copilot/customization/agent-skills.
4. OpenAI Codex — the agents/openai.yaml sidecar¶
Codex's extensions live in an optional sidecar file rather than in SKILL.md frontmatter. The sidecar sits at agents/openai.yaml inside the Skill directory:
incident-response/
├── SKILL.md # open-spec file (name + description + body)
├── agents/
│ └── openai.yaml # Codex-specific extensions
├── scripts/
│ └── triage.sh
└── references/
└── playbook.md
The sidecar's fields:
| Field | Type | Purpose |
|---|---|---|
interface.display_name |
string | Human-readable label shown in the Codex picker UI |
interface.icon |
string | Icon identifier or path |
interface.group |
string | Grouping label for organising Skills in the picker |
policy.allow_implicit_invocation |
boolean | If false, the model cannot auto-trigger this Skill; the user must invoke it explicitly |
dependencies.mcp_servers |
list of strings | Named MCP servers this Skill needs at runtime; Codex will fail-fast if any are missing |
Example:
# agents/openai.yaml
interface:
display_name: "Incident response"
icon: "alert"
group: "On-call"
policy:
allow_implicit_invocation: false
dependencies:
mcp_servers:
- pagerduty
- github
The sidecar is purely additive — Claude and Copilot ignore it; Codex picks it up at session start. Putting all vendor-specific configuration in a sidecar rather than in SKILL.md frontmatter is, on balance, the cleanest design of the three: the portable file stays untouched and the extensions live in their own namespace.
4.1 Where Codex looks for Skills¶
| Location | Scope |
|---|---|
$CWD/.agents/skills/<n>/, walking up to repo root |
Project (closer wins) |
$HOME/.agents/skills/<n>/ |
Personal |
/etc/codex/skills/<n>/ |
System (machine-wide) |
| System-bundled Skills | Shipped with Codex itself |
Codex documents a session-start budget for the level-1 Skills list: roughly 2% of the model's context window or 8,000 characters, whichever is smaller. Past that ceiling, some Skills' level-1 metadata is not visible to the model and they will never auto-trigger. The design pressure is identical to Claude and Copilot but Codex is the only vendor that publishes a numeric cap; treat 8,000 characters as a portable safety limit even on hosts where it isn't enforced.
4.2 Custom Prompts (deprecated)¶
Codex previously distributed user extensions as ~/.codex/prompts/*.md Custom Prompts, invoked as /prompt-name. The Custom Prompts docs page is now officially marked deprecated in favor of Skills. Existing files keep working — no end-of-life date is documented — but new authoring should target Skills. Migration is mechanical: take the Markdown body of the prompt, add YAML frontmatter (name, description), and move the file under ~/.agents/skills/<name>/SKILL.md.
5. Three-vendor field comparison¶
For any Skill that needs vendor-specific tuning, this is the field-by-field cheat sheet:
| Concern | Anthropic | GitHub Copilot | OpenAI Codex |
|---|---|---|---|
| Restrict tool surface | allowed-tools (experimental, CLI-only) |
No equivalent at Skill level; use Custom Agent tools field |
policy.allow_implicit_invocation: false (locks Skill behind explicit user invocation) |
| Force user-only invocation | Not exposed | disable-model-invocation: true |
policy.allow_implicit_invocation: false |
| Picker UI hints | Not exposed | argument-hint |
interface.display_name, interface.icon, interface.group |
| Execution context isolation | Sub-agents are a separate surface | context: fork (inline / fork) |
Not exposed at Skill level |
| MCP server dependencies | Declared at plugin manifest level (mcpServers) |
Declared in .vscode/mcp.json / workspace settings, not in Skill |
dependencies.mcp_servers in sidecar |
| Session-start budget | Not documented (token pressure applies) | Not documented (token pressure applies) | ~2% context or 8,000 chars |
The three security knobs — allowed-tools, disable-model-invocation, policy.allow_implicit_invocation — are partially-overlapping intent expressed in three different fields. There is no portable way today to say "this Skill must be user-invoked only" or "this Skill may only call these tools" that works across all three vendors. The Agent Skills spec community is openly discussing convergence here, but for May 2026 the portable advice is: write the Skill to need the minimum tools possible, declare each vendor's knob in its respective field, and document the intent in plain prose in the Skill body so future authors can re-pin if the spec moves.
6. Three-vendor location matrix¶
For a Skill that needs to live at a path readable by more than one host, this is the working set:
| Path | Anthropic | Copilot | Codex |
|---|---|---|---|
.claude/skills/ |
✅ project | ✅ project | ❌ |
.github/skills/ |
❌ | ✅ project | ❌ |
.agents/skills/ |
❌ | ✅ project | ✅ project |
~/.claude/skills/ |
✅ personal | ✅ personal | ❌ |
~/.copilot/skills/ |
❌ | ✅ personal | ❌ |
~/.agents/skills/ |
❌ | ✅ personal | ✅ personal |
/etc/codex/skills/ |
❌ | ❌ | ✅ system |
Practical conclusion: the path read by two hosts is .claude/skills/ (Anthropic + Copilot) and the path read by two hosts including Codex is .agents/skills/ (Copilot + Codex). There is no single path that all three read natively. The pragmatic options are:
- Pick one path and symlink from the others. Adds a one-line setup step but keeps the Skill in a single source-of-truth location.
- Pick one host as primary and let the others read from one of the secondary paths.
- Use
.agents/skills/as the canonical path for new cross-vendor authoring; this is the path most likely to gain native Anthropic support as the spec matures.
7. Codex AGENTS.md — adjacent but different¶
OpenAI Codex also reads AGENTS.md, an always-loaded file (walking from the repo root down to $CWD) that establishes standing project context: setup commands, code style, testing instructions, "don't touch" lists. It is not a Skill. The difference:
| File | Loading | Purpose |
|---|---|---|
AGENTS.md |
Always loaded at session start | Standing context — "what this project is, how to behave in it" |
SKILL.md |
Loaded only when the model decides it applies | On-demand recipe — "how to do a specific job" |
AGENTS.md is an open spec governed under AAIF and is now read by Claude Code, Codex, Cursor, Gemini CLI, Windsurf, Aider, and GitHub Copilot's coding agent, among others — significantly broader cross-vendor footprint than either CLAUDE.md or copilot-instructions.md. A useful authoring rule: project-wide conventions go in AGENTS.md; task-specific procedures go in Skills.
8. MCP — same protocol, different config files¶
All three vendors are MCP clients of the same protocol (donated by Anthropic to the AAIF on December 9, 2025). The config files are different:
| Vendor | MCP config | Transports |
|---|---|---|
| Anthropic | .mcp.json (project) or claude_desktop_config.json |
STDIO, Streamable HTTP |
| GitHub Copilot | .vscode/mcp.json or workspace settings |
STDIO, Streamable HTTP |
| OpenAI Codex | ~/.codex/config.toml [mcp_servers.*] block |
STDIO, Streamable HTTP |
For a cross-vendor Skill that depends on MCP, the durable approach is: declare the dependency at the Skill level (Codex sidecar field; Skill body prose elsewhere), and document the per-vendor config snippet in a references/MCP.md that the body cites.
9. Worked portable Skill¶
A Skill written to be maximally portable across the three vendors looks like this:
---
name: triage-bug
description: Triages a bug report into a Jira ticket using this team's severity and label conventions. Use when the user reports a bug, asks to "log this", says "open a ticket", or shares a stack trace they want filed.
license: Apache-2.0
metadata:
author: example-org
version: "1.0"
---
# Triage bug
## Steps
1. Read the user's report. Identify reproduction steps, affected platform, and impact.
2. Apply the severity rules in `references/severity.md`.
3. Apply the label rules in `references/labels.md`.
4. Create the Jira ticket via the configured MCP server (`jira` — see `references/mcp.md` for setup).
5. Reply to the user with the ticket key and a one-line summary of severity + labels.
## Decision rules
- If reproduction steps are missing, ask the user once for them, then proceed.
- If the affected platform is unclear, default to `unknown` and label `needs-triage`.
- If the MCP `jira` server is unreachable, surface the error verbatim — do not invent a ticket key.
## Examples
- "P2 / cart fails on Safari for users with >50 line items" → ticket in `CART`, severity P2, labels `safari`, `large-cart`.
- "the build is red on main" → ticket in `INFRA`, severity P1, label `ci`.
And then, separately, a agents/openai.yaml sidecar for Codex:
interface:
display_name: "Triage bug"
icon: "bug"
group: "Engineering"
policy:
allow_implicit_invocation: true
dependencies:
mcp_servers:
- jira
That Skill loads cleanly on Claude (the sidecar is ignored), on Copilot (the sidecar is ignored), and on Codex (the sidecar takes effect). Adding vendor-specific frontmatter fields — allowed-tools for Claude, disable-model-invocation or context for Copilot — is fine as long as they sit in their own clearly-labelled section and the portable core stays clean.
10. Portability rules of thumb¶
- Pin the portable core. Use only the spec's required and optional fields in the main frontmatter block.
- Use a labelled vendor-extensions block at the bottom of
SKILL.mdfor fields a single host reads. - Prefer the sidecar pattern (Codex's
agents/openai.yaml) over inline frontmatter when the spec supports it — it keeps the portable file untouched. - Path: pick
.agents/skills/for cross-vendor projects; fall back to.claude/skills/for Anthropic + Copilot, and to.codex/skills/(or~/.agents/skills/) for Codex-only. - Mind the surface coverage gaps. Visual Studio doesn't load Skills yet; JetBrains is in preview; Eclipse and Xcode are not on the roadmap as of May 2026.
- Watch the spec.
agentskills.iois the authoritative source; security-field convergence is a likely near-term change.
Changelog¶
- 2026-05-11 — Page created from cross-vendor deep-research synthesis (Anthropic, Microsoft VS Code, GitHub, OpenAI Codex primary docs). Confidence 85.