Campos do frontmatter
Dois campos são obrigatórios e o resto é opcional. As restrições abaixo são as que um validador aplica, e por isso skills falham por motivos que parecem cosméticos, como uma letra maiúscula no nome.
| Campo | Obrigatório | Restrição |
|---|---|---|
name | Obrigatório | 1 to 64 characters. Lowercase a-z, 0-9 and hyphens only. No leading or trailing hyphen, no consecutive hyphens. Must match the parent directory name. |
description | Obrigatório | 1 to 1024 characters. Must say what the skill does and when to use it, with keywords an agent can match against a task. |
license | Opcional | A license name, or the name of a bundled license file. Recommended to keep it short. |
compatibility | Opcional | Up to 500 characters. Only include it when the skill has real environment requirements, such as a target product, system packages or network access. |
metadata | Opcional | A map of string keys to string values for anything the spec does not define. Use distinctive key names to avoid collisions. |
allowed-tools Experimental | Opcional | A space separated string of pre-approved tools, for example Bash(git:*) Read. Support varies between agent implementations. |
Estrutura de diretórios
Só o SKILL.md é obrigatório. Os outros diretórios são convenção e existem para que material grande fique fora do contexto do agente até ser necessário.
| Caminho | Obrigatório | Para que serve |
|---|---|---|
SKILL.md | Obrigatório | Frontmatter plus the instructions themselves. |
scripts/ | Opcional | Executable code the agent can run. |
references/ | Opcional | Documentation loaded on demand, not up front. |
assets/ | Opcional | Templates, images, data files. |
Divulgação progressiva e orçamento de contexto
Skills carregam em três etapas. É isso que decide se uma biblioteca grande é usável, porque a primeira etapa é paga por cada skill instalada em cada sessão.
| Etapa | Custo | Carrega | Contém |
|---|---|---|---|
| Metadata | around 100 tokens | Loaded at startup for every installed skill | name and description only |
| Instructions | under 5,000 tokens recommended | Loaded when the skill is activated | the whole SKILL.md body |
| Resources | as needed | Loaded only when the task requires them | files under scripts/, references/ and assets/ |
Regras que valem decorar
- Keep SKILL.md under 500 lines and move detail into references/.
- Keep file references one level deep from SKILL.md.
- The name must match the directory name, so renaming a skill means renaming both.
- Most skills do not need compatibility. Add it only when the environment really matters.
Valide antes de publicar
A biblioteca de referência checa frontmatter e convenções de nome, o que pega os erros que de outro jeito aparecem como uma skill que simplesmente nunca carrega.
skills-ref validate ./my-skillFontes
Todas as restrições desta página vêm da especificação publicada, lida na data indicada. Confira a fonte antes de depender de um campo em produção.
Agent Skills specification Última revisão: 2026-08-05