Building agent skills: from folder structure to testing and sharing

What skills are and why they are needed

The Anthropic engineering post source frames the problem this way. However capable a model is, real work requires procedural knowledge and organizational context, such as 'at this company, we do it in this order.' Skills (Agent Skills) were created to fill that gap. A skill is a folder of organized instructions, scripts and resources that the agent finds on its own and loads when needed. The same post compares building a skill to putting together an onboarding guide for a new hire.

Skills serve a different purpose from the prompts you normally write. Claude's official documentation source distinguishes prompts, which are conversation-level instructions for a one-off task, from skills, which are reusable resources loaded when needed. Once you have built a skill, you no longer need to paste the same guidance into every conversation. Anthropic says it provides built-in skills for PowerPoint, Excel, Word and PDF, and that custom skills can be used in Claude Code, the API and claude.ai settings source.

Skills are also not a format tied to a single product. In December 2025, Anthropic released Agent Skills as an open standard that can be used across multiple platforms source, and a public specification source defines the folder structure and field rules. Simon Willison's post source also points out that nothing prevents skills from being used with other models.

Components of a skill folder

According to the Agent Skills specification source, a skill is, at minimum, a folder containing a single SKILL.md file. You can optionally add scripts/ for executable code, references/ for reference documents, and assets/ for static resources such as templates, images and data files. All three are only recommended conventions; you can include other files or folders if needed.

SKILL.md must begin with YAML frontmatter (a configuration block at the very top of the file), and it has two required fields: name and description sourcesource. The specification source also defines optional fields: license for the license, compatibility for describing the required environment in 500 characters or fewer, metadata for arbitrary key-value pairs, and allowed-tools (an experimental feature) for listing pre-approved tools. The specification adds that most skills do not need compatibility.

The body below the frontmatter is Markdown with no format restrictions. The specification source recommends including step-by-step instructions, input and output examples, and common edge cases. Code in scripts/ should be self-contained or clearly state the libraries it needs, and should produce easy-to-understand error messages. Files in references/ should stay small and focused on a single topic, because the agent reads them each time they are needed.

Progressive disclosure: reading in three levels

The core of skill design is progressive disclosure. Level 1 is metadata. At startup, the agent preloads the name and description of every installed skill into the system prompt source, at about 100 tokens per skill sourcesource. Simon Willison source described each skill as taking up only a few dozen extra tokens. Level 2 is the body of SKILL.md. It is read only when a user request matches the description, and the official documentation recommends keeping it under 5,000 tokens sourcesource.

Level 3 is the reference files and scripts inside the folder. In the PDF skill example from the Anthropic engineering post source, SKILL.md only refers to reference.md and forms.md by name. Because the instructions for filling out forms are split out into forms.md, Claude reads that file only when it fills out a form. Scripts are even lighter. According to Claude's official documentation source, scripts run via bash and the code itself never enters the context; only its output does.

As a result, even with many skills installed, only their names and descriptions occupy the context window until they are actually used source. The engineering post source explains that this makes the amount of material you can bundle into a skill effectively unlimited. However, this approach only works in an environment where the agent can read the file system and run commands sourcesource.

Design principles: name, description, length and degrees of freedom

Start with the name. Under the specification source, name must be 64 characters or fewer and may contain only lowercase letters, numbers and hyphens. It must not start or end with a hyphen, cannot contain consecutive hyphens, and must match the folder name. Claude's authoring guide source additionally bans reserved words such as 'anthropic' and 'claude'. It recommends gerund (verb-ing) forms such as processing-pdfs and advises against vague names such as helper, utils or data.

The description determines whether a skill actually gets used. The authoring guide source states that Claude uses this description to choose one skill from what may be more than 100. It therefore recommends covering both what the skill does and when to use it, and including key terms users are likely to mention. Because the description is inserted directly into the system prompt, it must be written in the third person, not the first person as in 'I can help you…'. The specification source gives 'Helps with PDFs.' as a bad example, and as a good example a sentence that lists extracting text and tables from PDFs and filling out forms, and also states 'use when the user mentions PDFs or forms.'

Shorter is better. The authoring guide source calls the context window a shared resource used alongside the system prompt, conversation history and other skills, and says to take 'Claude is already smart' as the default assumption. It considers an example of about 50 tokens that keeps only the library name and code better than one of about 150 tokens that even explains what a PDF is. The specification source recommends keeping SKILL.md under 500 lines. It says to move details into separate files and reference them from SKILL.md only one level deep. The engineering post source adds that splitting content that is not used together into different files saves tokens.

