The Agent Skills Standard Explained — and How to Write Your First Skill

Something is consolidating in the AI agent ecosystem right now, and it is happening in public on GitHub. In June 2026, repositories cataloguing agent skills are accumulating tens of thousands of stars within weeks — VoltAgent's awesome-agent-skills (~26k★) and scientific-agent-skills from K-Dense-AI (~29k★) among them — while IBM Research shipped CUGA, a working harness with two dozen runnable examples of agents built from reusable skills. The pattern is unmistakable: the loose idea of "giving an agent a capability" is hardening into a shared Agent Skills standard.

If you build with agents, this matters for a practical reason. A standard means the skill you write today is more likely to be portable, discoverable, and reusable tomorrow. This guide explains what an agent skill is, what the emerging standard actually standardizes, and then walks you through writing your first skill — grounded in a real, first-party example rather than a toy.

What is an agent skill? What is the "Agent Skills standard"?

An agent skill is a self-contained, reusable unit of capability or knowledge that an agent can load when — and only when — it is relevant. Instead of stuffing every instruction, workflow, and reference into one giant system prompt, you package a focused competency into a skill: a clear description of when to use it, the instructions for how, and any supporting files it needs. The agent's runtime decides, based on the description, whether to pull that skill into context for a given task.

The "Agent Skills standard" is not a single specification handed down by one vendor. It is a convergent format emerging from practice across many high-star repositories and harnesses. What they increasingly agree on is the shape of a skill:

A definition file (commonly a SKILL.md) that carries metadata and the skill's instructions.
A trigger description — a short, carefully written summary of what the skill does and when it applies, which the runtime uses for routing.
Supporting files — references, scripts, data, or examples the skill can pull in on demand instead of loading everything up front.

That this structure is appearing independently across awesome-agent-skills, scientific-agent-skills, and harnesses like IBM's CUGA is the news. When the same anatomy crystallizes in many places at once, you are watching a standard form in real time — and writing to that shape is how you future-proof your work.

Anatomy of a skill

Let's make the structure concrete. The clearest way to understand a skill is to open a real one. Clawvard's own open nuwa-skill repository distills a set of public figures into reusable "thinking" skills, and its layout is a faithful example of the converging standard.

The SKILL.md / definition

The heart of a skill is its definition file. In nuwa-skill, each skill is a SKILL.md that opens with YAML frontmatter and then contains the skill's actual instructions in Markdown. The frontmatter carries machine-readable metadata — a name, a description, a version, and provenance fields like when it was last updated. The body is plain Markdown that any agent can read.

This "metadata header + Markdown body" pattern is exactly why skills travel well: the file is human-readable, diff-able in git, and copy-pasteable into almost any agent's instructions. nuwa-skill's README makes the portability explicit — because SKILL.md is pure Markdown, you can symlink it into a runtime's skills directory or drop its contents straight into another agent's system prompt.

The trigger description and routing

The single most important field to get right is the description, because it is what the runtime reads to decide whether your skill is relevant. In nuwa-skill, the description does double duty: it summarizes who the skill represents and lists explicit trigger phrases — the kinds of requests that should activate it. A vague description means your skill is loaded when it shouldn't be (wasting context) or skipped when it should fire (silent failure). Treat the description as routing logic, not marketing copy: name the concrete situations, requests, and keywords that should pull the skill in.

Supporting files

A good skill keeps its definition lean and pushes detail into supporting files loaded on demand. nuwa-skill is a strong illustration of this layered approach. Around each SKILL.md it keeps:

meta.yaml — richer machine-readable metadata and source provenance.
references/ — deeper research and intermediate artifacts the skill can pull in when needed.
sources/ — the raw data the skill was built from.
candidates.md and evolution.md — a staging area for unverified signals and a dated changelog of how the skill has evolved.

The design principle behind this layout is worth stealing regardless of your runtime: a stable layer (the verified SKILL.md), a candidate layer (new, not-yet-validated material), and a history layer (a log of changes). New observations don't overwrite the trusted skill — they enter the candidate area first and are only promoted once they hold up. That discipline is what keeps a frequently-updated skill from rotting.

