← Back to concepts
8 min read

Skills

In AI systems, a skill is a reusable capability that helps a model perform a specific kind of task. A skill may include instructions, examples, tools, templates, validation rules, scripts, or reference files that support one workflow.

You can think of a skill as a packaged ability. Instead of writing a long custom prompt every time, the system can load the right skill when the user asks for that kind of work.

A simple example

Imagine an assistant that helps with software projects. It might have different skills:

  • A code review skill.
  • A release note writing skill.
  • A test failure investigation skill.
  • A database migration planning skill.

Each skill teaches the assistant how to approach that task. The code review skill may focus on correctness and security. The release note skill may focus on user-facing changes and clear summaries.

A skill packages the reusable parts of one workflow A release note skill is shown as a package around six reusable pieces: instructions, examples, a final template, allowed tools, validation rules, and code or scripts. The package is loaded into the application context for the model. The model then uses those pieces to produce a release note for the current request. User request "Write release notes" Release note skill instructions examples template allowed tools validation code/scripts Model uses skill Output note A skill is broader than a single prompt because it can include resources the workflow needs.
A skill is a reusable package for one kind of work, not just a longer prompt.

Skills vs prompts

A prompt is the text instruction sent to the model for a specific request. A skill is broader. It can contain prompts, but it can also contain supporting resources.

For example, a release note skill might include:

  • Instructions for grouping changes.
  • A template for the final note.
  • Examples of good release notes.
  • A tool for reading merged pull requests.
  • Rules for excluding internal-only changes.

The prompt is one part of the skill. The skill is the full reusable package.

In the common Agent Skills format, the SKILL.md file is the main instruction file. Its instructions are loaded into context when the skill is relevant, but the skill is the whole package: SKILL.md plus any supporting files around it.

Skills vs tools

Tool calling lets the model do something outside itself, such as search files, call an API, or update a record. A skill tells the model how to perform a type of work.

For example:

  • fetch_pull_requests() is a tool.
  • “Write a release note from merged pull requests” is a skill.

The skill may use the tool, but they are not the same thing.

Skills also differ from MCP. MCP connects an AI application to external tools, resources, and prompts. A skill packages know-how: when to use a workflow, how to perform it, and how to validate the result. A skill may call tools exposed directly or through MCP, but it is not the connectivity layer itself.

Prompt, skill, and tool at different levels Three columns compare a prompt, a skill, and a tool. A prompt is a per-request instruction that tells the model what to do now. A skill is a reusable workflow package that tells the model how to perform a type of work. A tool is an external function that the application can execute. An arrow from skill to tool shows that a skill may use tools, but the tool is not the skill. Prompt instruction for this specific request "Summarize this diff" Skill reusable workflow package for a task type instructions + examples + templates + constraints Tool external function the application can run fetch_pull_requests() may use A prompt says what to do now; a skill says how to do a kind of work; a tool performs an outside action.
Skills sit above prompts and tools: they organize a workflow and may call tools when the workflow needs outside data or action.

Why skills are useful

Skills make AI systems easier to scale. Without skills, every workflow may become a custom prompt hidden in application code. That gets hard to maintain.

With skills, teams can create reusable task modules. Each skill can be tested, improved, and versioned. Harness engineering helps teams check whether a skill behaves consistently on real examples.

Skills also help route user requests. If the user asks, “Can you review this diff?”, the system can load the code review skill. If the user asks, “Summarize this meeting”, it can load the meeting summary skill.

Many systems use progressive disclosure. Only skill names and descriptions are loaded up front. The full SKILL.md is loaded when a skill matches the request. Extra scripts, templates, and reference files are read only when needed. This saves context and tokens because the model does not see every detail of every skill on every turn.

The host or harness discovers the skill and injects the relevant instructions. The model does not load files by itself unless the application gives it file tools and permission to use them.

Progressive disclosure for skills A user request enters the application. The application checks a skill catalog that contains short names and descriptions. The matching description selects the release note skill. Only then is the full SKILL.md loaded into the model context. Supporting files such as scripts, templates, and reference docs are read later only when needed. Nonmatching skills remain unloaded so they do not add noise. User request "Draft release notes" Level 1 catalog names + descriptions code review release notes meeting summary database migration Level 2 SKILL.md instructions examples validation file references Model works with relevant guidance Level 3 support files are loaded on demand. Other skills stay out of context to reduce noise.
Progressive disclosure keeps the model focused: metadata first, full instructions when matched, supporting files only when needed.

The Agent Skills format

Several agent tools use a simple folder format for skills. A skill is a folder with a SKILL.md file and optional supporting files:

release-notes/
  SKILL.md
  templates/
    release-note.md
  scripts/
    collect-prs.py
  references/
    style-guide.md

A minimal SKILL.md usually has YAML frontmatter with name and description, followed by Markdown instructions:

---
name: release-notes
description: Use when the user asks to draft release notes from merged pull requests.
---

# Release notes skill

1. Collect merged pull requests for the target release.
2. Group changes into features, fixes, and internal work.
3. Draft concise user-facing notes.
4. Validate that every public claim is backed by a pull request.

The description is important because it is often the routing signal. A vague description such as “helps with releases” can collide with deployment, changelog, or versioning skills. A specific description says when to use the skill.

What a good skill contains

A good skill is focused. It should explain:

  1. When to use the skill.
  2. What the skill should accomplish.
  3. What inputs it expects.
  4. What tools it may use.
  5. What output format it should produce.
  6. What mistakes it should avoid.
  7. What validation steps prove the work is done.

For example, a support triage skill might say:

Use this skill when classifying support tickets.
Identify the issue type, urgency, product area, and next best action.
Do not promise refunds or policy exceptions.
Return structured JSON.

This makes the behavior easier to understand and test.

Good skills are also concise. Keep SKILL.md focused on routing, steps, examples, and validation. Move long reference material into separate files so it is loaded only when needed.

Skills in agent systems

Agents become more useful when they can load the right skill for the task. A general agent without skills may behave inconsistently across different workflows. Skills give it task-specific guidance.

For example, an agent handling a bug report could load:

  • A reproduction skill.
  • A log analysis skill.
  • A code search skill.
  • A fix validation skill.

The agent still decides what to do next, but the skills guide how each step should be done.

Skills can include scripts that run with the agent’s permissions. Install skills only from trusted sources, review scripts before enabling them, and version skills like code. Conflicting or overlapping skills can cause routing mistakes, so write descriptions that clearly say when to use each skill and when not to.

The key idea

Skills are reusable task capabilities for AI systems. They sit above raw prompts and may use tools. A good skill packages the instructions, examples, constraints, validation steps, and supporting files needed to do one job consistently without loading unnecessary context.