BLOG
PT
← Back to blog

Daniel Garcia

Anatomy of a Skill

Versão portuguesa →

As AI agents become more capable, there is also a growing need to provide them with clear, reusable procedures. This is where Skills come in: components that combine instructions, workflows, tools, rules and resources to teach an agent how to perform a particular type of task in a more structured and consistent way. In this article, we will take a Skill apart piece by piece to understand how it is built, how it works and when it makes sense to use one.

Illustration of an AI module connected to chat, document and image icons, with text, chart and automation outputs.
In this article

Context

What is a Skill?

In the context of Artificial Intelligence agents, a Skill is a reusable set of instructions, rules, knowledge and resources that teaches an agent how to perform a task or type of task more consistently.

A Skill can define:

  • when it should be used;
  • what input data is required;
  • which steps should be carried out;
  • which tools can or should be used;
  • restrictions and security rules;
  • decision criteria;
  • the expected format of the results;
  • checks to be carried out before completing the task;
  • scripts, references, examples, templates or other supporting resources.

A Skill should not be understood as simply a long prompt. Instead, it acts as a reusable operational manual for an AI agent.

How do they work?

In the open Agent Skills format, a Skill is usually represented by a folder containing, at minimum, a SKILL.md file.

This file combines:

  1. YAML metadata, used to identify and describe the Skill;
  2. Markdown instructions, which define how it should be executed.

A Skill can also include scripts, reference documentation, templates, examples, images, schemas or other resources required by the workflow.

A compatible agent can analyse the metadata of the available Skills, identify the one that matches the current task and load the full instructions only when necessary. This mechanism reduces the amount of context used and makes it possible to keep many Skills available without loading all their instructions at the same time.

Difference between Prompt and Skill

Prompts and Skills are related mechanisms, but they serve different purposes.

A prompt provides instructions to the model within a particular context. A Skill encapsulates procedural knowledge and a reusable workflow that can be applied repeatedly by an agent.

Aspect Prompt Skill
Purpose Provides instructions or context for a task, question or objective. Defines a reusable capability or procedure for carrying out a type of task.
Configuration Can exist at different levels of instruction, such as system, application/developer and user. Is usually stored as a dedicated, versionable artefact, generally in a folder containing SKILL.md.
Reuse Can be reused, but is often written for a specific interaction or context. Is specifically designed to be reused for similar tasks.
Execution The model interprets the instructions present in the context and generates a response or action. The agent identifies the appropriate Skill, loads the instructions and follows the defined workflow, using tools and resources when necessary.
Structure Can range from a simple sentence to complex instructions. Usually includes structure, metadata, workflow, restrictions, resources and validation criteria.
Consistency Depends heavily on the quality of the prompt and the context provided. Tends to produce greater consistency because the procedure is explicitly documented and reused.
Maintenance Changes may require modifying prompts scattered across several applications or conversations. Can be versioned and updated as an independent component.
Ideal for Questions, brainstorming, one-off tasks and specific instructions. Recurring, specialised, multi-step processes or those requiring consistent rules.

A simple way to visualise the difference is:

Prompt = instruction for this interaction.
Skill = reusable procedure for this type of work.

Importance of Skills

Skills make agents more predictable, specialised and reusable.

Saving time on repetitive tasks

A Skill avoids repeatedly explaining to the agent how to perform the same type of task.

It can be used, for example, to:

  • analyse documents;
  • generate reports;
  • review code;
  • prepare presentations;
  • process data;
  • organise files;
  • carry out technical procedures;
  • apply an organisation’s internal standards.

Producing more consistent results

When the same instructions, steps, formats and checks are reused, variability between executions is reduced.

Consistency does not depend on the Skill alone: it still depends on the model, the input data, the available tools and the quality of the instructions. However, a well-designed Skill significantly reduces unnecessary improvisation.

Supporting specialised use cases

A Skill can incorporate domain-specific knowledge.

Examples:

  • legal analysis;
  • systems administration;
  • software development;
  • data analysis;
  • technical support;
  • marketing;
  • research;
  • technical documentation;
  • internal company processes.

This means the agent no longer relies solely on its general knowledge and instead receives procedures and references specific to that context.

Scaling processes

A Skill makes it possible to turn individual knowledge into a reusable procedure that can be used by several people or agents.

