Agent Skills: From Usage to First Principles

#AI #Agent #Skills #OpenAI #Claude 1,637 words 8 min read

A Skill is not a “longer prompt,” nor is it another name for a model capability. More precisely, it is a folder specification for packaging repeatable workflows, domain knowledge, scripts, and resources. An agent normally sees only an index of these capabilities and expands the details when needed.

0. Article Map

This article moves from usage to structure to first principles:

#QuestionAnswer
1What is a Skill?A capability folder with an entry-point document
2How is it used?It can be invoked explicitly or selected automatically by the agent
3Where does it live?Different hosts scan different paths
4Why does it save context?Through progressive disclosure: index first, details later
5How does it relate to the agent loop?It is runtime context, not a model parameter
6How does it relate to MCP, subagents, and tools?It defines the workflow rather than replacing tools or execution isolation
7How do you write one?Be clear about triggers, execution paths, and degrees of freedom
8What are the risks?Skills can contain instructions and code, so their sources must be reviewed

1. What Is a Skill?

I now prefer to think of a Skill as an agent capability package.

Its smallest form is not an API or a prompt fragment, but a directory. The directory must contain a SKILL.md, which does two things:

  1. It tells the agent what the Skill is called and when to use it.
  2. It tells the agent what to do once it decides to use the Skill.

The directory can also contain scripts/, references/, and assets/. These folders are optional, but they are what distinguish a Skill from an ordinary prompt: a prompt can only provide instructions, while a Skill can bundle scripts, templates, and reference material with those instructions.

A typical structure looks like this:

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

The most important field is description in the SKILL.md frontmatter. It is not a human-facing introduction; it is the trigger condition the agent uses for routing.

A weak description:

description: Use this to analyze marketing data

A better one:

description: Use when the user provides marketing campaign data in CSV format and asks for funnel analysis, ROAS, CPA, or budget allocation recommendations.

The first says only what the Skill is. The second says when to use it. Whether a Skill triggers correctly depends largely on this field.

2. How Do You Use It?

From the user’s perspective, there are two ways to enter a Skill.

The first is explicit invocation. In environments that support Skills, you can name one directly through a command, selector, or slash command. In Claude Code, this commonly takes the form /skill-name; Codex has its own commands and selection interfaces.

The second is automatic triggering. The agent first sees the name and description of every available Skill, then decides whether one is relevant to the current task. The user does not necessarily have to say “use this Skill.” If the task matches its semantics, the Skill may be activated automatically.

That is why a description should be written as a trigger condition rather than a product pitch.

3. Directory Structure and Loading Paths

The Skill directory format is converging toward a shared standard, but different hosts still look for Skills in different places.

In the Codex ecosystem, repository-level Skills usually live in .agents/skills. Codex scans upward from the current working directory to the repository root. It also supports user-level, administrator-level, and system-level locations.

In the Claude Code ecosystem, common paths include:

  • Personal Skills: ~/.claude/skills/<skill-name>/SKILL.md
  • Project Skills: .claude/skills/<skill-name>/SKILL.md
  • Plugin Skills: <plugin>/skills/<skill-name>/SKILL.md

This has a practical consequence: Skills do not belong only to a “global assistant.” They can travel with a project or a team’s workflow. A repository can encode its release process, testing strategy, and documentation style as Skills, giving the agent those capabilities as soon as it enters the project.

4. Why Progressive Disclosure Matters

The most important design feature of a Skill is not that it can contain many files, but progressive disclosure.

If an agent has dozens or even hundreds of Skills installed, injecting every SKILL.md in full at the start of each conversation would quickly consume the context window. Skills instead use three loading levels:

LevelWhat is loadedWhen it is loadedPurpose
L1name + descriptionAt session start or during capability indexingTell the agent what capabilities are available
L2Full SKILL.mdWhen a Skill is judged relevantLoad the specific operating instructions
L3scripts/, references/, and assets/On demand during executionSupply scripts, templates, long documents, and media

This structure solves a context-budget problem.

The description is the index, SKILL.md is the operating manual, and references/ and scripts/ are the repository. The agent reads the index first, opens the manual once relevance is established, and consults the repository only when execution requires more detail.

