# Nova Skill > Use quando alguém for criar, revisar ou corrigir uma skill deste marketplace — escrever um SKILL.md do zero, escolher o bundle certo, ajustar uma description que não está disparando, resolver erro do validador, ou publicar a skill para Cursor/Copilot/AGENTS.md. - Skill: `thiagopbraga/nova-skill` (Agent Skill) - Install (CLI): `npx skillmds@latest add thiagopbraga/nova-skill` - Raw SKILL.md: https://api.skillmd.com/api/skills/thiagopbraga/nova-skill/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: thiagopbraga (https://skillmd.com/u/thiagopbraga) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/thiagopbraga/nova-skill --- # Escrevendo uma skill para o skills-space ## O modelo mental Uma skill não é documentação. É **contexto que entra na cabeça do agente no momento certo e some depois**. O agente carrega apenas a `description` de todas as skills o tempo todo; o corpo só entra em contexto quando a descrição casa com a tarefa. Isso define as duas responsabilidades, e elas são bem diferentes: - **`description`** — precisa fazer o agente *decidir carregar*. É um problema de recall. - **corpo** — precisa fazer o agente *acertar*. É um problema de instrução. Quase toda skill que "não funciona" na verdade nunca foi carregada. Suspeite da description antes de reescrever o corpo. ## Passo 1: confirme que precisa existir Não escreva uma skill quando: - o agente já acerta sem ela (teste antes: rode a tarefa sem skill nenhuma); - é uma regra sempre-válida do repositório — isso é `CLAUDE.md`, não skill; - é conhecimento de uso único — isso é uma mensagem, não skill. Escreva quando existe um procedimento **repetível**, **específico do time** e que o agente **erra sozinho**. Se você não consegue nomear o erro que ela evita, ainda não há skill. ## Passo 2: escolha o bundle Skills vivem dentro de um bundle, que é a unidade que o time instala: ``` plugins//skills//SKILL.md ``` Prefira sempre um bundle existente. Crie um novo só quando um time diferente for dono das skills e o público for outro — bundle demais faz o time instalar cinco coisas em vez de uma. Se criar, escreva também `plugins//.claude-plugin/plugin.json` com `name` (igual ao diretório), `description`, `version` e `author`. ## Passo 3: escreva a description Este é o trabalho de verdade. Formato: ``` Use quando — . ``` Coloque as **palavras que o usuário realmente digita**, não os termos internos do time. Se o pessoal fala "subir pra prod", a description precisa conter "subir pra prod", não apenas "deploy em produção". ```yaml # ruim — descreve a skill, não o gatilho; nunca vai disparar description: Padrões de acessibilidade do design system. # bom — nomeia as situações que devem carregá-la description: Use quando for criar ou revisar componentes de UI — modal, dropdown, formulário, tabela — ou quando alguém perguntar sobre foco, leitor de tela, contraste, navegação por teclado ou aria-*. ``` Erros que o validador não pega, mas que matam a skill: - descrição genérica demais → dispara em tudo e polui o contexto; - descrição estreita demais → só dispara na frase exata que você imaginou; - descrever o *conteúdo* ("Guia de X") em vez da *situação* ("Use quando X"). ## Passo 4: escreva o corpo Escreva para um colega competente que não conhece as convenções do time. Regras: - **Imperativo, não descritivo.** "Rode `npm run lint` antes de commitar", não "o projeto usa lint". - **Exemplo certo e errado lado a lado.** Um par ruim/bom ensina mais que três parágrafos. - **Diga o que *não* fazer** quando existe um atalho tentador e errado. - **Corte o óbvio.** Se o agente já faz sem instrução, cada linha extra só compete por atenção com o que importa. - **Determinismo vira script.** Se o passo é mecânico e sempre igual, ponha um script em `scripts/` ao lado do `SKILL.md` e mande executá-lo. É mais barato e não varia. Arquivos de apoio ficam no diretório da skill e são lidos sob demanda: ``` skills/minha-skill/ SKILL.md references/tabela-completa.md ← só carrega se o corpo mandar abrir scripts/checar.mjs ``` Mantenha o `SKILL.md` abaixo de ~500 linhas. Passou disso, mova detalhe para `references/` e deixe o corpo apontar para lá. ## Passo 5: preencha o metadata ```yaml metadata: owner: "@thiagopbraga" # quem responde quando quebra. Obrigatório. stability: experimental # stable | beta | experimental targets: [claude] # onde publicar tags: [ci, deploy] ``` Sobre `stability`: comece em `experimental`. Suba para `beta` quando outra pessoa já usou, e para `stable` quando o time depende dela e você aceita ser cobrado por regressão. Sobre `targets`: **deixe em `[claude]` a menos que tenha um motivo.** Claude Code carrega skill sob demanda; Cursor e Copilot carregam de forma bem mais agressiva. Exportar tudo para todo lugar enfia o catálogo inteiro no contexto de cada prompt e degrada todos os agentes. Exporte para `cursor`, `copilot` ou `agents` só quando o time realmente usa aquele agente para aquela tarefa. Se exportar: o corpo é copiado literalmente, então **caminhos relativos para `references/` e `scripts/` quebram**. Skills multi-target precisam ser autocontidas. ## Passo 6: valide e gere ```bash npm run validate # erros e avisos npm run build # regenera marketplace.json, CATALOG.md, docs/ e dist/ ``` Commite os artefatos gerados junto. O CI roda `npm run check` e reprova o PR se `dist/`, `docs/` ou `marketplace.json` estiverem fora de sincronia com `plugins/`. ## Passo 7: teste de verdade Validador confere formato, não eficácia. Antes de abrir o PR: 1. Abra uma sessão nova (contexto limpo). 2. Digite a tarefa **como um colega digitaria** — não cite o nome da skill. 3. Confirme que ela carregou. 4. Se não carregou, o problema é a `description`. Volte ao passo 3. 5. Se carregou e o resultado ficou errado, o problema é o corpo. Volte ao passo 4. Rodar direto com um comando explícito prova apenas que o arquivo existe — o gatilho continua sem teste.