This helps with:

  • process standardisation;
  • sharing best practices;
  • team training;
  • task automation;
  • reducing errors;
  • auditing procedures;
  • continuous improvement.

The Agent Skills Standard

Basic structure

In the open Agent Skills standard, a Skill corresponds to a directory containing at least:

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

The only mandatory file is normally SKILL.md.

The remaining folders depend on the needs of the Skill.

SKILL.md

The file contains two main parts:

---
name: my-skill
description: Description of what the Skill does and when it should be used.
---

# Instructions

...

The initial YAML block forms the frontmatter.

Mandatory and optional fields can vary depending on the specification and client, but name and description are the fundamental elements of the open format.

Progressive disclosure

One of the central ideas behind Agent Skills is progressive disclosure (progressive disclosure).

Rather than loading all complete Skills into the model’s context, a compatible client can work in several stages:

1. Discovery

The agent only knows minimal information about the available Skills, particularly:

  • name;
  • description.

2. Activation

When a task matches the description of a Skill, the agent can load the corresponding SKILL.md.

3. Execution

The agent follows the instructions and, when necessary, consults additional resources or executes tools and scripts.

This approach reduces context usage and makes it possible to maintain relatively large Skill libraries.

Anatomy of a Skill

A good-quality Skill should clearly answer several questions.

1. Identification

Which Skill is this?

Usually defined through:

  • name;
  • description;
  • version;
  • author or organisation;
  • licence;
  • additional metadata.

The description is particularly important because it can be used by the agent to decide when the Skill is relevant.

2. Conditions of use

When should it be used?

A Skill should make it clear:

  • which requests should activate it;
  • which types of files or data it supports;
  • which tasks are within its scope;
  • which tasks are outside its scope.

A description that is too vague can lead to incorrect activations.

3. Inputs

What information does it require?

For example:

  • files;
  • text;
  • parameters;
  • credentials;
  • location;
  • structured data;
  • project context.

When a required input is missing, the Skill should specify how to proceed.

4. Workflow

What sequence of work should the agent follow?

Example:

1. Validate inputs
2. Identify the type of task
3. Consult the necessary references
4. Execute the operation
5. Validate the result
6. Correct any issues found
7. Produce the final result

The workflow should be explicit enough to reduce ambiguity, but not so rigid that it prevents the agent from adapting when necessary.

5. Tools

Which tools can or should be used?

A Skill may depend on:

  • file system access;
  • browser;
  • APIs;
  • databases;
  • terminal;
  • Python;
  • Git;
  • external applications;
  • MCP tools;
  • local scripts.

It is important to distinguish between:

  • mandatory tools;
  • preferred tools;
  • optional tools;
  • prohibited tools.

6. Resources

A Skill can include supporting resources.

references/

Documentation that the agent can consult when necessary.

Examples:

references/
├── api.md
├── business-rules.md
├── architecture.md
└── examples.md

scripts/

Reusable code for deterministic or repetitive operations.

Examples:

scripts/
├── validate.py
├── convert.py
└── build_report.py

assets/

Resources used to produce the result.

Examples:

  • templates;
  • images;
  • schemas;
  • configuration files;
  • examples;
  • document templates.

7. Restrictions and guardrails

What should the agent not do?

A good Skill should explicitly define its limits.

Examples:

  • do not delete files without confirmation;
  • do not modify production files;
  • do not expose credentials;
  • do not invent missing data;
  • do not use external tools without authorisation;
  • do not perform destructive operations without validation.

Guardrails reduce errors and make execution safer.

8. Output format

Where relevant, the Skill should specify how the result should be presented.

Examples:

  • Markdown;
  • JSON;
  • CSV;
  • report;
  • table;
  • code;
  • file;
  • directory structure.

When the format is important for automated systems, it should be described precisely.

9. Validation

A robust Skill does not simply stop after performing the task.

It should define final checks.

For example:

Before concluding:

- confirm that all files have been processed;
- validate the syntax;
- check required fields;
- confirm that there are no errors;
- compare the result against the requirements;
- indicate any limitations or missing data.

This stage acts as a quality control mechanism.

10. Error handling

A Skill should explain how to react when something goes wrong.

It can define:

  • when to retry an operation;
  • when to use an alternative strategy;
  • when to stop;
  • when to request additional information;
  • when to inform the user of a limitation.

A Skill that only describes the ideal scenario tends to be less robust.

Execution Cycle

