BlogUpdated By Minjae Lee, Co-CEO, Trina Inc.

Agent Skills: one SKILL.md, many AI agents

Agent Skills is an open format for giving an AI agent a reusable procedure: a folder with a SKILL.md file in it, plus any scripts, references or templates the procedure needs. [1] Anthropic developed it and released it as an open standard, and the project’s showcase now lists 46 products that read it, among them Claude Code, Claude, ChatGPT and Codex, GitHub Copilot, VS Code, Cursor and Gemini CLI. [1][3] On November 4, 2026, in a change titled “AAIF Donation”, the project adopted a governance document under which it is to become a series of LF Projects, LLC, with a representative to the governing board of the Agentic AI Foundation. [5]

“Write it once, use it in any agent” is the promise. In practice a skill travels well if you know three things: which header fields every tool accepts, where each tool looks for skill folders, and what to check before you install someone else’s skill. Here is each, then how a team keeps one copy — and, at the end, a different approach, a skills folder on a company server, which is what we build.

What the standard defines

A skill is a directory with, at minimum, a SKILL.md file: YAML frontmatter, then Markdown instructions. Optional scripts/, references/ and assets/ folders hold code the agent can run, documents it can read and templates or data it can use. [2]

Agents load skills in three steps, which the standard calls progressive disclosure. At startup they read only each skill’s name and description; when a task matches a description, they read the whole SKILL.md; while following it, they open the bundled files they need. [1] The specification suggests keeping SKILL.md under 500 lines (under 5,000 tokens) and moving detail into separate files, referenced one level deep. [2]

The header has six fields:

Field Required Rule
name Yes 1–64 characters: lowercase letters, numbers and hyphens; no hyphen at the start or end, no two in a row; must match the folder name
description Yes 1–1,024 characters: what the skill does and when to use it
license No A license name, or the name of a bundled license file
compatibility No Up to 500 characters on what the skill needs: a product, system packages, network access
metadata No A map of string keys to string values, for anything else
allowed-tools No Experimental: a space-separated string of tools the skill may use without asking; support varies by agent

These six are the fields that every skills-compatible tool should accept. [2] The project’s reference library checks a folder against them — skills-ref validate ./my-skill — though its README says it is for demonstration, not production. [2][16]

Extra fields travel only sometimes

Each tool adds its own settings, and puts them in different places.

  • Claude Code accepts more fields in SKILL.md itself — for example disable-model-invocation (only you can start the skill), context: fork (run it in a subagent), paths (load it only for matching files) and hooks. It treats every field as optional, uses the folder name when name is missing, and ignores a field it doesn’t recognise without an error. [6]
  • Claude uploads are strict. A skill uploaded to claude.ai, sent through the Skills API or packaged with package_skill.py may use only the six standard fields; any other field fails with a hard error such as Unexpected key(s) in SKILL.md frontmatter: argument-hint. Body features that only Claude Code runs, such as dynamic context injection, don’t work in claude.ai chat or the API. [6]
  • Codex keeps its extras out of SKILL.md, in an optional agents/openai.yaml: a display name and icon for the ChatGPT desktop app, allow_implicit_invocation (set it to false and only an explicit $skill mention starts the skill), and tool dependencies such as an MCP server. [7]
  • Copilot in VS Code reads some of Claude Code’s extras too: argument-hint, user-invocable, disable-model-invocation, and context: fork, which it marks experimental. A name with characters outside the rules makes the skill silently fail to load there. [8]

So the rule for a skill you want to move: keep the header to the six standard fields, write name and description out even where a tool would guess them, and put tool-specific settings where that tool keeps them. A header with just the two required fields, name and description, loads in each of the four above. [6][7][8]

Write the description for matching, not for people. Agents pick a skill by its description, and the list they pick from is trimmed. Claude Code caps each skill’s listing text at 1,536 characters, and with many skills it fits the list into a budget of 1% of the context window by dropping the descriptions of the skills you use least. Codex by default gives the list 2% of the context window (8,000 characters if the window is unknown), shortens descriptions first and may leave some skills out. Both say to put the main use case first. [6][7]

Where each tool looks for skills

The specification defines what goes inside a skill folder, not where the folder lives. .agents/skills/ has emerged as the shared convention, and some agents also read .claude/skills/ because so many skills are already installed there. [4] The tools differ:

