Skills personalizadas

As skills são comandos slash que automatizam fluxos de trabalho completos com o Claude Code. Quando você digita /implement no terminal, o Claude Code lê as instruções da skill correspondente e executa uma sequência de etapas predefinida: ler a tarefa, escrever código, executar testes e mover o item para a coluna correta.

O Almirant inclui skills integradas que cobrem os fluxos mais comuns, mas você pode criar suas próprias skills para adaptá-las às necessidades da sua equipe.

Skills integradas

O Almirant inclui estas skills por padrão:

Skill	Descrição
/implement	Lê o work item atribuído, implementa o código necessário e move a tarefa para a coluna Review
/review-task	Revisa a implementação atual comparando-a com a definição do work item e sua definition of done
/validate	Pipeline completo de validação: revisão de código + execução de testes + capturas de tela
/test-task	Gera testes automáticos para a implementação atual e os executa
/pr	Cria um Pull Request no GitHub a partir da branch atual com uma descrição gerada
/ideate	Inicia uma sessão interativa de brainstorming e cria work items a partir das ideias
/create-tasks	Cria work items bem estruturados com título, descrição, critérios de aceitação e estimativa

Como cada skill funciona

/implement

1. Lê o work item atribuído no Almirant via MCP
2. Analisa a descrição, os critérios de aceitação e a definition of done
3. Explora o código existente para entender o contexto
4. Implementa as alterações necessárias
5. Move o work item para a coluna Review

/review-task

1. Obtém o work item e sua definition of done no Almirant
2. Lê as alterações implementadas no código
3. Compara a implementação com os critérios de aceitação
4. Gera um relatório detalhado com achados e sugestões

/validate

1. Executa /review-task para revisar a implementação
2. Executa os testes do projeto
3. Se houver uma interface, tira capturas de tela para verificação visual
4. Gera um relatório consolidado com o resultado de cada etapa

/test-task

1. Lê o work item para entender o que deve ser testado
2. Analisa a implementação atual
3. Gera testes unitários e/ou de integração
4. Executa os testes e relata os resultados

/pr

1. Analisa os commits e as alterações na branch atual
2. Gera um título e uma descrição para o Pull Request
3. Cria o PR no GitHub com as informações geradas

/ideate

1. Inicia um diálogo interativo para explorar ideias
2. Faz perguntas para refinar os conceitos
3. Converte as ideias em work items estruturados no Almirant

/create-tasks

1. Recebe uma descrição de alto nível do que é necessário
2. Decompõe o trabalho em tarefas granulares
3. Cria os work items no Almirant com todas as informações necessárias

Criar skills personalizadas

As skills são definidas como arquivos Markdown dentro do diretório .claude/skills/ do projeto.

Localização

tu-proyecto/
  .claude/
    skills/
      implement.md
      review-task.md
      mi-skill-custom.md    # <-- sua skill personalizada

Estrutura de uma skill

Cada arquivo de skill tem duas partes:

1. Frontmatter: metadados no formato YAML (nome e descrição)
2. Instruções: etapas que o Claude Code deve seguir, escritas em Markdown

---
name: mi-skill
description: Breve descripcion de lo que hace esta skill
---

## Instrucciones para el agente

1. Paso uno: descripcion detallada
2. Paso dos: descripcion detallada
3. Paso tres: descripcion detallada

Exemplo: skill de deploy

---
name: deploy-staging
description: Despliega la rama actual al entorno de staging
---

## Instrucciones

1. Verifica que no haya cambios sin commitear ejecutando `git status`
2. Ejecuta el linter con `bun run lint` y corrige errores si los hay
3. Ejecuta los tests con `bun run test` y verifica que pasen
4. Haz push de la rama actual a origin
5. Ejecuta el deploy a staging con `bun run deploy:staging`
6. Verifica que el deploy fue exitoso revisando la URL de staging
7. Reporta el resultado al usuario con la URL del entorno

Exemplo: skill de documentação

---
name: document-feature
description: Genera documentacion tecnica para una feature implementada
---

## Instrucciones

1. Lee el work item asociado a la feature desde Almirant usando MCP
2. Identifica los archivos nuevos o modificados en la implementacion
3. Para cada componente/modulo nuevo:
   - Genera un JSDoc con descripcion, parametros y ejemplos
   - Si es un hook, documenta los valores de retorno
   - Si es un endpoint, documenta request/response
4. Actualiza el README del dominio si existe
5. Crea un comentario en el work item con el resumen de la documentacion generada

Exemplo: skill de migração de banco de dados

---
name: db-migrate
description: Genera y aplica migraciones de base de datos de forma segura
---

## Instrucciones

1. Lee los cambios pendientes en los archivos de schema (`backend/packages/database/src/schema/`)
2. Genera la migracion con `bun run db:generate`
3. Revisa el SQL generado en la carpeta de migraciones
4. Si el SQL contiene operaciones destructivas (DROP, ALTER con perdida de datos),
   advierte al usuario y espera confirmacion antes de continuar
5. Aplica la migracion con `bun run db:migrate`
6. Verifica que la migracion se aplico correctamente

Boas práticas

Instruções claras e específicas

Escreva instruções que não deixem margem para ambiguidades. Em vez de "revise o código", especifique quais arquivos ou padrões devem ser revisados.

# Menos efectivo
1. Revisa el codigo
2. Haz los cambios necesarios

# Mas efectivo
1. Lee todos los archivos en `src/domains/[feature]/` para entender la estructura
2. Verifica que los componentes presentacionales no contengan useState ni useEffect
3. Si encuentras logica en componentes .tsx, extraela a un custom hook en `application/hooks/`

Use ferramentas MCP nas instruções

Faça referência às ferramentas MCP do Almirant para que a skill interaja com o seu quadro.

1. Usa la herramienta `get_work_item` para leer la tarea asignada
2. Implementa los cambios segun la descripcion
3. Usa `update_work_item` para mover la tarea a la columna "Review"

Inclua condições e validações

Defina o que a skill deve fazer quando algo falhar ou quando houver condições especiais.

3. Ejecuta los tests con `bun run test`
   - Si fallan tests, analiza los errores e intenta corregirlos
   - Si no puedes corregirlos despues de 2 intentos, reporta los fallos al usuario
4. Si el work item tiene la etiqueta "needs-review", no muevas automaticamente a Done

Mantenha as skills focadas

Cada skill deve fazer uma coisa bem. Se você precisar de um fluxo complexo, divida-o em várias skills e combine-as manualmente.

Dica

Comece duplicando uma skill integrada e alterando-a para seu caso de uso. É mais fácil adaptar algo existente do que criar do zero.

Importante

As skills são instruções para a IA, não scripts executáveis. O Claude Code as interpreta e decide como executar cada etapa. Escreva as instruções pensando em um desenvolvedor que as lê pela primeira vez.

Compartilhar skills com sua equipe

Como as skills ficam em .claude/skills/, elas são versionadas com Git junto com o restante do projeto. Qualquer membro da equipe que clone o repositório terá acesso às mesmas skills.

Para manter a consistência:

1. Documente cada skill com uma descrição clara no frontmatter
2. Use convenções de nomenclatura consistentes (kebab-case)
3. Agrupe skills relacionadas com prefixos: deploy-staging.md, deploy-production.md
4. Revise as skills no code review como qualquer outro arquivo do projeto