Criar Skill

Criar uma skill nova

Este repositório é público (luizsiqueira-eng/skills) e alimenta três lugares ao mesmo tempo:

Por isso catálogo e pacote têm que subir juntos — ver a etapa 5.

1. Levantar o fluxo real (não inventar)

Skill boa é fluxo que já existe e funciona. Antes de escrever:

• Pergunte ao autor como ele faz hoje, passo a passo, e onde costuma dar errado.
• Se o fluxo já existir em alguma skill interna do ambiente do autor (skills privadas de projeto ou ~/.claude/skills/), leia primeiro e use como matéria-prima — e neutralize tudo dela.
• Se ele mandar uma palestra, um PDF ou um print, extraia o fluxo dali.
• Não pergunte o que der para descobrir lendo o repositório.

2. Neutralizar (regra que não se negocia)

Nada de empresa, cliente ou instância dele pode ir para o público:

Antes de publicar, rode a checagem:

# nome do autor, empresa, produtos, sistemas, cidades, colegas, ids de tracker — ajuste a lista ao seu caso
grep -rniE "<nome-da-empresa>|<sigla>|<prefixo-do-tracker>-[0-9]|<dominio-da-empresa>|customfield_[0-9]|<nomes de sistemas internos>|<nomes de colegas>|meus times" skills/ README.md skills.json bin/

Só pode voltar vazio. A lista é sua e cresce: toda vez que um termo interno escapar, entra aqui. Menções genéricas a ferramentas de mercado (Jira, Trello, Slack, Discord) como exemplo são aceitáveis.

3. Escrever a skill

Pasta: skills/<nome>/SKILL.md — nome em inglês, kebab-case, curto, que descreva o que a skill faz (git-flow-delivery, não fluxo-1 nem luiz-skill). É o nome que a pessoa digita no npx.

Frontmatter — as duas linhas mais importantes da skill:

---
name: <igual ao nome da pasta>
description: "O QUE a skill faz, denso e específico (o vocabulário que o agente vai casar), + QUANDO invocar. Uma frase só."
---

A description é o que faz o agente carregar (ou não) a skill: cite os termos que a pessoa usaria (branch, commit, PR, release) e termine com "Invocar quando/sempre que…". Sem ela boa, a skill nunca é acionada.

Corpo — o que funciona na prática:

• Título # com o nome legível, e um parágrafo dizendo a tese do fluxo.
• Seções numeradas na ordem de execução (## 1. Branch, ## 2. Commit, …).
• Tabelas para decisões (situação → ação) e comandos prontos para copiar.
• Marque as regras rígidas em negrito ("1 branch = 1 commit — sempre") e explique o porquê em uma linha; agente sem o porquê improvisa.
• Diga também o que não fazer e onde parar (ex.: "no máximo 1 retry, depois reporte").
• Onde exige julgamento humano, mande perguntar em vez de decidir.
• Termine com ## Checklist rápido (caixas) e ## Adaptando ao seu time (tabela dos poucos pontos que variam entre times: prefixo do card, nomes de branch, status, canal).
• Integrações opcionais (Jira, Linear…) em seção própria marcada como opcional, via MCP, sem IDs concretos e sem credenciais em prompt.

Tamanho: o suficiente para um agente executar sem adivinhar; se passar de ~250 linhas, provavelmente são duas skills.

4. Registrar no catálogo (skills.json)

Uma entrada por skill — é isso que vira o card no site:

{
  "name": "git-flow-delivery",
  "title": "Git Flow Delivery",
  "description": "Branch, commit, PR, release e hotfix seguindo o Git Flow.",
  "tags": ["git-flow", "code-review", "release"],
  "category": "Engenharia",
  "added": "2026-08-25",
  "featured": false
}

• name igual ao nome da pasta (o CI falha se divergir).
• description: uma frase, só o que a skill faz — sem explicar como funciona, sem listar etapas ("entrevista o time…", "detecta a stack…"). Exemplo bom: "Cria, move e consulta cards no Jira ou Trello seguindo o fluxo do seu time." Não repita a description do frontmatter (ela é longa e cheia de termos técnicos, boa para o agente e ruim para o card).
• title: curto, sem subtítulo explicativo depois do travessão ("Web Security Review", não "Web Security Review — Laravel, Node e apps com IA").
• tags: 3–5, minúsculas, kebab-case; viram os filtros da página.
• added: data de hoje em YYYY-MM-DD (ordena a home, mais recente primeiro).
• featured: no máximo uma skill por vez.

Existe uma cópia do catálogo no site (~/Projetos/nlake/luiz-siqueira/skills/skills.json) usada como fallback e como fonte do conteúdo estático/SEO — atualize as duas para ficarem iguais e, no repositório do site, rode node skills/build.mjs (regenera cards estáticos, JSON-LD, FAQ e llms.txt) antes de commitar.

5. Publicar

Nova skill = minor no package.json (1.0.0 → 1.1.0); só correção de texto = patch. A versão do pacote é alinhada pela tag no workflow, mas mantenha o arquivo coerente.

# validar antes: CLI e catálogo
node bin/cli.mjs list
cd "$(mktemp -d)" && node ~/Projetos/skills/bin/cli.mjs add --all && ls .claude/skills

# commit no padrão do repo (ver a skill git-flow-delivery)
git add -A
git commit -m "feat - Add <nome> skill"
git push

# release → o workflow publish.yml publica no npm via OIDC (sem token, sem 2FA)
gh release create v1.1.0 --generate-notes
gh run watch "$(gh run list --workflow publish.yml --limit 1 --json databaseId -q '.[0].databaseId')"
npm view @luizsiqueira/skills version   # confirmar

Ordem importa: o site lê o skills.json do main, então logo que você faz o push o card aparece com o comando de instalação — e ele só funciona depois da release publicar no npm. Faça push e release na mesma sessão; se algo travar, avise que o card está no ar antes do pacote.

Nunca rode npm publish na mão: a conta exige 2FA interativo e o pipeline existe para isso.

6. Fechar o ciclo

• Teste como um usuário externo, de pasta limpa: npx @luizsiqueira/skills@latest add <nome>
• Confira o card em luizsiqueira.com.br/skills/ (a home mostra as skills em carrossel).
• Só então diga que está pronto — com o link do npm e o do SKILL.md no GitHub.

Editar, renomear ou remover

• Editar texto: altere o SKILL.md, ajuste a description do catálogo se mudou o sentido, patch de versão, push, release.
• Renomear: git mv na pasta, name no frontmatter, name nas duas cópias do skills.json, e grep no repositório e no site pelo nome antigo — sobrou nome velho em README, CLI ou card, o link quebra. Renomear é minor (o comando antigo deixa de existir).
• Remover: apague a pasta e a entrada do catálogo; no npm, npm deprecate na versão antiga em vez de despublicar.

Checklist rápido

• Fluxo levantado com o autor (ou extraído de material real), não inventado
• Grep de neutralização limpo
• Pasta skills/<nome-en-kebab>/SKILL.md com name igual à pasta
• description do frontmatter diz o que faz e quando invocar
• Corpo com passos numerados, comandos, checklist e "Adaptando ao seu time"
• Entrada no skills.json (repo e cópia do site), com added de hoje; node skills/build.mjs rodado no site
• Versão do package.json ajustada (nova skill = minor)
• node bin/cli.mjs list e add --all passando
• Push + gh release create na mesma sessão
• npx ... add <nome> testado de pasta limpa
• Autor revisou o SKILL.md antes da release (é o processo dele que fica público)