Agent Skills guide: the spec defines six SKILL.md fields, but invocation and permission settings differ by tool

Summary

Terms used here

• A skill is a folder containing SKILL.md and, optionally, scripts, reference documents and templates. The agent reads the folder when it needs it and follows the procedure.
• Frontmatter is the YAML block between the --- markers at the top of SKILL.md. It holds the skill's name, description and settings such as how it may be invoked.
• Progressive disclosure means the agent first puts only names and descriptions into its context, reads a skill's body once it decides to use that skill, and reads other files only when the body points to them. The context is everything the model receives as input at once.
• Automatic invocation is the agent picking a skill on its own by matching your request against skill descriptions. Explicit invocation is you calling it directly, as in /skill-name or $skill-name. The Codex docs call these implicit and explicit invocation.
• Pre-approval lets a skill use specified tools without asking you to confirm each call. The spec's allowed-tools field does this.

What the spec defines: one folder and six fields

Under the agentskills.io specification, a skill is a directory containing at least a SKILL.md file. scripts/ (executable code), references/ (documentation) and assets/ (templates, images, data) are optional; the spec describes these three folders as recommended conventions and allows any other files and folders. [1]

my-skill/
├── SKILL.md          # required: frontmatter + instructions
├── scripts/          # optional: executable code
├── references/       # optional: documentation
└── assets/           # optional: templates, images, data

The 2026-06-16 first version of this report also listed an agents/ folder. Because the spec allows extra folders, that layout is not wrong, but the spec does not define that folder, and the agents/openai.yaml file inside it is a settings file that Codex reads (see the tool comparison below). [6]

The body has no format restrictions. The spec recommends putting step-by-step instructions, input and output examples, and common edge cases in it, and gives three levels for progressive disclosure. At startup the agent reads the name and description of every skill, about 100 tokens per skill. It reads the whole body once it decides to use the skill, with under 5,000 tokens recommended, and reads other files only when needed. The spec therefore recommends keeping SKILL.md under 500 lines, moving long material into separate files, and keeping file references one level deep from SKILL.md. Format checks use the reference tool published with the spec, skills-ref validate ./my-skill. [1]

---
name: summarize-changes
description: Summarizes uncommitted git changes and flags risky edits. Use when the user asks what changed or wants a commit message.
---

## Steps
1. Read the current git diff.
2. Summarize the changes in three bullets or fewer.
3. List risks: missing tests, error handling, hardcoded values.
4. Suggest one commit message.

An example using only the spec's two required fields. The directory must also be named summarize-changes.

What differs by tool: paths, blocking automatic invocation, pre-approval

All three tools' docs say they follow the Agent Skills spec. Their skill search paths and settings outside the spec still differ. The table below reflects each tool's official documentation as checked on 2026-10-06; we did not install the same skill in all three tools to confirm it. [2] [6] [7]

Three differences matter in practice right away.

• Claude Code and Codex share no repository path. Claude Code reads .claude/skills/; Codex reads .agents/skills/. Both docs say they follow symlinked skill folders, so you can keep the source in one location and link it from the other. VS Code reads all three paths.
• The setting that blocks automatic invocation lives in different places. For skills with side effects, such as deploying or sending messages, Claude Code and VS Code use disable-model-invocation in SKILL.md, while Codex uses a separate file, agents/openai.yaml. If you set only one, the agent in another tool can still choose that skill on its own.
• Only Claude Code reliably loads a skill that omits name or uses a name that differs from its directory. Claude Code falls back to the directory name, but the Codex and VS Code docs make name required, and the VS Code docs say a skill whose name differs from its directory does not load.

Even within Anthropic's products, behavior differs

According to the Claude Code docs, claude.ai and the Skills API reject with an error, rather than ignore, any uploaded skill whose frontmatter includes fields outside the spec, such as disable-model-invocation, context or argument-hint. The VS Code docs list these three fields too, but those upload paths accept only the spec's six. Claude Code's !`command` feature, which inserts a shell command's output into the body, also does not work in claude.ai chat or through the API. [2] The runtime environments differ too. [4]

The same skill can call an external API in Claude Code but not through the Claude API. If a script needs network access or package installation, record that requirement in compatibility, the field the spec provides for environment requirements. [1]

The gains came from human-curated procedural skills

Among the sources we checked, SkillsBench is the broadest measurement of whether skills improve task results. It pairs each of 87 tasks across 8 domains with human-curated skills and a verifier that grades results automatically, runs each task with and without skills, and compares pass rates across 18 model and harness configurations. The harnesses include Claude Code, Codex CLI, Gemini CLI and OpenHands. [9]

