Como criar uma skill de formulários no Claude Code: regras de label, validação, mensagem de erro e autocomplete

Fala aí, beleza? Pede um formulário de cadastro pra IA e repara no que costuma vir: placeholder no lugar de label, asterisco solto sem explicação e campo marcado como inválido antes de tu digitar qualquer coisa 😛

A saída é uma skill de formulário no Claude Code: um arquivo SKILL.md dentro de .claude/skills/<nome>/ (projeto) ou ~/.claude/skills/<nome>/ (pessoal), com frontmatter YAML no topo e as regras em Markdown embaixo

A description funciona como gatilho, e as regras vêm de norma, não de achismo: WCAG 1.3.5, 3.3.1, 3.3.2 e 3.3.3, mais os tokens de autocomplete da especificação HTML

Ela não substitui tua skill de UI geral, ela complementa, cuidando só de campo, validação, erro e autocomplete. É o mesmo padrão da skill de design para dashboards: uma skill por tipo de tela 🙂

O que você precisa antes de criar a skill

Tu precisa do Claude Code e de uma decisão: a skill vale só pra você ou pro projeto inteiro?

• Skill de projeto: .claude/skills/<nome>/SKILL.md, fica junto do código
• Skill pessoal: ~/.claude/skills/<nome>/SKILL.md, vale pra você em qualquer projeto
• Noção da estrutura: o SKILL.md tem duas partes, frontmatter YAML no topo e instruções em Markdown abaixo

Tudo isso está na documentação oficial de Skills do Claude Code

E uma notícia boa: não precisa reiniciar nada

Quando tu adiciona, edita ou remove uma skill nessas pastas, o Claude Code detecta a mudança na sessão atual. Dá pra ir ajustando a regra e testando na mesma conversa, massa né?

Passo a passo: como montar a skill de formulários

Bora montar por partes, beleza?

1. Crie a pasta e o arquivo SKILL.md

No projeto, a estrutura fica assim:

.claude/skills/formularios/SKILL.md

O nome da pasta importa, porque se tu não preencher o campo name, ele vira o nome da skill e do comando

Erro comum deste passo: usar maiúscula ou espaço no nome, tipo Formularios Acessiveis. O name aceita só letras minúsculas, números e hífens, com no máximo 64 caracteres. Vai de formularios ou formularios-acessiveis

2. Escreva o frontmatter com name e description

No Claude Code todos os campos do frontmatter são opcionais, e o único recomendado é o description

Por quê? Porque é ele que diz o que a skill faz e quando usar, e o Claude compara esse texto com o teu pedido pra decidir se carrega a skill sozinho

---
name: formularios
description: Regras para criar e revisar formulários HTML: label associado ao campo, obrigatório indicado em texto, validação com aria-invalid, mensagens de erro e tokens de autocomplete. Use ao criar ou revisar form, input, select, textarea, telas de cadastro, login, checkout ou recuperação de senha.
---

A description merece uma seção só dela (logo abaixo), porque é ali que mora o risco de colidir com a skill de UI geral

3. Adicione a regra de label

O critério WCAG 3.3.2 Labels or Instructions (Nível A) pede rótulo ou instrução sempre que o conteúdo exige entrada do usuário, e isso inclui identificar os campos obrigatórios

Na prática, duas técnicas do WCAG resolvem: a H44, que associa o <label> ao campo com for igual ao id, e a G83, que indica o obrigatório em texto

## Label
- Todo campo tem um <label> com o atributo for igual ao id do campo (WCAG H44)
- Campo obrigatório é indicado em texto dentro do label, ex: "(obrigatório)" (WCAG 3.3.2, G83)
- Placeholder não substitui label

O HTML esperado fica nessa linha:

<label for="email">E-mail (obrigatório)</label>
<input id="email" autocomplete="email">

Erro comum deste passo: marcar o obrigatório só com asterisco ou só com cor vermelha. A G83 fala em descrição em texto, então escreve isso na regra com todas as letras

4. Adicione a regra de validação e do momento do erro

