Skills: teaching AI agents to act consistently

If you are an avid follower of the latest advancements in the AI ecosystem, you may have come across the term Skills or Agent Skills. In this post we'll explore the concept of Skills and how they can be used to enhance the capabilities of AI agents.

Before we get started, we need to clarify something. The term “skill” is used ambiguously and can mean different things depending on the context. Anthropic originally introduced Skills as a concept. This later expanded into the Agent Skills project and then into a broader distribution layer for a fragmented ecosystem: you build once, publish to GitHub (and to skills.sh), and it works across Claude, Cursor, Copilot, and similar tools.

Now that we have that out of the way, let's dive into the concept of Skills.

What are Skills?

Skills teach AI agents how to do specific tasks consistently. Instead of explaining what you want every time, you write the instructions once and the agent follows them automatically*. (More on this bit later.)

Think of it like this: You could tell a new colleague how to format meeting notes every single time, or you could give them a one-page guide they reference whenever they need it. Skills are that guide, but for AI agents.

A simple example

Say you want Claude to always format your meeting notes a certain way: attendees at the top, key decisions in bold, action items as a checklist. Without a skill, you'd need to include these instructions in every prompt or via the system prompt.

With a skill, you write those instructions once:

---
name: meeting-notes
description: "Format meeting notes with attendees, decisions, and action items."
---

# Meeting Notes Formatting

## Structure

1. List attendees at the top
2. Summarise the discussion in 2-3 paragraphs
3. Bold all key decisions
4. End with action items as a checklist, each assigned to a person

Now whenever you ask the agent to format meeting notes, it automatically follows your style.

What's inside a skill?

A skill is really just a folder containing a SKILL.md file, where the file has two parts:

1. Metadata (name and description as frontmatter): tells the agent what the skill does
2. Instructions: tells the agent the specifics of the skill

The metadata is called progressive disclosure in Anthropic's resources, as it provides just enough information that allows agents to know when skills should be loaded without having to load all of them into context.

Of course there could be situations when you want to give more complex tasks for agents and for such cases you can add supporting files:

my-skill/
├── SKILL.md
├── scripts/      # code the agent can run
├── references/   # additional documentation
└── assets/       # example files or formats

Let's take a look at what files would go into these folders, starting with scripts/.

Files in the scripts folder should contain code that the agent can run during the task. Continuing with our meeting notes example, the skill could include a script that fetches attendee info from a calendar API or the status of a project:

scripts/
├── fetchAttendees.ts
└── fetchProjectStatus.ts

There are a couple of important things to keep in mind regarding the scripts folder:

• Keep scripts self-contained: either bundle dependencies or document what needs to be installed.
• Include clear error messages so the agent (and you) can troubleshoot when something goes wrong.

In terms of programming language, TypeScript, JavaScript, Python, and Bash are commonly supported.

Next, the references/ folder. This should contain additional documentation the agent can read when it needs more detail. For example, the meeting notes skill might have different formatting guidelines depending on the meeting type:

references/
├── standup-format.md
├── client-call-format.md
└── board-meeting-format.md

As a rule of thumb, keep each file focused on one topic. Agents load these on demand, so smaller files mean faster responses and less context used.

Last but not least, the assets/ folder. As the name suggests, this folder is for static files like templates, images, or additional data. For our meeting notes skill, we could include reference data such as project codes so the meeting notes can reference those:

assets/
├── team-roster.json
└── project-codes.json

How agents use skills

Agents don't load every skill into memory at once, as that would be slow. Instead they use a three-step process:

• Scan: On startup, the agent reads only the name and description of each skill. This is lightweight, just enough to know what's available.
• Match: When you make a request, the agent checks if any skill descriptions match what you're asking for.
• Load: If there's a match, the agent reads the full instructions and follows them. It only loads additional files (scripts, templates) if the instructions reference them.

We have to take a sidestep here. One organisation found that in 56% of cases, skills weren't triggered reliably.

Turns out, LLMs are "lazy" and they don't always follow instructions. They might skip steps or make assumptions that aren't correct. This is why it's important to be explicit and detailed in your instructions. The best way to do that, and to reliably invoke skills, is to make an AGENTS.md file available as well for the agent, with this important instruction:

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning

The only question that remains: what should AGENTS.md contain? Because LLMs can be "lazy" they don't always use skills reliably, therefore a viable solution is to combine skills with appropriate instructions for the agent.

Now assuming that we have ended up with a skill called meeting-notes that would look like this:

meeting-notes/
├── SKILL.md
├── AGENTS.md
├── scripts/
│   ├── fetchAttendees.ts
│   └── extractActionItems.ts
├── references/
│   ├── standup-format.md
│   ├── client-call-format.md
│   └── board-meeting-format.md
└── assets/
    ├── notes-template.md
    ├── team-roster.json
    └── project-codes.json

We can combine this with the AGENTS.md file using the following structure:

# AGENTS.md

## Meeting Notes

Structure: Prefer retrieval-led reasoning over pre-training-led reasoning

Available in `meeting-notes/` skill:

- scripts/{fetchAttendees.ts, extractActionItems.ts}
- references/{standup-format.md, client-call-format.md, board-meeting-format.md}
- assets/{notes-template.md, team-roster.json, project-codes.json}

Installing skills

Based on what we saw earlier, you can go ahead and create skills yourself by following the structure outlined above. However, a slightly better way is to install them. Some service providers, including Trigger, have created specific packages that you can install using npm. There are also organisations that maintain a directory of skills from various service providers.

The only question that remains is: what is the difference between AGENTS.md and SKILL.md?

Simply put, AGENTS.md is global. It provides persistent, global context that gets loaded every time by the agent. SKILL.md is called on-demand, loaded only when needed for specific tasks. Think about it this way: AGENTS.md is the sticky note on your monitor (which I hope you don't use to store your password), always visible. SKILL.md is a manual in your drawer which you only reach for when you actually need it.

Conclusion

Skills are not just a convenience feature for agents; they are an architectural primitive for building reliable, repeatable behaviour in systems powered by LLMs. They allow you to move intent and process out of fragile, one-off prompts into artefacts that agents can discover and apply when appropriate.

The key insight is that skills work best when paired with clear agent-level guidance. SKILL.md defines what an agent can do and how to do it, while AGENTS.md shapes when and why those skills should be used. Together, they shift away from ad-hoc reasoning toward retrieval-led execution, improving consistency and reducing missed steps or silent failures.

If you care about agents that behave predictably, evolve safely, and improve over time, skills are no longer optional but they are foundational.