Tool In a project For one person Also
Claude Code .claude/skills/<name>/ in the start folder and each parent up to the repository root ~/.claude/skills/<name>/ Organisation-wide through managed settings; plugins; skills enabled on your claude.ai account, which is how a skill reaches Cowork and cloud sessions [6]
Codex .agents/skills/ in each folder from where you start up to the repository root $HOME/.agents/skills/ /etc/codex/skills for every user of a machine; bundled system skills; plugins [7]
GitHub Copilot in VS Code .github/skills/ ~/.copilot/skills/ Local sessions also read .claude/skills/ and .agents/skills/, and the same two under your home folder [8]

Two things follow.

  • A skill in .claude/skills/ is not a Codex skill, and one in .agents/skills/ is not a Claude Code skill, by default. [6][7] Copilot in VS Code reads both in local sessions. [8]
  • The same name means different things. With a deploy skill both in your home folder and in the project, Claude Code runs the personal one; [6] the standard’s guide for agent builders describes “project-level skills override user-level skills” as the common convention; [4] Codex doesn’t merge two skills with the same name and can show both. [7] Give team skills names nobody will reuse.

Keep one copy

Claude Code and Codex both follow a symbolic link to a skill folder. [6][7] So keep the real folder in one place — say .agents/skills/expense-review/ — and link .claude/skills/expense-review to it. Claude Code loads a skill once even when several locations point at the same folder. [6] Copilot in VS Code reads both folders in local sessions, [8] so check that it doesn’t list the skill twice.

Before you install someone else’s skill

A skill is instructions plus, often, code — so it can ask the agent to do things its description doesn’t mention. Anthropic’s guidance is to use skills only from trusted sources, meaning ones you wrote or got from Anthropic, and otherwise to audit every bundled file (SKILL.md, scripts, images and other resources) for network calls, file access or steps that don’t match the stated purpose. Skills that fetch content from outside URLs are a particular risk: what they fetch can carry malicious instructions, and even a trusted skill can be compromised if its outside dependencies change. [9] VS Code’s documentation says the same: reuse only skills you trust, because scripts in a skill can run tools or reach external systems. [8] The standard’s own guide for agent builders adds that skills inside a freshly cloned project may be untrusted and suggests loading them only after the person trusts the folder. [4]

allowed-tools deserves a second look. In Claude Code it pre-approves the listed tools for the turn in which the skill runs, through the normal permission rules — and workspace trust doesn’t gate it: Claude Code applies a project skill’s allowed-tools even in a folder you’ve never trusted, so its docs say to review that line in skills checked into a repository before you run Claude Code there. [6] A skill that pre-approves broad shell access is asking for more trust than one that reads files.

Sharing a skill with a team

Each tool has its own route: commit .claude/skills/, publish a plugin, or deploy through managed settings in Claude Code; [6] commit .agents/skills/, put skills in /etc/codex/skills on a shared machine, or package them as a plugin for Codex; [7] commit .github/skills/ for Copilot. [8] Two routes reach people who never open a terminal: Claude Code, Cowork and cloud sessions load skills an organisation provides on claude.ai, [6] and skills bundled in a ChatGPT plugin work in ChatGPT on the web, desktop and phone. [7] We compared the routes for Claude — a repository, Claude Team or Enterprise, or a server — in How to share Claude skills with your whole team.

A different approach: one skills folder on a company server

Another option is to keep skills where the company’s files live, so that who may use a skill follows folder access and group membership. That is what we build, so read this section as ours.