The last row matters most for adoption. In three configurations (Claude Code + Opus 4.7, Codex + GPT-5.5, Gemini CLI + Gemini 3.1 Pro), the agent first wrote skills with skill-creator, Anthropic's skill-authoring tool, then solved the tasks with only those skills. Pass rates fell 8.1 to 11.5 percentage points below the no-skill baseline. In the same configurations, human-curated skills added 18.2 to 24.8 percentage points. The authors attribute the shortfall to generated skills the solving agent never found, skill-writing work that consumed solving time, and confidently wrong instructions. [9] So this result does not support the idea that you can simply generate skills automatically. By length, compact and standard-length skills performed similarly, while comprehensive documentation-style skills had almost no effect.

Skills made results worse on 13 of the 87 tasks. Comparing paired runs, the authors found a common pattern: the skill prescribed a single "correct" pipeline with no stated scope or lightweight fallback. It either imposed an overly heavy procedure, displaced a strategy the model already handled well, or pointed the agent at a tool it could not debug. [9]

The official authoring guidance points the same way. Anthropic's guidance says to run representative tasks without a skill first and record the failures, build three evaluation scenarios that test those failures, then write only enough instructions to pass them. [5] The Claude Code docs say to check separately whether a skill gets invoked and whether its output is what you expect, and describe comparing the same prompts in fresh sessions with the skill on and off. [2] When running a skill as a subagent with context: fork pays off is covered in Subagents vs agent skills.

How to write descriptions and bodies

• Put the main use case and the trigger conditions at the start of the description. The Claude Code and Codex docs both say this. With many skills, the list exceeds its budget and descriptions get cut, and a cut description no longer lets the agent match requests to skills. [2] [6]
• Say both what the skill does and when to use it. The spec and Anthropic's docs both require this, and Anthropic's authoring guidance says to write it in the third person because the description is injected into the system prompt. [1] [5]
• Put task-wide instructions near the top of the body, and word them so the agent applies them throughout the task. Claude Code adds an invoked skill's body to the conversation once and does not re-read it. When the conversation is summarized, it re-attaches only the first 5,000 tokens of each skill, within a combined 25,000 tokens, starting from the most recently invoked skill. [2]
• Put rules that must hold every time into a hook, a command that runs at a fixed point, not into a skill. The Claude Code docs say hooks run whether or not the model is following the skill. [2]

Review third-party skills like software you install

Anthropic's Agent Skills docs recommend using only skills you wrote yourself or got from Anthropic, and say that for a skill from an unknown source you should read and review every bundled file, including SKILL.md, scripts and images, before using it. They also note that a skill fetching content from external URLs may pull in malicious instructions, and that even a trustworthy skill can be compromised if its external dependencies change. [4]

Two ways a skill gains execution rights in Claude Code

Source: Claude Code skills docs and settings reference, checked 2026-10-06. [2] [3]

That is why the Claude Code docs advise reading the allowed-tools of skills checked into a repository before you run Claude Code there. [2] Permission rules can also block skills outright: adding Skill to the deny rules blocks all skills, and a rule like Skill(deploy *) blocks a specific one. How this behavior changed in recent versions is covered in our Korean report on Claude Code plugin security changes, and how many official-marketplace plugins pre-approve Bash through allowed-tools in our Korean audit of 315 official marketplace plugins.

A study of more than 30,000 public-marketplace skills

Liu et al. collected 42,447 skills from two public marketplaces (skills.rest and skillsmp.com) in December 2025, removed duplicates and skills with almost no content, and scanned the remaining 31,132 with static analysis and a large language model (LLM) classifier. [10]

The authors say directly that 26.1% should be read as "patterns warranting review", not as "confirmed malicious skills". The detector's precision is 86.7% and its recall 82.5%. The 17.3% of skills whose repositories had already been deleted at collection time were excluded; the authors note these may have included more malicious skills, so the true rate could be higher. [10] The difference by script inclusion is a correlation observed in this sample; the authors did not establish a cause.

One sentence in the description changed which skill was chosen