That is the essential difference between a Skill and pasting in a large prompt: a prompt is injected all at once, while a Skill unfolds on demand.

5. How It Relates to the Agent Loop

To understand where a Skill fits, start with the agent loop.

A typical agent turn looks roughly like this:

  1. The system assembles the user’s input, project instructions, permission boundaries, available tools, and available Skill metadata into the model input.
  2. The model decides whether to answer directly or request a tool call.
  3. The agent executes the tool and appends the result to the context.
  4. The model decides what to do next, repeating until the task is complete.

A Skill enters at step 1 and remains available throughout subsequent execution. It is not training data and does not change the model’s parameters. It consists of workflow instructions placed into the runtime context and file resources that can be read on demand.

A Skill is therefore closer to a temporary operating procedure installed for the agent than to permanently training the model as an expert.

6. Boundaries Between Skills, MCP, Subagents, and Tools

These concepts are easy to mix together, but they solve different problems.

ConceptWhat it solvesForm
ToolA single atomic capabilityAPI / function
MCPAccess to external data and servicesPersistent protocol connection
SkillWorkflow + domain knowledgeFolder
SubagentAn isolated execution contextIndependent agent instance

My mental model is:

  • Tools and MCP provide capabilities.
  • Skills define how work gets done.
  • Subagents let you assign a piece of work to a separate executor.

A Skill should therefore not be written as a list of tools. A better design is for the Skill to define the process, boundaries, and output standards, while calling tools and data sources as needed.

For example:

  • A Skill defines the rules for classifying customer feedback and the format of the resulting insights.
  • MCP connects to raw interviews, surveys, or document systems.
  • Subagents analyze separate datasets in parallel.
  • Tools handle atomic operations such as reading files or executing code.

This is also why a Skill’s scripts/ directory is not a tool definition. Its contents are simply small utilities invoked as needed within the workflow.

7. Constraints I Look for When Writing a Skill

I use the following criteria to judge whether a Skill is well designed:

  1. Its description states trigger conditions, not marketing copy.
  2. Its SKILL.md contains only the execution path, with lengthy knowledge moved to references/.
  3. Deterministic, repetitive, and error-prone mechanical steps are delegated to scripts/.
  4. The directory structure stays shallow so the agent does not have to hunt through layers of files.
  5. Operations involving external systems, secrets, deployment, or deletion require explicit confirmation.

Going one step further, a Skill’s degree of freedom can be divided into three levels:

  • High freedom: the goal is clear but the method is open, suitable for creative tasks.
  • Medium freedom: there is a recommended pattern, but deviation is allowed, suitable for semi-structured tasks.
  • Low freedom: the steps are fixed and must be followed, suitable for production workflows.

I prefer to write a Skill as a compact, precise operating manual:

  • The entry conditions are clear.
  • The steps are stable.
  • All necessary material is close at hand.
  • The parts that need to be fixed are fixed, so the agent does not improvise itself off course.

8. Security Boundaries

The power and risk of a Skill come from the same place: it can contain instructions, files, and code.

An untrusted Skill may instruct an agent to take harmful actions, while its scripts may connect to external networks, read sensitive files, or execute commands they should not. Host-level scanning and permission controls help, but they do not replace human review.

I treat a Skill as an executable project dependency rather than ordinary Markdown:

  1. Read SKILL.md first.
  2. Inspect any actual code in scripts/.
  3. Check for network access, file writes, secret reads, deployment, and publishing behavior.
  4. Keep a human confirmation step for high-risk Skills instead of allowing silent execution.

9. Conclusion

The central value of an Agent Skill is not that it adds another prompt. It turns reusable experience into a stable, discoverable, and distributable capability package.

It serves three groups at once:

  1. Users repeat fewer explanations of the same process.
  2. Agents see a capability index first and load details only when needed.
  3. Organizations preserve team conventions, business processes, templates, and scripts as file-based assets.

My one-sentence summary is:

A Skill is a workflow package for the agent era. It takes “knowing how” out of one-off conversations and places it in a reusable, reviewable, and evolvable directory.

Compressed even further, it does three things:

  1. Turns experience from verbal guidance into file-based assets.
  2. Turns context from one-shot injection into progressive loading.
  3. Turns workflows from improvisation into repeatable execution.

References