In simplified form, the cycle can be represented as follows:

User request
        │
        ▼
Discovery of available Skills
        │
        ▼
Is there a relevant Skill?
        │
   ┌────┴───────┐
   │            │
  no           yes
   │            │
   ▼            ▼
Normal     Load SKILL.md
response        │
                ▼
          Validate inputs
                │
                ▼
          Execute workflow
                │
                ▼
           Use tools
                │
                ▼
          Validate result
                │
                ▼
          Deliver response

Portability

The Agent Skills format was designed to make reuse easier across different compatible agents and platforms.

However, format portability does not mean full execution compatibility.

A Skill may require adaptations when moving between clients because of differences in:

  • available tools;
  • permission systems;
  • directory locations;
  • APIs;
  • client-specific conventions;
  • support for additional YAML fields;
  • activation mechanisms;
  • execution environments.

It is therefore more accurate to say:

A Skill based on the open standard can be structurally portable between compatible clients, but its execution may require platform-specific adaptations.

Best practices

A Skill should be:

Specific

It should solve a clearly defined problem or set of related problems.

Reusable

It should not depend unnecessarily on a single conversation.

Deterministic where possible

Operations that can be performed reliably through scripts should consider this approach rather than relying exclusively on text generation.

Modular

Skills that are too large become difficult to maintain.

It is generally preferable to divide distinct responsibilities into independent Skills.

Explicit

Important rules should not depend on implicit interpretation.

Versionable

Because Skills consist of text files and associated resources, they can be maintained in a version control system such as Git.

Testable

A Skill should be tested with different types of input, including:

  • normal cases;
  • edge cases;
  • incomplete inputs;
  • tool errors;
  • unexpected data.

Security

Skills can include instructions capable of:

  • executing scripts;
  • reading files;
  • accessing external services;
  • using APIs;
  • modifying data;
  • executing commands.

For this reason, a Skill obtained from a third party should be treated in much the same way as external code or automation.

Before installing or running an unknown Skill, it is advisable to check:

  • its source;
  • the contents of SKILL.md;
  • included scripts;
  • commands being executed;
  • network access;
  • requested permissions;
  • use of credentials;
  • destructive operations.

A Skill should not be considered safe simply because it is written in Markdown.

When should you create a Skill?

A Skill is particularly useful when:

  • the same task is performed frequently;
  • there is a well-defined procedure;
  • maintaining consistency is important;
  • multiple steps are required;
  • there are rules that must not be forgotten;
  • the agent requires specialised documentation;
  • specific tools or scripts are involved;
  • the result needs to follow a precise format.

A Skill may be unnecessary when:

  • the task is a one-off;
  • a simple prompt solves the problem;
  • the process is not yet sufficiently stable;
  • the workflow is still being explored.

Prompt, Skill, Tool and Agent

These concepts are often confused.

Concept Function
Prompt Tells the model what it should do or consider.
Skill Teaches a reusable procedure for a particular type of work.
Tool Allows the agent to perform an external action or obtain information.
Agent A system that interprets objectives, selects Skills and tools, and coordinates execution.

A Skill can instruct an agent to use a Tool, but the Skill is not the tool itself.

Conceptual example

Imagine a Skill called:

analyse-configuration-nginx

The Skill could define:

---
name: analyse-configuration-nginx
description: Analyses Nginx configurations, identifies errors, security issues and optimisation opportunities.
---

And then include a workflow:

1. Locate the configuration files.
2. Identify includes.
3. Validate the syntax.
4. Analyse the TLS configuration.
5. Look for insecure rules.
6. Identify `server_name` and port conflicts.
7. Check security headers.
8. Produce a report.
9. Classify issues by severity.
10. Suggest corrections without modifying files automatically.

It could also use:

scripts/
└── nginx_check.sh

references/
├── security.md
└── conventions.md

Together, these elements form a reusable capability that is far more structured than a single prompt.

Conclusion

A Skill can be understood as a reusable unit of procedural knowledge for AI agents.

Its usefulness lies not simply in storing instructions, but in bringing together within a single component:

Skill
├── Metadata
├── Conditions of use
├── Inputs
├── Workflow
├── Tools
├── Resources
├── Restrictions
├── Error handling
├── Output format
└── Validation

This structure makes it possible to turn human procedures or repeated prompts into workflows that are more consistent, documented, versionable and reusable.

References