These are my notes on Skills. I wanted to understand where they fit in an agent system, then look at how the text in a folder becomes guidance used while a task is being carried out.
The article first uses diagrams to explain the components and loading process, then works through how to write a Skill with Codex's Skill Creator. If you also want to organize some of the ways you use agents in everyday work, I hope you will read along and share your understanding.
1 The concept: what a Skill does in an agent system
The motivation: why we need Skills
Models can already understand code, organize prose, and work with files through tools. But a concrete task still requires the user to supply a great deal of information: which conventions a project follows, which materials are trustworthy, where the result should be delivered, how different situations should be handled, and what counts as complete.
Some of this information belongs only to the immediate task, such as which article to edit this time. Other methods recur: check original sources for technical claims, confirm the outline before writing the full article, and prefer suitable existing images when choosing illustrations. Repeating these instructions each time takes effort, and some may be missed in a new conversation.
A Skill organizes this kind of task knowledge into a reusable package of files. It uses SKILL.md as its entry point, stores instructions, and can include references, scripts, and assets as needed. The application or framework running the agent is usually called the host. A host that supports Skills discovers and loads these files; the model then uses their guidance alongside the current task. This is also their basic role in the Agent Skills open standard.
The stored content may be a workflow, criteria for making domain decisions, explanations of data, or instructions for using tools. This knowledge participates in reasoning through the context. Parts suited to programmatic handling can also call scripts in the package. None of this changes the model's parameters. The outcome still depends on whether the guidance is accurate, the task is suitable, and the execution environment has the required capabilities.
What interests me most is which methods are worth keeping so that the next task needs less repeated explanation while leaving room to address its particular circumstances. Renaming a long prompt to SKILL.md does not, by itself, answer those questions.
Responsibilities: how prompts, AGENTS.md, Skills, and tools work together
These elements often appear together. Their responsibilities provide a useful way to distinguish them:
| Element | Main responsibility | Typical contents |
|---|---|---|
| Current prompt | Explain what needs to be done this time | Goal, input materials, scope, and special requirements for this task |
| AGENTS.md | Provide project conventions that continue to apply | Repository commands, coding conventions, and verification requirements |
| Skill | Preserve reusable methods and knowledge for a type of task | Use cases, decision criteria, workflows, and supporting resources |
| Tool | Perform a concrete action | Read files, run commands, or query and write to services |
| MCP | Connect capabilities such as tools and resources | The protocol and interactions between clients and servers |
This division helps explain their roles; it is not a set of mutually exclusive categories enforced by every host. Project conventions can refer to a Skill, and a Skill can guide an agent in using tools supplied through MCP.
For example, a Skill can explain how to check query results, but a tool still executes the query. MCP can connect an agent to external services, while a Skill can describe how to combine those services for a type of work. Naming a tool in a file does not automatically supply an account, credentials, or permission to execute it.
The following official diagram brings these parts together. The agent's configuration is on the left; an environment capable of reading files and running programs is on the right, with the Skill's contents stored in its directories.

