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
Every skill detail page emits a single-line install command per agent. Commands are idempotent — running them twice is safe. For agents that don't yet ship an official registry, we emit a placeholder shape; the card metadata stays stable so SKILL.md needs no edits when registries land.
Reading the audit
Every skill carries a 0–100 trust score and a verdict (verified / community / unverified / flagged). All findings render verbatim — no severity is suppressed. See the Security policy page for the full scoring formula.
Webhook API & MCP
POST /api/webhook/dify validates an HMAC-SHA256 signed payload. Before forwarding, every secret is replaced with a typed placeholder ([REDACTED:aws], [REDACTED:jwt], …). The same index is exposed as an MCP server so agents can search/install programmatically.
Privacy & data
No accounts are required to browse or install. Telemetry is restricted to anonymous code-block dwell time used for ranking; opt out via DNT or by blocking /api/telemetry. Every entry in the index is derived from public GitHub repos with author attribution 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.