How agent skills work: structure, loading, portability and limits

An agent skill is a folder of instructions, optionally with scripts and reference files, that teaches an agent how to do one kind of task well. The idea is modest. Instead of pasting the same long explanation into every conversation, or stuffing it into a system prompt that is always loaded, you package it once and let the agent pull it in when a task calls for it. The format that many agent tools now share is built around a file called SKILL.md. This page explains how a skill is structured, when it loads, how portable it really is, and where its authority stops.

Anatomy of a skill

A skill is a directory. Only one file is required; everything else is optional.

release-notes/
  SKILL.md            required: metadata and instructions
  scripts/
    collect.sh        helper the agent can run
  references/
    style-guide.md    longer material, read only when needed
  assets/
    template.md       files used in the output

SKILL.md opens with a small block of YAML front matter, followed by ordinary Markdown:

---
name: release-notes
description: Draft release notes from changes merged since the last tag.
  Use when asked for release notes, a changelog entry or a summary of
  what shipped. Not for marketing announcements.
---

# Release notes

1. Run scripts/collect.sh to list changes merged since the last tag.
2. Group them under Added, Changed, Fixed and Removed.
3. Follow references/style-guide.md for tone and length.
4. Mark anything you cannot tie to a specific change as "unverified".

The two required fields carry most of the weight. The name is a short, lowercase, hyphenated identifier. The description says what the skill does and when to use it, and it is the only part the agent sees before deciding whether to load the skill. Some tools read additional optional fields, such as a licence, compatibility notes or a list of tools the skill expects; check what your agent supports. The open specification is published at agentskills.io.

When a skill loads

Skills are designed around progressive disclosure: the agent pays for detail only when it needs it.

1. At start-up, the agent reads only the name and description of each installed skill, so a large collection costs very little context.
2. When a task matches a description, the agent reads the full body of that SKILL.md.
3. When the instructions point to a file, the agent opens that file, or runs a script and reads only its output. It never pulls in the whole folder.

Two practical consequences follow. First, the description is the trigger. A vague description ("helps with documents") loads at the wrong moments or not at all; a specific one names the task, the phrasings people use for it and the cases it does not cover. Second, keep the body lean. Put long reference material in separate files so it costs nothing until it is needed, and move deterministic work, such as parsing a file format, into scripts instead of asking the agent to do it in prose.

Skills, tools, prompts and MCP

Skills are often confused with the other ways of extending an agent. The difference lies in what each one provides.

They combine naturally. A skill can explain how to use a tool exposed by an MCP server, or wrap a command-line program in a script. MCP, skills or CLI tools compares the three when you have to choose, and turning a CLI into an agent skill walks through building one.

How portable skills really are

Because a skill is plain files, it moves easily: copy the folder, commit it to a repository, share it with a team. More and more agent tools read the same layout. The instructions travel well; the environment they assume does not always come along.

• Scripts assume an interpreter, a shell and an operating system. A Bash helper will not run unchanged where only PowerShell is available.
• Instructions may name tools that exist in one agent and not in another. "Use the browser tool" means nothing to an agent that has none.
• Optional fields are honoured unevenly. A field that restricts tools in one product may be ignored by the next.
• Paths and credentials differ between machines and between teams.

To keep a skill portable, describe the outcome rather than one product's tool names, declare dependencies at the top, prefer widely available interpreters for scripts, and test the skill in every agent you expect to run it.

Review a skill like code

A skill is an instruction the agent will follow with whatever access it already has, plus scripts it may execute. Installing one from a public collection deserves the scrutiny you would give a new dependency. Read it before you install it, and look for:

• Instructions telling the agent to skip confirmations, disable checks or hide what it did.
• Scripts that make network calls, read credentials or touch files outside the task's scope.
• A description broad enough to load during unrelated tasks and quietly change how they behave.
• Text in referenced files that addresses the agent with new instructions.

Pin the version you reviewed, keep skills under version control so every change shows up in a diff, and remove skills nobody uses. Reviewing community skills before you install them gives a fuller procedure.

A skill is not a permission

The most important limit is also the easiest to forget: a skill describes how to do something; it does not authorize anyone to do it. A SKILL.md that says "you may deploy to production" grants nothing. Whether the agent can deploy depends on the credentials it holds, the tools it has been allowed to call and the approvals its environment enforces. If a skill's instructions would be dangerous with the agent's current access, the fix is to narrow the access, not to reword the skill.

GoCux treats this as a rule rather than a convention: no reusable instruction ever stands in for a permission. Work is defined in a work order with a goal, a scope and acceptance criteria, and GoCux selects the skills that work needs; selecting a skill never widens the scope. Consequential actions, from sending something out to rewriting the agent's own instructions, wait until a teammate decides, and every step lands on a record the team can read. The agent skills documentation and the governance page describe how this works in practice.

Writing your first skill

• Pick one task you explain again and again, with a recognizable end state.
• Write the description first: what it does, when to use it, when not to.
• Keep the body to steps and rules; move long reference material to separate files.
• Move deterministic steps into scripts, and keep secrets out of the folder.
• Test with prompts that should load the skill and prompts that should not.
• Confirm that the agent's access, not the wording of the skill, is what keeps risky actions in check.
• Put the skill under version control and review changes the way you review code.