Image source: Anthropic, Equipping agents for the real world with Agent Skills. This is the original article's virtual-machine environment example. Local files, tools, and MCP can work together; it does not mean every Skill requires a virtual machine or an MCP service.
Scope: what to retain and what to leave in the current task
Material worth putting into a Skill usually affects execution decisions and can be reused across similar tasks. Domain rules, fields that are easy to misinterpret, stable delivery formats, and methods that have repeatedly proved useful can all have value.
“Check the results carefully” is too vague. “When citing a performance improvement, identify the comparison and test conditions; if the materials are insufficient, leave the claim marked for verification” provides an actionable basis for judgment.
Temporary data, changing project status, and one-off arrangements are better kept in the current task or their original data sources. Fixing them in a Skill may introduce stale information the next time it is used. Mechanical actions that require precise guarantees should be considered for implementation in a program or host mechanism, with instructions explaining when to call it, what to pass in, and how to judge the result.
2 Structure: how SKILL.md organizes instructions and resources
The entry file: the roles of the name, description, and body
Under the Agent Skills specification, the minimum structure is a directory containing SKILL.md. The file begins with YAML frontmatter containing at least name and description, followed by Markdown instructions.
The following teaching excerpt is drawn from a writing task. It illustrates how the information is divided; it is not a complete writing Skill:
---
name: technical-notes
description: Help organize Chinese technical notes; use for source research, outline discussion, and drafting, or for scoped edits to an existing draft.
---
# Technical Notes
For a new article, first propose the core question, chapters, reference links, and illustration plan. Write the full article after confirmation.
Continue directly once an existing outline has been approved; keep local edits within their specified scope.
Distinguish source conclusions from the author's judgments. Do not invent personal experiences or results.
Read references/voice.md when drafting the body.
Read references/figures.md when selecting or creating illustrations.name identifies the capability. description helps the host and model decide whether it suits the current task before reading the full instructions. A description should therefore explain what it does and when to use it. “Help process documents” offers little distinction from related capabilities such as translation, formatting, and proofreading.
The body explains what to do after selection: which inputs are needed, which judgments must be respected, when to read supporting material, and what counts as complete. It does not need to teach the model all general knowledge again. Its purpose is to add information missing from the current task that will change how the work is done.
Supporting resources: the roles of references, scripts, and assets
A single file can work when the entry point explains the task sufficiently. Add supporting resources when more material is needed:
technical-notes/
├── SKILL.md
├── references/ # Knowledge and rules read as needed
│ ├── voice.md
│ └── figures.md
├── scripts/ # Helpers used when actually needed
│ └── check_image_refs.py
└── assets/ # Templates or materials for deliverables
└── article-template.mdThis is an optional structure. The example script and template do not indicate that they have been implemented. The directories serve different purposes:
| Location | Suitable contents | How it is used |
|---|---|---|
| SKILL.md | Shared guidance, key constraints, and resource entry points | Read into context after the Skill is selected |
| references/ | Longer knowledge or material needed only in certain situations | Read when the current step needs it |
| scripts/ | Repeated, well-defined processing suited to a program | Run through an existing execution tool and check the output |
| assets/ | Templates, images, styles, and other deliverable materials | Copy, fill in, or use as a format reference, depending on their purpose |
The official PDF example below shows how material can be separated: the entry point retains the basic guidance, while advanced references and form handling live in additional files. Processing an ordinary PDF does not require loading every form-handling detail first.

Image source: Anthropic's explanation of Skill design. reference.md and forms.md are example filenames in this diagram, not a required structure for every Skill.
Structural choices: when one file is enough and when to split it up
The reason to split material is when it will be used. A few short rules that are always used together usually belong in the entry point. When different task branches need large amounts of different material, separate references can reduce irrelevant content.
The entry point should also state the conditions for reading a resource. “When illustrations are needed, first read references/figures.md” is clearer than a list of filenames on its own. Relative paths are resolved from the Skill directory; the execution working directory cannot be assumed to be the installation directory. Scripts should explain their arguments, dependencies, output locations, and the meaning of their results. Templates should state whether they are to be copied and filled in or used only as references.
Splitting material too finely increases lookup and reading operations, while unclear references make it easy to miss information. Maintaining a Skill requires considering both whether the entry point is too long and whether material moved elsewhere can still be found. The number of directories is not meaningful by itself.
Some products also support extension files. Codex's agents/openai.yaml can configure interface information, invocation policies, and tool dependencies. This is a product-supported extension; the open format does not require every host to provide the same configuration capabilities.
3 Runtime behavior: from discovery to on-demand loading and execution
Discovery and activation: what the host and model each do
The host must discover the files before they can participate in a task. It may scan established local directories or provide Skills through a registry, API, or bundled resources. The open format specifies file contents, but does not require every product to use the same installation path.
After discovery, the host usually supplies catalog information such as names and descriptions to the model first. The model uses this information to decide whether it needs particular guidance, then reads the corresponding entry point. The user can also explicitly specify a Skill. The host integration guide explains discovery, catalog disclosure, activation, and subsequent context management separately; they are not one operation.
Taking Codex as an example, the current official usage guide supports both explicit and implicit invocation. In the CLI and IDE, users can mention $skill-name; Codex can also select a Skill when its description fits the task. Implicit selection depends on that match. A word appearing in a description should not be interpreted as a fixed rule that will always trigger activation.
The host determines how the entry point reaches the model. An environment that supports file reading may let the model read it directly. Other environments may provide an activation tool or inject the content through program logic. Whichever path is used, the instructions must actually reach the model before they can guide subsequent execution.
Progressive disclosure: when metadata, instructions, and resources enter context
Progressive disclosure can be understood in three stages: first learn which capabilities are available, then read the full guidance for the selected capability, and finally obtain the supporting material needed for the current step.
All three address the same problem: at the start of a task, the system does not yet know what it will need, so loading the entire contents of every Skill into context would be premature. The official diagram below shows the reading sequence for a PDF task.