Aqui entra a técnica ARIA21: aria-invalid marca o campo que falhou na validação, e ele não deve ser true antes de a validação acontecer

E o momento de mostrar o erro? Ao sair do campo, ao enviar, enquanto digita?

Se liga: o WCAG não define isso. É decisão de design do teu projeto, e a skill é justamente o lugar pra deixar essa decisão escrita, pra IA não escolher cada vez de um jeito

## Validação
- aria-invalid="true" só depois que a validação rodar (WCAG ARIA21)
- Nunca renderize o campo já com aria-invalid="true" no carregamento da página
- Momento de validar neste projeto: [preencha com a decisão do time, ex: ao enviar o formulário]

Erro comum deste passo: campo que nasce marcado como inválido antes de o usuário interagir. A pessoa abre a tela e já leva bronca sem ter digitado nada xD

5. Adicione a regra de mensagem de erro

O WCAG 3.3.1 Error Identification (Nível A) diz que, se um erro de entrada é detectado automaticamente, o item com erro é identificado e o erro é descrito em texto

O WCAG 3.3.3 Error Suggestion (Nível AA) vai além: quando possível, o usuário recebe sugestão de como corrigir

## Mensagem de erro
- Diga QUAL campo tem erro e O QUE está errado, em texto (WCAG 3.3.1)
- Sempre que der, diga como corrigir (WCAG 3.3.3)
- Cor ou ícone sozinhos não contam como mensagem de erro

No HTML, a diferença entre "Campo inválido" e uma mensagem útil fica assim:

<label for="cep">CEP (obrigatório)</label>
<input id="cep" autocomplete="postal-code" aria-invalid="true">
<p>CEP incompleto: confira os números do seu CEP</p>

6. Adicione a regra de autocomplete

O WCAG 1.3.5 Identify Input Purpose (Nível AA, desde o WCAG 2.1) pede que o propósito de cada campo com dados do usuário possa ser determinado programaticamente. Em HTML, quem faz isso é o atributo autocomplete

Pela especificação HTML do WHATWG, o autocomplete aceita on, off ou um ou mais tokens de autofill válidos

## Autocomplete
- Todo campo com dado do usuário usa o token correto (WCAG 1.3.5)
- Nome: name, given-name, family-name
- Contato: email, tel
- Endereço: street-address, address-line1, address-level1, address-level2, postal-code, country
- Nascimento: bday
- Cartão: cc-number, cc-exp, cc-csc
- Senha no cadastro ou na troca de senha: new-password
- Senha no login: current-password
- Código de uso único (2FA): one-time-code
- Não use autocomplete="off" como forma de bloquear preenchimento em login

A separação de senhas é a que mais confunde: new-password é pra criar conta ou trocar senha, current-password é pra senha que já existe e one-time-code é pro código do 2FA, como explica a documentação de autocomplete da MDN

Erro comum deste passo: confiar no autocomplete="off" num campo de login. Os navegadores podem ignorar o off em alguns campos, como os de login, pra dar mais controle ao usuário

Como escrever a description para não colidir com a skill de UI geral

A description precisa ser específica de formulário e deixar claro o que NÃO é com ela

O motivo: o Claude compara a description com o pedido pra decidir se carrega a skill. Se tua skill de formulário e tua skill de UI geral falam a mesma coisa, as duas competem pelo mesmo pedido

E tem um detalhe: a documentação não detalha como o Claude desempata duas skills parecidas. Então o jeito seguro é escrever descriptions específicas e excludentes, sem contar com mágica

1. Compare a description vaga com a focada

A vaga dispara junto com qualquer skill de interface:

---
name: formularios
description: Regras de interface para o projeto.
---

A focada cita os termos que aparecem num pedido de formulário de verdade:

---
name: formularios
description: Regras para formulários HTML: label associado ao campo, obrigatório indicado em texto, validação com aria-invalid, mensagens de erro e tokens de autocomplete. Use ao criar ou revisar form, input, select, textarea, telas de cadastro, login, checkout ou recuperação de senha.
when_to_use: Não use para layout de página, cores, tipografia ou componentes sem campo de entrada, que ficam com a skill de UI geral.
---