Saha et al. tested attacks that modify only SKILL.md. For each of 100 skills from the public registry ClawHub, they made a variant with identical functionality and one sentence appended to the description, and presented it side by side with the original. Across four models (GPT-4.1-mini, GPT-5, Gemma-4-31B, Qwen3-235B), the variant was chosen in 77.6% of trials on average, against a 50% random baseline. The appended sentences were of four kinds: false advertising, assertive cues, security or trust claims, and claims of active maintenance. [11] The experiment used a two-way choice and did not measure how Claude Code or Codex actually select skills, but as the authors conclude, a SKILL.md description is input that changes agent behavior, so it belongs in review alongside the scripts.

Checklist

1. Start with the instructions you keep pasting into chat. The Claude Code docs say to create a skill when you keep pasting the same instructions, checklist or multi-step procedure, or when a section of CLAUDE.md has grown into a procedure rather than a fact.
2. Run representative tasks without a skill first and record the failures. Write only enough instructions to fix those failures, then compare results in fresh sessions with the skill on and off.
3. Start the frontmatter with the spec's six fields and make name match the directory name. That keeps the skill loadable in VS Code and accepted by claude.ai and Skills API uploads. Assume a field outside the spec works only in tools that read it, and remove such fields from copies you upload to claude.ai or the Skills API.
4. Put the main use case and the trigger conditions at the start of the description. Descriptions get cut when the list exceeds its budget.
5. Block automatic invocation of skills with side effects in every tool you use. In Claude Code and VS Code, that is disable-model-invocation: true; in Codex, allow_implicit_invocation: false in agents/openai.yaml.
6. Before running Claude Code in someone else's repository, read the allowed-tools and !`command` lines in .claude/skills/. Organizations should review allowManagedPermissionRulesOnly and disableSkillShellExecution in managed settings.
7. Read and review every file of a third-party skill before adopting it. Check scripts for network calls and file access, any content fetched from external URLs, and inflated trust claims in the description. A recent update is not evidence of safety.
8. Move rules that must hold every time into hooks. Skill instructions can lose force as a conversation grows or is summarized.

What this is not yet

• This is a rewrite, on 2026-10-06, of an initial note first published in Korean on 2026-06-16. We did not keep the earlier text and tables as they were; every claim was checked again against its source. We removed the earlier top-10 table of marketplace installs and its chart: the source was a marketplace's own article promoting its skills, a secondary source, and when we reopened it on 2026-10-06 the install counts the first version cited were no longer on the page. We also removed the category priorities, staged adoption timeline, industry scenarios and recommended-skill list, which the first version had set without evidence. Cursor, which the first version listed as a supporting tool, was not checked this time and is not covered.
• We did no measurement of our own. The tool comparison reflects what the official docs say; we did not install the same skill in all three tools to confirm behavior. That the Codex and VS Code docs do not mention allowed-tools means it is absent from the docs, not that it has been confirmed not to work.
• Anthropic's own docs disagree in one place. The Agent Skills overview says Claude Code skills are separate from claude.ai and the API, while the Claude Code docs say terminal sessions signed in with a claude.ai account download and use that account's skills. We report both statements as written and did not check which reflects current behavior.
• SkillsBench results come from terminal-based, containerized tasks. The authors say the results may not carry over directly to GUI agents or very long workflows, and that some of the gain could come simply from skills adding context. They also say the self-generated result mixes in cases where the solver did not find the skills and interference between the authoring and solving stages.
• The 26.1% is the share the detector flagged. It counts carelessness and malice together, is a December 2025 snapshot of two marketplaces, and, as the authors note, does not represent enterprise deployments or the ecosystem as it later evolved.
• The description-manipulation experiment used a two-way choice. It was measured with 100 ClawHub skills and four models, and the authors note results may differ with real agents' selection policies or other models.
• All three papers are arXiv preprints. We did not check whether they have passed peer review.
• Product docs and version numbers change quickly. All paths, fields, budgets and versions are as checked on 2026-10-06.

Sources

All checked on 2026-10-06. Product docs were fetched as Markdown source (append .md to the URL) and compared; for the three papers, values and limitations sections were checked in the arXiv LaTeX source. Product docs describe the vendor's own product behavior and are not independent verification.

The 2026-06-16 initial note was rewritten on 2026-10-06 to the current standard. We changed the title and structure, removed the marketplace install ranking that could no longer be checked against its source and the priority and timeline tables the first version set without evidence, and added the tool-by-tool differences and the results of three papers. Of the material moved in from our coding agents comparison (then titled “2026 AI coding agent landscape”) in the 2026-09-07 revision, the release and open-standard dates were checked against the source and kept; the two-role classification of skills and the install distribution were removed for lack of evidence meeting this standard.