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 0–100 score is only a ranking/explanation signal, not the safety policy. Public projections downgrade legacy static Verified labels: static-heuristic can never produce Verified, and any fail-severity finding is Flagged/quarantined regardless of score. Verified is reserved for explicit manual review or genuinely isolated sandbox/combined runtime evidence.
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.