How specific to make the instructions depends on how easily the task can go wrong. The authoring guide source divides degrees of freedom into three levels. When several approaches can all be correct, as in code review, give only high-level written direction. When there is a preferred pattern, give pseudocode or a script with parameters. When a sequence must be followed exactly, as in a database migration, go as far as 'run this command exactly as written.' The same document compares this to a narrow bridge with cliffs on both sides versus an open field. The criteria for including scripts are similar. The engineering post source explains that code is better for tasks that are expensive to do by generating tokens, such as sorting a list, and for tasks that must always produce the same result. It also recommends stating clearly whether Claude should run a script directly or read it as a reference. Simon Willison source likewise wrote that he adds scripts only when they are more reliable or efficient.

Steps for building your first skill

First, start with evaluation. The engineering post source recommends running the agent on representative tasks, identifying where it gets stuck or needs more context, and then incrementally building skills that fill those gaps. Do not start with skills that merely seem 'nice to have.'

Second, write name and description first. These two lines determine whether the skill gets used. Third, in the body, briefly note only what the model does not know: company-specific procedures, fixed commands and common mistakes. Fourth, when the body grows long or contains material needed only in specific situations, move it to references/. Put tasks that must run exactly as defined into scripts/. Fifth, check the frontmatter format and naming rules with the skills-ref validate command described in the specification source.

Sixth, test on every model you plan to use. The authoring guide source says a skill's effectiveness depends on the underlying model. It recommends checking whether the guidance is sufficient for Haiku and whether the explanations are excessive for Opus. Seventh, observe actual usage. The engineering post source says to watch for unexpected trajectories (the work path the agent took) and overreliance on particular files. It also recommends having Claude record successful approaches and common mistakes in the skill, and having it reflect on what went wrong when a task goes off track. This lets you discover the context that is actually needed instead of guessing it in advance.

Checklist

Start with format. Does SKILL.md begin with YAML frontmatter? Does name match the folder name and use only lowercase letters, numbers and hyphens source? Is description non-empty, 1,024 characters or fewer, and written in the third person, covering both what the skill does and when to use it sourcesource?

Check length and structure. Is the body under 500 lines source? Have you removed general explanations the model already knows and asked 'Is this paragraph worth its tokens?' source? Are reference files linked from SKILL.md one level deep, using relative paths source? Is content that is not used together split into separate files source?

Check scripts and behavior. Does each script state whether it is meant to be run or read as a reference source? Are required libraries and error messages clear source? Have you tested on the models you will actually use source? Before installing a skill from an unfamiliar source, have you reviewed its file contents, code dependencies and any instructions to connect to external networks source?

Common mistakes, security, and how skills differ from MCP and subagents

Common mistakes fall into a few categories. The description is vague, such as 'Helps with documents', so the skill never gets invoked sourcesource. The description is written in the first or second person, which confuses skill discovery source. Content the model already knows is spelled out at length, wasting tokens source. Reference files form deep chains that point to yet other files source. The skill is tested on only one model source.

Security needs separate attention. The engineering post source warns that a malicious skill can introduce vulnerabilities into the environment, exfiltrate data, or steer Claude into unintended actions. It therefore recommends installing skills only from trusted sources and thoroughly auditing the file contents of any others before use. Simon Willison source pointed out that because skills depend on a code execution environment, a sandbox is important for limiting the damage from attacks such as prompt injection. When sharing skills within a team, it is also safer to make this audit process a common rule.

MCP does a different job. MCP is a protocol for connecting external tools and data. The engineering post source said Anthropic will explore ways for skills to complement MCP servers by teaching complex workflows that use external tools. Simon Willison source saw skills' reliance on a file system and command execution environment as the biggest difference from MCP. He also cited a case where GitHub's official MCP alone takes up tens of thousands of tokens of context, and judged that skills impose a smaller burden because they read details only when needed. This is his personal view.

The input sources for this piece do not directly cover subagents, so only the general distinction is given here. A subagent is a separate agent to which the main agent delegates work; it works in its own context and then returns the result. A skill does not create a new agent; it is a bundle of knowledge and tools that the currently working agent reads when needed. So think of subagents when you want to divide up 'who does the work,' and skills when you want to teach 'how the work is done.'

To learn more

Start with the Anthropic engineering post source, which covers in one place why skills were introduced, how progressive disclosure works, and tips for building and evaluating them. Next, the level-by-level loading table and the PDF skill loading example in Claude's official overview documentation source give a sense of what actually enters the context.

When building your own, keep Claude's skill authoring guide source and the Agent Skills specification source at hand. The authoring guide provides criteria for judgment such as conciseness, degrees of freedom, and writing names and descriptions. The specification provides field rules, folder conventions and validation tools. Finally, Simon Willison's post source shows from a developer's perspective how skills differ from MCP and what real skills look like.