Image source: Anthropic's context-loading example. The Bash reads, file paths, and placement in the system prompt belong to this specific implementation example. The focus here is the sequence from summaries to entry-point instructions to related material.
Initially, the diagram contains only brief information about each Skill. Once the user asks to fill in a PDF, Claude reads the PDF Skill's entry point. That entry point mentions form-handling material, so Claude reads forms.md next. The reference was separated precisely because it is needed only for this branch of the task.
On-demand loading also has costs. Catalog information still takes space, and instructions and references consume context once read. If the entry point requires every reference to be read in advance, splitting them up loses its purpose. Each read should serve the current task, rather than mechanically dividing a long prompt into files and then reading them all at once.
Context compression, retention of activated content, and control over repeated loading in long conversations are implemented by the host. A Skill can concentrate key constraints and provide clear resource entry points, but its files do not manage session memory or guarantee that every host behaves the same way after compression.
The execution environment: running scripts and returning results to the model
References mainly provide knowledge, while scripts can perform concrete processing. An agent can call an existing execution tool, pass arguments to a script, and continue based on its exit status, output files, or a necessary summary. Running a script usually does not require reading its complete source into context first. Source reading may become necessary when diagnosing an error or modifying the program.
This leaves processing suited to precise execution with the program. The model judges which step the current task needs and how to interpret its result; the program processes data according to defined logic. This division still requires clear interfaces. An instruction that says only “run the checking script,” without defining what it checks or what failure means, makes it difficult for the agent to decide correctly from the output.
Execution also depends on interpreters, packages, networking, or service credentials. A Skill can document dependencies and usage, but the environment must satisfy those conditions separately. Instructions and scripts in an external Skill should also be read carefully. An open file format does not make arbitrary code in it trustworthy to execute.
4 Writing and validation: distilling working methods with Codex Skill Creator
Defining the task: inputs, outputs, and boundaries from real needs
Writing a Skill can start with a task that has already been carried out: which steps were necessary, which corrections will still apply next time, and which material helped the model make sound judgments. Distill these into methods for similar tasks, rather than saving an entire conversation unchanged.
When organizing this writing Skill, reusable methods include discussing an outline before drafting, not inventing experiences, and looking for reusable sources before creating illustrations. This article's specific chapters and sentences needing revision remain in the article directory. Keeping the two kinds of information separate lets the next article reuse the methods while retaining its own subject.
The Agent Skills writing guidance likewise emphasizes extracting knowledge from real domain material and execution. Without that material, a Creator may be able to produce only generic requirements such as “follow best practices” and “handle errors carefully.”
Codex's Skill Creator can help create or modify these packages. The bundled version actually read for this work emphasizes preserving the user's scope, adding only non-obvious information that changes decisions, and selecting supporting resources according to the task. The following summarizes that writing process; it is not a fixed pipeline that every invocation must complete.