Erro comum deste passo: description genérica como "regras de interface". Ela não diz quando usar, e aí a skill de formulário briga com a de UI geral em todo pedido de tela

2. Coloque o caso principal primeiro

No Claude Code, a soma da description com o when_to_use é cortada em 1.536 caracteres na listagem de skills

Por isso "formulários HTML" e os termos de input vêm logo no começo, e as exclusões vêm depois. Se algo for cortado, que seja o detalhe, não o gatilho

3. Ajuste também a skill de UI geral

Vale o caminho inverso: na description da skill de UI geral, avise que formulário e campo de entrada ficam com a skill formularios

4. Se a colisão persistir, desligue a invocação automática

Com disable-model-invocation: true no frontmatter, o Claude não carrega a skill sozinho. Ela passa a rodar só quando tu chama /formularios

---
name: formularios
description: Regras para formulários HTML: label, obrigatório em texto, aria-invalid, mensagens de erro e autocomplete.
disable-model-invocation: true
---

É menos automático, mas tu ganha controle total de quando as regras entram

E o allowed-tools? Ele lista ferramentas que o Claude pode usar sem pedir permissão, só durante o turno em que a skill é invocada. Na próxima mensagem tua, essa liberação acaba. Numa skill que só traz regras de escrita, como essa, tu pode simplesmente não usar o campo

Como verificar se a skill está funcionando

Pede um formulário de cadastro na sessão e confere o resultado contra as próprias regras da skill

Como o Claude Code detecta a skill na sessão atual, não precisa reiniciar. Confere:

• Cada <label> tem for igual ao id do campo
• O obrigatório aparece em texto, não só em asterisco ou cor
• Nenhum campo nasce com aria-invalid="true", ele só aparece depois da validação
• A mensagem de erro diz qual campo errou e o que está errado, em texto, com sugestão de correção quando der
• Os campos usam os tokens certos: email, given-name, postal-code e por aí vai
• Senha do cadastro com new-password, nunca com current-password

Depois testa a invocação direta: roda /formularios e pede o mesmo formulário, pra garantir que a skill também responde quando chamada pelo nome

Se algum item falhar, ajusta a regra no SKILL.md, de preferência deixando ela mais explícita, e pede de novo na mesma sessão

Outro exemplo de regra de domínio numa skill

A ideia de empacotar regra de domínio numa skill não é só pra interface. No canal tem um vídeo sobre a ub-mode, que leva essa ideia de regra empacotada pro lado do código

Próximo passo: uma skill por tipo de tela

Se a skill ficou em .claude/skills/formularios/, versiona essa pasta junto com o repositório. Assim o time inteiro gera formulário com a mesma regra de label, de erro e de autocomplete, sem cada um explicar tudo no prompt

Depois é repetir o padrão: tabela, e-mail, página de listagem… cada tipo de tela com decisões próprias ganha a sua skill, com description específica e regra amarrada em norma, igual fizemos com os dashboards

Até o próximo post! 😀

Perguntas frequentes

A skill de formulário do Claude Code funciona só com HTML puro ou dá pra usar em qualquer framework?

As regras da skill são escritas em cima de atributos HTML (label, for, aria-invalid, autocomplete), então valem pra qualquer stack que termine gerando esse HTML na tela, seja React, Django ou PHP. O que muda de projeto pra projeto é só a sintaxe de implementar a regra, não a regra em si.

Preciso ter a skill de dashboards pra usar a skill de formulário?

Não, as duas são independentes e cada uma cuida de um tipo de tela. A skill de formulário cobre campo, validação, erro e autocomplete, e a de dashboards cuida de outro recorte, sem uma depender da outra pra funcionar.

Quer aprender mais sobre inteligência artificial e programação na prática? Conheça o canal Hora de Codar no YouTube e acompanhe os próximos vídeos.