How do you write your first agent skill? A grounded walkthrough

Here is a step-by-step path to your first skill, mirroring the structure above.

Pick one narrow capability. Resist the urge to build a do-everything skill. The best skills are focused: "review Python for security issues," "summarize a research paper in our house format," "apply this figure's analytical lens." Narrow scope makes the trigger description sharp and the behavior predictable.

Create the folder and SKILL.md. Make a directory named for the skill and add a SKILL.md. Start it with YAML frontmatter:

---
name: my-first-skill
description: |
  What this skill does, in one or two sentences. Then list the
  concrete triggers: the requests, keywords, or situations that
  should activate it.
version: 0.1
---

Write the description as routing logic. This is where most skills succeed or fail. State plainly what the skill does and enumerate when it applies. If a teammate couldn't tell from your description whether the skill should fire on a given request, the runtime can't either.
Write the instructions in the body. Below the frontmatter, in plain Markdown, tell the agent exactly how to perform the capability — the steps, the rules, the format of the output, and importantly the boundaries: what the skill should not do. nuwa-skill elevates this into a design principle — every skill carries an explicit "honest boundary" section stating where its confidence is low. A skill that hides its limits, as the repo puts it, isn't worth trusting.
Add supporting files only as needed. If the skill needs reference material, examples, or data, add them alongside SKILL.md and reference them from the body so they load on demand. Keep the definition itself lean.
Version and iterate. Give the skill a version, and when you improve it, log the change rather than silently overwriting. The candidate-then-promote pattern keeps quality from regressing as the skill grows.

Skills frequently run with real privileges — file access, tools, credentials. That makes capability scope a security concern from line one, which is exactly why disciplined skill design and agent security are two sides of the same coin. If your skill touches secrets or processes untrusted input, read our companion guide on how to secure an AI agent before you ship it.

Where to find good agent skills

The fastest way to learn the format is to read skills that already work. Two community catalogues are worth bookmarking:

awesome-agent-skills (VoltAgent) — a broad, fast-growing index of agent skills across domains.
scientific-agent-skills (K-Dense-AI) — skills focused on scientific and research workflows.

For a sense of how skills compose into full applications, IBM Research's CUGA examples walk through building real agentic apps from reusable parts. And for a complete, opinionated first-party example with the stable/candidate/history layering described above, Clawvard's nuwa-skill repository is a working reference you can read end to end.

FAQ

Are agent skills portable across runtimes?

Increasingly, yes — and that is the whole point of a converging standard. Because the dominant format is a Markdown definition with a metadata header, a well-written skill can often be moved between runtimes, or even pasted directly into another agent's instructions, with little change. The closer you stick to the common shape — SKILL.md, a clear description, supporting files on demand — the more portable your work is.

How is a skill different from a tool?

A tool is a single function the agent can call (send an email, query a database). A skill is a packaged competency: instructions, know-how, and references that tell the agent how and when to accomplish something — and it may orchestrate several tools along the way. Roughly: tools are verbs the agent can execute; skills are the playbooks that decide which verbs to use, when, and how.

Do I need a standard to write one?

No — you can write a useful skill today with nothing but a SKILL.md and a good description. But writing to the emerging standard is cheap insurance: it makes your skill discoverable in community catalogues, portable across runtimes, and legible to other builders. Follow the common shape now and you avoid a rewrite later.

Takeaways

An agent skill is a focused, reusable unit of capability with a clear "when to use it" description and supporting files loaded on demand.
The Agent Skills standard isn't one vendor's spec — it's a convergent format (definition file + trigger description + supporting files) crystallizing across high-star repos and harnesses right now.
The description is routing logic. Getting it sharp is what makes a skill fire at the right time.
Borrow nuwa-skill's discipline: a stable / candidate / history layering and an explicit honest-boundary section keep a skill trustworthy as it evolves.
Skills run with privileges — design their scope with security in mind from the start.

Ready to build? Start with one narrow capability, study a catalogue or two, and model your layout on a real example. Then pair it with sound agent security practices and follow the Clawvard blog as the Agent Skills standard continues to take shape.