Anatomy of an agent skill: name, description, body

An agent skill is a versioned folder holding an instruction file and the resources needed to run it; the rest is convention. The real minimum is a name and a description that says when to use it.

Minimum anatomy

• Name: kebab-case, stable, matching the folder name.
• Description: what it does and when to invoke it, using the words a user would type.
• Body: steps, commands and rules, in the order they run.
• Resources: reference files and scripts, loaded only when needed.

The frontmatter

---
name: eneui-blog
description: Produce or repair an EneUI blog article (Italian and English pair)
  end to end: JSON shape, measured-data contract, English rewrite rules,
  validation commands, covers and sitemap. Use whenever writing a post
  under data/blog/.
---

# EneUI blog article, end to end

One post = one file: data/blog/.json, holding the Italian source and
the English edition. Never create separate EN files.
## Fast path

Two fields, no absolute path. The description is deliberately long: it carries the verbs that trigger invocation, such as write, rewrite, translate and check a post.

The description is the routing

The client reads only name and description until it decides to open the skill. If the description does not name the task, the skill is never chosen, even with a perfect body. Spend lines here and save them elsewhere.

The body executes, it does not narrate

In the eneui-blog skill the body holds the file path, the validation commands and the prohibitions, for example never writing JSON with PowerShell and never inventing a count. Every line either runs or checks: a summary of the documentation ages twice.

Progressive disclosure

The body stays short and the detail lives in separate files, read only when needed. The blog skill points at docs/SEO-1000-PLAN.md and docs/EN-REWRITE.md without copying them: 82 lines instead of three whole documents in context.

What breaks a skill

• A renamed command left in the text: the skill fails without a clear error.
• No validation step: the agent declares finished what it never checked.
• Duplicated documentation: two sources diverge and the model picks the wrong one.

The catalogue

An agent building UI can start from dqnamo agent dock, or browse the 111,985 components and the 1,556 blocks. The skill the server publishes is on /agents and the endpoint on /mcp.

The limitation

A skill is text: it grants no permission and blocks no command. If the client does not limit the shell, the skill can only ask for care. The description also spends context in every session, so each added trigger takes room from the others.

Where to continue

Prompt writing is in prompts for agents, not chat; the context is in what an AI agent is. For the risks read securing a coding agent, and for component documentation how to document components.