Publiquei as boas práticas de SolidJS como skill no skills.sh

Uso bastante o skills.sh no dia a dia. É prático poder gerenciar como skills o conhecimento passado aos agentes, e fui aumentando aos poucos para uso pessoal e da equipe.

As oportunidades de escrever SolidJS aumentaram e senti falta de um skill. Coisas como a reactivity quebrando por destructuring de props, ou situações em que se deve usar <For> em vez de .map() — estava ficando cansativo complementar o contexto toda vez.

Já que ia fazer, criei com o Claude Code e publiquei diretamente no skills.sh. Deixo aqui como registro do procedimento de publicação.

Criar o skill

Basta iniciar o /skill-creator e responder às perguntas para obter um rascunho.

/skill-creator

Para que serve o skill, quando deve ser acionado, o que se espera do output. Respondendo a essas três perguntas, um rascunho do SKILL.md é gerado. Incomparavelmente mais rápido do que escrever do zero.

Ajuste a description manualmente

Quando o rascunho sair, vale a pena sempre revisar a description. A precisão dela se traduz diretamente na precisão do trigger.

# Escrita vaga quase não aciona
description: SolidJS のヘルプ

# O que realmente uso
description: SolidJS のコードを書いたりレビューするためのベストプラクティス。
  createSignal, createEffect, createMemo, createStore, createResource,
  createContext, Show, For, Switch, SolidJS, solid-js が出てきたら使う。
  React パターンを Solid に変換する質問や、コンポーネントが更新されない
  バグのデバッグにも使う。

Não basta listar palavras-chave — incluir em que situações o skill será usado faz com que ele seja acionado mesmo em cenários implícitos.

Mantenha o SKILL.md em até 500 linhas

O SKILL.md é sempre carregado no contexto. Se ficar longo demais, acaba prejudicando outras tarefas. Por isso, adotei uma estrutura em que os detalhes ficam em references/ e são consultados apenas quando necessário.

## Ao usar SolidStart

Consulte [`references/solidstart.md`](references/solidstart.md) para detalhes.

Confirme a diferença com testes

O /skill-creator tem uma funcionalidade que executa with-skill e without-skill em paralelo para comparação.

Preparei três casos de teste.

Ao rodar de fato, sem skill o <For> e o createResource já eram razoavelmente utilizados. A diferença apareceu nos seguintes pontos.

No code review, com skill detectou como Critical o problema de que fazer destructure de props nos argumentos quebra a reactivity. Sem skill, passou batido.

Na criação do Todo, com skill sugeriu createStore + produce, enquanto sem skill parou em createSignal<Todo[]>.

Na busca assíncrona, com skill sugeriu o conjunto Suspense e ErrorBoundary. Sem skill, ficou na verificação manual de users.loading.

O bug de destructuring de props é conhecimento que o Claude já possui. Porém, o comportamento muda dependendo de haver ou não no skill o critério de julgamento de sempre apontar isso no review. Escrever skills para garantir que armadilhas específicas do framework sejam cobertas — essa foi a conclusão a que cheguei.

Publicar no skills.sh

Basta criar um repositório em conformidade com o padrão aberto do skills.sh. É a mesma estrutura de vercel-labs/agent-skills.

Estrutura do repositório

agent-skills/
├── LICENSE
├── README.md
└── skills/
    └── solidjs-best-practices/
        ├── SKILL.md
        └── references/
            └── solidstart.md

Ajustar o frontmatter

Antes de publicar, adicione license, metadata.author e metadata.version.

---
name: solidjs-best-practices
description: ...
license: MIT
metadata:
  author: mktbsh
  version: "1.0.0"
---

As regras de name são sutilmente rigorosas. Apenas letras minúsculas, números e hífens. Deve corresponder ao nome do diretório. Hífens no início ou no fim não são permitidos, nem hífens consecutivos.

Faça push depois de passar pela validação

npx skills-ref validate ./skills/solidjs-best-practices

Ele verifica de uma vez o formato do frontmatter e as regras de nomenclatura. Recomendo fazer push somente depois de passar por isso.

Escreva o README e está pronto

# agent-skills

## Skills

### solidjs-best-practices

Coleção de boas práticas para escrever e revisar código SolidJS.

## インストール

npx skills add mktbsh/agent-skills

Faça push para o GitHub e a publicação está concluída. É só isso.

Conclusão

A precisão da description e o processo de verificar diferenças com testes determinam a qualidade do skill. Se negligenciar qualquer um dos dois, acaba-se na situação de ter criado o skill sem saber se está fazendo efeito.

Quanto mais se concentra em know-how específico — aquele que trava se não souber — em vez de conhecimento genérico, mais o skill se torna eficaz.