Original schematic, organized from the Codex Skill Creator used for this work. A simple change can edit the relevant rules directly; initialization tools are used only when a new skeleton is needed.
Writing the entry point: a description for selection, a body for decisions
One starting point is a specific request to the Creator:
$skill-creator Organize the confirmed technical-article collaboration methods into a writing Skill.
Inputs include a topic, notes, existing drafts, or project material.
For new articles, first provide chapters, source links, and an illustration plan. Write the full article after the author confirms them.
For scoped edits, modify the requested part directly without reopening discussion of the entire outline.
Maintain Chinese expression rules and illustration rules separately; do not translate or publish automatically.
An existing yeagerzhao-writing directory is available. Update it in place and retain resources that remain valid.This request explains the task, materials, working method, and scope. The Creator can then decide what the entry point needs to retain and which details should live in separate resources. If the input is only “make a very professional writing Skill,” generating more text cannot supply the missing basis for judgment.
The description makes the Skill discoverable for suitable tasks; the body gives execution a basis after selection. For example, whether the outline has been confirmed directly determines whether the next step is discussion or drafting, so that branch needs to be explicit. The exact number of characters in a title or sentences in a paragraph may not need to be fixed in advance.
The level of detail should also follow the task. Open-ended writing and design need goals, tradeoffs, and necessary constraints. Error-prone format conversion may benefit from precise parameters and scripts. Locking down every step can force a small edit through the full process; guidance that is too abstract can make important boundaries ineffective.
Organizing resources: what belongs in references and what merits a script
The writing Skill's structure in this case can be simplified as follows:
yeagerzhao-writing/
├── SKILL.md
├── references/
│ ├── workflow.md # Two-stage collaboration
│ ├── voice.md # Titles, openings, and expression preferences
│ ├── figures.md # Image selection and diagramming methods
│ └── humanizer-op7418.md # Selected snapshot for tone editing
└── scripts/
├── lib/drawio.mjs # Compile content models into editable diagrams
├── render.ps1 # Export through the existing diagramming application
└── validate.py # Check structural consistency of diagram filesThe entry point identifies whether the current work is planning, drafting, or a scoped edit. Detailed examples of openings stay in the voice reference, and illustration rules are read only when images are needed. The diagram's content and relationships still require judgment; model conversion and file checks are left to existing programs. There is no assets/ directory added just to complete the structure, because this workflow does not currently need a separate deliverable template.
The Creator's initializer can generate a directory, entry point, and some product configuration. Domain content still needs to be supplied after generating the skeleton. When updating an existing Skill, inspect its files and references first and modify them in place, rather than overwriting them through reinitialization.
Product configuration also needs to be considered separately. Current Codex documentation allows agents/openai.yaml to declare interface information, tool dependencies, and invocation policies. For example, allow_implicit_invocation: false disables eligibility for implicit selection while retaining explicit use. This is a host-supported extension. Before moving to another product, check that product's capabilities; identical directory structures alone do not imply identical behavior.
Validation and revision: observing use after the format passes
The Creator's quick_validate.py can perform basic static checks, but the checks depend on its version. The local version used here covers some frontmatter, naming, and unfinished placeholders. It does not establish that every reference is accessible, scripts run correctly, or the model can complete the task. A validation pass therefore means only that the checks actually performed by that tool have passed.
Next, observe behavior on a small set of relevant tasks. For a writing Skill, these might include whether a new topic gets an outline first, existing approval leads directly to continued drafting, a local edit stays within scope, and missing factual support leads to invention. The focus is the result and its boundaries, not requiring exactly the same tool sequence every time.
If the wrong task is selected, inspect the description first. If the entry point was read but supporting material was missed, check the reading conditions and paths. If a script fails, diagnose the program and its input. Add rules only when a concrete gap appears. A complex workflow may require additional independent evaluation; an ordinary wording change usually needs one readback.
Version differences also matter: the bundled Creator used here is not identical to the version in the public repository. The public Skill Creator source helps explain its organization, while the actual version in use determines its initialization, configuration, and validation capabilities.
5 Open-source practice: three useful ways to organize a Skill
Judgment-oriented guidance: a compact entry point can work
Anthropic's frontend-design focuses on design decisions: understand the subject, audience, and purpose, then choose typography, colors, layout, and motion, and review the result against the requirements.
The value of this kind of Skill is giving design choices a concrete basis. It does not need to import every piece of frontend documentation or add scripts and reference directories merely to complete a structure. For work primarily based on judgment, where shared guidance fits in a short entry point, a single file can be appropriate.
When learning from it, consider how it organizes judgment rather than applying its aesthetic preferences directly to every project. The user's needs and the actual content remain the deciding factors.
Rule indexes: using a large body of knowledge on demand
Vercel's React best practices takes another approach. The entry point provides categories, impact priorities, and an index; individual rule files explain when a rule applies and give positive and negative code examples.
This structure suits knowledge with many entries that need to be consulted by problem. For asynchronous data fetching, first locate the relevant rule and then read its explanation; using one rule does not require expanding everything in advance. Rules still have preconditions. Parallel execution, for instance, requires that the operations have no dependencies that must be preserved. Multiple await expressions are not, by themselves, a reason to make everything concurrent.
It also provides a compiled version for reading in one place. Such compiled files within Skill resources should be used according to the entry-point instructions. Even if a file is named AGENTS.md, that name alone does not make it equivalent to conventions that apply automatically from the current project root.
Tool integration: giving well-defined processing to programs
Anthropic's PDF Skill illustrates how instructions, references, and tool usage fit together. The entry point covers common operations. Tasks such as forms lead to the relevant guidance, while concrete operations rely on Python libraries, command-line tools, or helper programs.
Its organizational focus is routing by task and making inputs, processing, and outputs clear. Reading form fields is suitable for a program; deciding which path to take now and what the field results mean still requires guidance and reasoning.
The three structures suit different work: a short entry point retains judgment criteria, an index organizes many rules, and a tool-oriented workflow connects precise processing. They do not share one ideal directory structure. When organizing a Skill of your own, start with knowledge you repeatedly need to supply and gaps found during actual execution, then decide what to retain. This is usually easier to maintain than designing a large structure first.
This article is based on public specifications, official material, and the locally bundled Creator examined on November 16, 2026. Statements about product behavior are bounded by the corresponding host and version.
References: specifications, implementations, and original explanations
- Agent Skills: format specification
- Agent Skills: adding Skills support to an agent
- Agent Skills: writing guidance
- Anthropic: Equipping agents for the real world with Agent Skills
- OpenAI: Build skills
- OpenAI: Skill Creator
- Anthropic: frontend-design
- Vercel: React best practices
- Anthropic: PDF Skill
- Simon Willison: Claude Skills are awesome, maybe a bigger deal than MCP, for additional discussion of simple file-based designs and execution environments; its predictions reflect the author's views.