Trina AX runs Claude Code and Codex on one company server, with the company’s files, the team’s skills and each person’s folder permissions; people use it through a chat app in the browser, on the desktop or on a phone. [14]

  • The same format. Team skills are SKILL.md files under the server’s skills/ folder. The header rules are the standard’s: name of lowercase letters, numbers and single hyphens, up to 64 characters and equal to the folder name; a description of up to 1,024 characters; an optional compatibility of up to 500. A file may be up to 128 KiB and its header up to 8 KiB. A skill that breaks a rule doesn’t load, and the Team skills page shows why. [10]
  • Folder permissions and groups decide who can use a skill. skills/<name>/ is for everyone who can read skills/; skills/<folder>/<name>/ only for people who can read that folder, such as skills/finance/; groups/<group>/skills/<name>/ only for that group’s members, not the owner or admins outside it; projects/<project>/skills/<name>/ only in that project’s chats; users/<you>/skills/<name>/ only for you — not the owner or admins either. A personal skill replaces a group or team skill of the same name for that person only. [11][18]
  • One copy for both engines. The server lists the skills a person may use in the instructions of whichever engine answers, and gives the full text through its own skill tool, over the same connection as its file tools — so the same file serves Claude Code and Codex. [13] People pick a skill with / in a chat, or the AI picks one that fits the request. [11]
  • Who changes skills. The owner, admins and the people or groups an admin allows change team skills; others can suggest a personal skill for a skill manager to review. A group’s skills are changed by any member of that group, and a project’s by anyone who can write its folder. Every change is recorded, and the owner and admins get a notice with a link to the version history. [11][17][18] The AI asks a person before it saves a team, group or project skill, unless that person picked Always allow for skill saves, an option an admin can turn off for the team. [14][19][20] Admins can also install skill bundles for the whole company as plugins; those skills contain no code. [12]

What it doesn’t do. Its header check is strict. Of the standard’s fields it checks name, description and compatibility; metadata must be a map of text values, every other field must be plain text, and the header must be valid YAML with no repeated keys — where Claude Code would load a broken header with no fields set, the skill doesn’t load here. So a skill written for Claude Code with disable-model-invocation: true, or allowed-tools as a YAML list, is skipped until those lines change. The skill list in the AI’s instructions cuts each description to 160 characters (within 8,000 characters for all skills), and a skill’s text is cut at 16,000 characters. [6][13] Finding a skill never runs its scripts or grants the tools its header names; the engine has no shell of its own and reaches files only through the server’s tools. Where the dev environment is on, though, the AI’s commands can read skill folders, so a skill’s script could be run there; only the AI’s instructions say it can’t. [21] A skill’s reference files and templates are read through those tools, but a skill that depends on running its bundled scripts won’t work through the skill tool as it does on a laptop. [13][15] The security page says Trina AX has no security certification yet, and people with administrator access to the server — on a hosted plan, Trina’s operators — can read the stored data. [15] Codex isn’t available on an office Mac. [14] Installing it yourself is free under AGPL-3.0-only; [14][15] or Trina hosts a private server for you in Seoul for up to 40 people (larger teams by quote), the smallest paid plan for 5 people, with a 14-day free trial (a card is needed to start) and plans from $50 a month. AI usage is paid separately to your AI provider. [14]

Fits when the people who should follow a skill don’t use git or a terminal, and who may use which skill should follow who may open which folder.

Side by side

Skills in a repository (Claude Code, Codex, Copilot) Trina AX
Where a team skill lives .claude/skills/, .agents/skills/ or .github/skills/ in the repository [6][7][8] skills/ on the company server, or a group’s or project’s skills/ folder [11][18]
Who can use it Anyone with the repository [6][7][8] Folder permissions and group membership, checked per person [11][18]
Header fields The standard’s six, plus each tool’s own (Claude Code in SKILL.md, Codex in agents/openai.yaml) [2][6][7] The standard’s; metadata as text values, other fields as plain text; strict YAML [10][13]
Bundled scripts Run by the agent, under each tool’s permission rules [6][8] Not run by the skill tool; reference files are read through the server’s tools [13][15][21]
Changes Through the repository’s review, if any Skill managers (a group’s skills: its members); suggestions reviewed; every change recorded [11][18]

How to choose

  1. Developers, one repository, more than one agent → keep the folder in .agents/skills/, link it from .claude/skills/, and keep the header to the standard’s six fields.
  2. A team that already pays for Claude Team or Enterprise and uses Claude’s apps → the organisation routes in our post on sharing Claude skills.
  3. People who don’t use a terminal, and skills that should follow folder access → one skills folder on a company server, like Trina AX.

Questions people ask

What is the Agent Skills standard?

An open format for packaging a procedure for an AI agent: a folder with a SKILL.md file — a short header with a name and a description, then instructions — plus optional scripts, references and assets. Anthropic developed it and released it as an open standard. [1][2]

