What is an Agent Skill
A skill is a folder. The bare minimum is a SKILL.md describing what problem it solves, when the agent should reach for it, and how to do the work. It can bundle scripts/, references/, and assets/ alongside. The format was open-sourced by Anthropic at agentskills.io and is now supported by 30+ agent products including Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Goose and GitHub Copilot.
Anatomy of a skill folder
Only SKILL.md is required; the rest are optional. Codex additionally reads agents/openai.yaml for UI config, invocation policy and tool dependencies.
my-skill/
├── SKILL.md # 必须 · 元数据 + 指令
├── scripts/ # 可选 · 可执行代码
├── references/ # 可选 · 参考文档
├── assets/ # 可选 · 模板与素材
└── agents/openai.yaml # 可选 · Codex 专用 UI/策略SKILL.md frontmatter fields
All fields live between the leading --- delimiters. Only name and description are spec-mandatory; the rest are audit bonuses and community convention. Keep description under 140 chars — it enters the agent's startup progressive-disclosure index and is the only signal the agent has when deciding whether to load the full body.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Skill slug; must match folder name; lowercase-kebab. |
description | string ≤ 140 | Yes | One-liner stating when this skill should and should NOT trigger. |
category | enum | No | engineering · ai · productivity · design · devops · documentation · writing · data · security · other |
license | SPDX | No | SPDX identifier. Declare explicitly for +6 audit points. |
version | semver | No | Semver string for change tracking (+4 audit points). |
agents | string[] | No | Compatible agent IDs; controls how many install commands render. |
allowed-tools | string[] | No | Tools the skill needs (Bash, Read, …). Omitting is interpreted as "any tool". |
tags | string[] | No | Free-form keywords; folded into the search haystack. |
Progressive disclosure: how agents use skills
At startup, the agent only loads each skill's name + description (a few dozen tokens, sub-1KB total). Only when a user request matches a description does the agent pull the full SKILL.md into context; scripts under scripts/ load lazily when called. This is how an agent can carry hundreds of skills with negligible context overhead.
- 01 Discovery
name + description only — a few dozen tokens each
- 02 Activation
Pull full SKILL.md only when the description matches
- 03 Execution
Lazy-load scripts/ and references/ when invoked
Where skills live: four scopes
Directories vary by agent but scope semantics are stable: SYSTEM is shipped by the agent vendor; ADMIN is pushed by your org; USER is your personal library; REPO travels with the repository for team sharing. The Hub crawls public SKILL.md files in the first three scopes and never reads private local skills.
| Scope | Path | Note |
|---|---|---|
SYSTEM | 随 Agent 安装包内置 | Bundled with the agent. Codex auto-loads .system on install. |
ADMIN | /etc/codex/skills · 类似企业策略 | Org-pushed compliance skills; overrides user scope. |
USER | ~/.claude/skills · ~/.codex/skills · ~/.agents/skills | Your personal library, shared across projects. |
REPO | $REPO/.agents/skills · $CWD/.claude/skills | Repo-bound skills; travel with the branch and team. |
Installing a skill, per agent
Skill pages emit one-line commands only for agents verified by the public skills CLI, with an explicit target-agent flag. Unverified catalogue labels retain compatibility information but do not receive copyable placeholder commands.
Reading the audit
The compatibility period keeps the legacy 0–100 audit score and verified / community / unverified / flagged classification, but these describe the legacy static-audit layer only. They do not imply source trust, runtime safety, platform compatibility, real runtime testing, or human review. Skill detail pages expose those evidence layers separately.
Public interfaces
The public site currently provides read-only skill browsing, search, and bundle downloads. Write-capable webhooks and MCP access are not public yet; authentication, secret scrubbing, rate limits, and audit evidence will be required before launch.
Privacy & data
No account is required to browse or install, and the site currently sends no browsing or dwell-time telemetry. Indexed skills come from public GitHub repositories with upstream authors and source links preserved.
Writing principle: extract from real traces
Do not treat a skill as a polished prompt. A stronger path is to run the workflow once in real files, environment, and goals, then record assumptions, tool order, recovery, verification, and output format before compressing it into a reviewable workflow.
Quality loop: audit, test, iterate
When reusing skills, stars are discovery signals, not quality proof. Audit files before installing, then test should-trigger, should-not-trigger, and should-stop cases. One failure is a clue, not a rule; compare examples before editing description, body, scripts, or references.