Agent skill — Shadwire

Sem contexto, um agente que escreve ERB inventa coisas: passa icon: para um botão, chama ui_carousel num app que não tem o carousel instalado ou escreve bg-blue-500 onde já existe um token. A skill ensina ao agente o fluxo de trabalho e as convenções. Os detalhes (nomes de componentes, variantes, argumentos, helpers) ela manda o agente perguntar à CLI, para que as respostas batam com o seu app.

npx skills add edumoraes/shadwire

O instalador skills funciona com Claude Code, Codex, Cursor, OpenCode, Gemini CLI e cerca de vinte outros agentes. O código da skill fica em skills/shadwire/ no repositório.

A skill não lista componentes

Se a skill listasse os componentes e as variantes, a lista ficaria desatualizada no seu primeiro add, e nada avisaria. Em vez disso, ela carrega a saída do bin/shadwire status --json no contexto do agente e pede que ele leia isso antes de qualquer coisa.

## Current Project Context

```!
bin/shadwire status --json 2>/dev/null || bundle exec shadwire status --json 2>/dev/null || …
```

Esse comando sempre devolve um JSON válido. Três campos são os que mais pesam no que o agente escreve:

Campo	Por que importa
`installed[].helpers`	Os métodos ui_* que existem neste app. Chamar o helper de um componente não instalado levanta NoMethodError.
`stack.importmap`	Se os componentes interativos podem funcionar. 29 dos 57 componentes trazem um controller Stimulus.
`cli.binstub`	Se `bin/shadwire` já existe. Se for falso, o agente roda o `init` antes de qualquer coisa.

No repositório do Shadwire, o CI confere se todo helper e comando citado na skill ainda existe, e roda do início ao fim o fluxo que ela descreve. Se a skill ficar desatualizada, o build quebra.

O que tem nela

Arquivo	Conteúdo
`SKILL.md`	Princípios, as regras mais importantes, a tabela para escolher um componente e o fluxo de trabalho. Carrega o bin/shadwire status --json como contexto do projeto.
`cli.md`	Referência de cada comando e flag, o formato do payload JSON e como interpretar erros e códigos de saída.
`theming.md`	Onde ficam os tokens, dark mode por classe, como mudar o tema, como adicionar um token e como não perder edições nas atualizações.
`rules/composition.md`	Subcomponentes como helpers aninhados, itens dentro do grupo, título obrigatório em overlays, Stimulus.
`rules/styling.md`	Tokens semânticos, qual classe prevalece, como passar atributos HTML, convenções de utilitários do Tailwind.
`rules/forms.md`	Os componentes de field, o estado de validação, o uso com form_with e como escolher o controle.
`rules/icons.md`	lucide-rails, nomes kebab-case, tamanhos e quando o ícone precisa de rótulo acessível.

O SKILL.md é o ponto de partida, e os outros arquivos são referências para as quais ele aponta. As mesmas regras aparecem neste site em Composição, Estilização, Formulários e Ícones.

O fluxo que ela ensina

bin/shadwire status --json      # 1. what already exists in this app
bin/shadwire search modal       # 2. find the component
bin/shadwire info dialog --json # 3. read the API before writing ERB
bin/shadwire add dialog --yes   # 4. install it
bin/shadwire status --json      # 5. confirm the new helpers

info --json devolve os nomes dos helpers, as variantes e os tamanhos. É o passo que os agentes mais pulam, e sem ele acabam refazendo o componente com divs e classes utilitárias.

Confie no código de saída

Um código de saída diferente de zero quer dizer que algo não foi aplicado (geralmente um bundle add), e a mensagem diz como resolver. A skill orienta o agente a parar nesse ponto em vez de seguir como se tivesse dado certo.

Permissões

O frontmatter da skill declara as ferramentas de que ela precisa:

---
name: shadwire
description: Manages shadcn/ui components in Ruby on Rails apps via the shadwire CLI…
user-invocable: false
allowed-tools: Bash(bin/shadwire *), Bash(./bin/shadwire *), Bash(bundle exec shadwire *), Bash(shadwire *)
---

O allowed-tools só vale no turno em que a skill é carregada. Para parar de vez com os pedidos de permissão, adicione uma regra no .claude/settings.json do app:

{
  "permissions": {
    "allow": ["Bash(bin/shadwire *)"]
  }
}

O user-invocable: false é de propósito: você não chama essa skill diretamente. O agente a carrega quando está mexendo em UI num app Rails que tem shadwire.json.

Agentes sem a skill

Nem todo agente aceita skills. O mesmo catálogo também é publicado em texto simples, no formato llms.txt: um índice que diz quando usar cada componente e um arquivo com a API completa. Dá para colar qualquer um dos dois no contexto de um modelo.