Do Claude Code skills work in Codex?

The format does; the folder doesn’t, by default. Codex reads .agents/skills/, Claude Code reads .claude/skills/, and both follow a symbolic link, so one folder can serve both. Claude Code’s extra fields, such as context: fork, aren’t part of the standard and aren’t in Codex’s documentation; Codex keeps its own settings in agents/openai.yaml. [6][7]

Where do I put SKILL.md?

In a folder named like the skill. In a repository: .claude/skills/<name>/ for Claude Code, .agents/skills/<name>/ for Codex, .github/skills/<name>/ for Copilot. For yourself: ~/.claude/skills/, ~/.agents/skills/ or ~/.copilot/skills/. [6][7][8]

Are agent skills safe to install?

As safe as their source and what they depend on. Use skills you wrote or got from a source you trust, read every bundled file first — scripts especially — and remember that a trusted skill can still be compromised if something it fetches changes. [8][9]

Try it

Claude is a trademark of Anthropic. Trina AX is made by Trina Inc. and is not affiliated with Anthropic.

Sources

  1. [1] Agent Skills Overview · agentskills.io/home · read 2026-11-06
  2. [2] Specification · agentskills.io/specification · read 2026-11-06
  3. [3] Client Showcase · agentskills.io/clients · read 2026-11-06
  4. [4] How to add skills support to your agent · agentskills.io/client-implementation/adding-skills-support · read 2026-11-06
  5. [5] Agent Skills Governance · github.com/agentskills/agentskills/blob/main/GOVERNANCE.md · read 2026-11-06
  6. [6] Extend Claude with skills · code.claude.com/docs/en/skills · read 2026-11-06
  7. [7] Build skills · developers.openai.com/codex/skills · read 2026-11-06
  8. [8] Use Agent Skills in VS Code · code.visualstudio.com/docs/agent-customization/agent-skills · read 2026-11-06
  9. [9] Agent Skills · platform.claude.com/docs/en/agents-and-tools/agent-skills/overview · read 2026-11-06
  10. [10] SKILL.md format · ax.trina.app/docs/agents/skills-format/ · read 2026-11-06
  11. [11] Team skills · ax.trina.app/docs/use/team-skills/ · read 2026-11-06
  12. [12] Plugins · ax.trina.app/docs/agents/plugins/ · read 2026-11-06
  13. [13] trina-app/trina-ax: server/src/chat/skills.ts · github.com/trina-app/trina-ax/blob/main/server/src/chat/skills.ts; trina-app/trina-ax: server/src/chat/skill-list.ts · github.com/trina-app/trina-ax/blob/main/server/src/chat/skill-list.ts; trina-app/trina-ax: server/src/chat/tools.ts · github.com/trina-app/trina-ax/blob/main/server/src/chat/tools.ts; trina-app/trina-ax: server/src/engine/codex.ts · github.com/trina-app/trina-ax/blob/main/server/src/engine/codex.ts · read 2026-11-06
  14. [14] Trina AX for LLMs (llms.txt) · ax.trina.app/llms.txt; Trina AX: Claude Code and Codex for your whole team · ax.trina.app/ · read 2026-11-06
  15. [15] Security and how it works — Trina AX · ax.trina.app/security · read 2026-11-06
  16. [16] skills-ref · github.com/agentskills/agentskills/blob/main/skills-ref/README.md · read 2026-11-06
  17. [17] Changelog (v0.5.2) · github.com/trina-app/trina-ax/blob/v0.5.2/CHANGELOG.md · read 2026-11-06
  18. [18] Team skills (v0.5.2) · github.com/trina-app/trina-ax/blob/v0.5.2/docs/site/use/team-skills.md · read 2026-11-06
  19. [19] Changelog (v0.5.3) · github.com/trina-app/trina-ax/blob/v0.5.3/CHANGELOG.md · read 2026-11-06
  20. [20] server/src/chat/always-allow.ts (v0.5.3) · github.com/trina-app/trina-ax/blob/v0.5.3/server/src/chat/always-allow.ts · read 2026-11-06
  21. [21] server/src/devenv/tool.ts (v0.5.7) · github.com/trina-app/trina-ax/blob/v0.5.7/server/src/devenv/tool.ts · read 2026-11-06
← All posts