Agent Skills

Colecao open source de skills reutilizaveis para agentes de IA focados em fluxo real de engenharia de software.

Este repositorio organiza instrucoes operacionais em formato SKILL.md para que agentes consigam executar tarefas com mais consistencia, menos ambiguidade e melhor rastreabilidade. Em vez de depender apenas de prompts livres, cada skill encapsula objetivo, quando usar, quando nao usar, passos obrigatorios, regras de decisao e, quando necessario, arquivos de apoio como assets/, references/ e scripts/.

Repositorio: https://github.com/JailtonJunior94/skills

Sumario

• Por que este projeto existe
• Para quem este repositorio e util
• O que voce encontra aqui
• Organizacao por perfil
• Skills disponiveis
• Catalogo detalhado
• Como instalar
• Guia operacional por agente
• Como usar
• Exemplos por perfil de usuario
• Fluxo recomendado: definicao ate entrega da feature
• Fluxo composto: discovery + publicacao no Azure DevOps
• Estrutura do repositorio
• Como criar uma nova skill
• Boas praticas para escrever skills
• Contribuindo
• Compatibilidade e observacoes
• Licenca

Por que este projeto existe

Agentes de IA costumam ter desempenho irregular quando a tarefa exige processo, criterio tecnico e disciplina operacional. Este repositorio reduz essa variacao ao transformar workflows recorrentes em skills reaproveitaveis.

Na pratica, uma skill deste repositorio ajuda o agente a:

• entender rapidamente o objetivo da tarefa;
• validar entradas obrigatorias antes de executar algo caro ou destrutivo;
• seguir uma sequencia de passos clara;
• aplicar regras de decisao consistentes;
• gerar saidas mais previsiveis para usuarios e times.

Para quem este repositorio e util

Este projeto foi pensado para qualquer pessoa que trabalhe com agentes de IA no ciclo de desenvolvimento de software:

• desenvolvedores que querem padronizar tarefas como commits, PRs, Jira e changelogs;
• product managers e analistas que precisam estruturar discovery, backlog e PRD;
• tech leads que precisam de mais consistencia entre diferentes agentes e times;
• equipes de plataforma ou enablement que desejam compartilhar workflows internos de forma reutilizavel;
• mantenedores de repositorios de prompts e automacoes que querem evoluir de instrucoes soltas para artefatos mais estruturados;
• usuarios iniciantes que precisam de exemplos concretos para entender como uma skill e organizada.

O que voce encontra aqui

Cada skill fica em um diretorio proprio dentro de skills/ e normalmente contem:

• SKILL.md: definicao principal da skill, com frontmatter e instrucoes operacionais;
• assets/: templates, esquemas e artefatos usados pela skill;
• references/: regras auxiliares, guias e material de suporte;
• scripts/: scripts locais usados para validacao, classificacao ou montagem de contexto.

Isso permite manter as instrucoes mais modulares: o SKILL.md descreve o comportamento, enquanto os arquivos auxiliares guardam detalhes operacionais reaproveitaveis.

Organizacao por perfil

O repositorio agora oferece duas formas de descoberta:

• skills/ continua sendo a estrutura canonica e a fonte oficial de cada skill;
• product-manager/, devteam/ e geral/ funcionam como catalogos de navegacao por perfil de uso.

Essa classificacao nao move nem duplica skills. Ela apenas organiza a descoberta para reduzir atrito na hora de escolher a skill certa.

product-manager

Foco em discovery, backlog, refinamento de escopo e consolidacao de insumos de produto.

• decision-brainstorming
• domain-modeling-production
• epic-story-discovery
• technical-discovery-production
• tracker-to-prd
• user-stories
• azure-devops-epic-stories

devteam

Foco em execucao tecnica, entrega, revisao, observabilidade e artefatos operacionais de engenharia.

• jira-tasks
• github-pr-comment-triage
• pull-request
• semantic-commit
• recursive-review-bugfix
• design-patterns-mandatory
• docker-postgres-production-stack
• domain-modeling-production
• excalidraw-embedding-best-practices
• postman-collection-generator
• otel-grafana-dashboards
• otel-hybrid-dashboard-blueprint
• postgresql-production-standards
• taskfile-production
• tech-debt-register
• technical-discovery-production
• c4-container-diagram

geral

Skills transversais, uteis tanto para PM quanto para dev team.

• prompt-enricher
• github-diff-changelog-publisher
• github-release-publication-flow
• confluence-changelog-publisher

Skills disponiveis

Atualmente o catalogo contem 26 skills ativas no workspace.

Skill	Perfil	Objetivo principal	Casos de uso tipicos
azure-devops-epic-stories	product-manager	Publicar bundles de discovery como epico e user stories no Azure DevOps com validacao, deduplicacao e audit log.	Criacao de backlog estruturado no ADO, publicacao de epicos, sincronizacao discovery -> board.
c4-container-diagram	devteam	Gerar e validar diagramas de containers C4 production-ready em PT-BR com elementos obrigatorios, notacao padrao e regras de seguranca, eficiencia e escalabilidade.	Criar, revisar ou converter descricoes/infraestrutura em diagrama de containers C4 valido.
confluence-changelog-publisher	geral	Publicar changelogs e resumos tecnicos no Confluence com confirmacao humana antes de consultar e antes de escrever.	Release notes, resumos de PR, changelog em wiki interna.
decision-brainstorming	product-manager	Conduzir pre-discovery decisorio com alternativas, trade-offs, riscos, custos, scorecard e recomendacao auditavel.	Ideias iniciais, solucoes prematuras, decisoes arquiteturais preliminares, reducao de incerteza antes de discovery.
design-patterns-mandatory	devteam	Padronizar a selecao, justificativa e validacao de design patterns classicos com foco em economia, eficiencia e robustez.	Escolha ou rejeicao de patterns, revisao arquitetural localizada, refactor com evidencia tecnica e plano de testes.
docker-postgres-production-stack	devteam	Construir stacks Docker + PostgreSQL production-ready com Compose ou Swarm, secrets, configs, redes e hardening.	Containerizacao de aplicacoes com PostgreSQL, stacks multi-servico, deploy stateful com seguranca e robustez.
domain-modeling-production	product-manager, devteam	Conduzir modelagem de dominio orientada a producao em PT-BR, explicitando linguagem ubiqua, regras, invariantes, comandos, eventos, estados e fronteiras antes de codigo, API ou backlog.	Discovery de dominio, desenho de workflows, definicao de agregados/ownership, contratos e erros de negocio antes de technical-discovery-production, epic-story-discovery ou implementacao.
epic-story-discovery	product-manager	Conduzir discovery estruturada de epico e user stories com perguntas obrigatorias e bundle local validado.	Refinamento de feature, pre-backlog, estruturacao de US antes de Jira ou ADO.
excalidraw-embedding-best-practices	devteam	Aplicar boas praticas de producao para incorporar Excalidraw em React, Next.js e navegador, cobrindo SSR, UI, persistencia, exportacao, seguranca e performance.	Integracao do Excalidraw, customizacao de UI, persistencia de cenas, exportacao e hardening de embeds.
github-diff-changelog-publisher	geral	Ler diffs do GitHub e gerar changelogs ou resumos publicaveis baseados em evidencia.	Release notes, resumo de PR, comparacao entre branches.
github-pr-comment-triage	devteam	Classificar comentarios de PR e transformar review em fila rastreavel de decisao e resposta.	Triagem de review comments, preparacao de respostas, follow-up de feedback tecnico.
github-release-publication-flow	geral	Orquestrar analise de diff, geracao de changelog e publicacao aprovada em GitHub ou Confluence.	Fluxo completo de release publication.
jira-tasks	devteam	Criar tasks no Jira a partir de decomposicao tecnica local.	Publicacao de tasks.md, criacao de subtarefas, sincronizacao de task bundle.
otel-grafana-dashboards	devteam	Gerar dashboards Grafana prontos para producao a partir de codebases Go com OpenTelemetry.	Painis de metricas, traces e logs para servicos instrumentados.
otel-hybrid-dashboard-blueprint	devteam	Montar blueprint de observabilidade hibrida para Grafana e Coralogix com OTel.	Padronizacao de dashboards, desenho inicial de observabilidade, planejamento SRE.
postgresql-production-standards	devteam	Projetar, revisar e endurecer o uso de PostgreSQL com base em evidencia do projeto e documentacao oficial.	Modelagem e migrations, tuning de queries e indices, transacoes, seguranca, observabilidade, backup e replicacao.
postman-collection-generator	devteam	Gerar collections Postman realistas a partir do codigo da API.	Onboarding de APIs, colecoes para testes exploratorios e integracao.
prompt-enricher	geral	Reescrever prompts brutos em prompts mais robustos, compactos e operacionais.	Hardening de prompts, economia de tokens, melhoria de confiabilidade de agentes.
pull-request	devteam	Gerar, revisar, criar ou atualizar PRs com base em diff, commits e contexto do repositorio.	Rascunho de PR, publicacao via GitHub, revisao de titulo e body.
recursive-review-bugfix	devteam	Orquestrar um ciclo iterativo de review e bugfix ate atingir veredito aprovado.	Validacao final pre-merge, reducao de achados criticos, fechamento de lacunas de qualidade.
semantic-commit	devteam	Sugerir ou revisar mensagens de commit semantico com Conventional Commits.	Commit message generation, classificacao de tipo, split de commits.
taskfile-production	devteam	Configurar e operacionalizar o Taskfile (go-task) de forma robusta e production-ready.	Padronizacao de build, testes, lint e CI/CD; migracao de Makefile; automacao multiplataforma.
tech-debt-register	devteam	Registrar debito tecnico com confronto de codebase e clarificacao em oito eixos.	Documentar gap de qualidade, refactor pendente ou risco arquitetural com problema e plano de acao prontos para tracker.
technical-discovery-production	product-manager, devteam	Conduzir discovery técnico orientado a produção com codebase, tecnologias, contratos, APIs, eventos, filas, banco, segurança, volumetria, observabilidade, confiabilidade e custo.	System design, refinamento técnico, análise de viabilidade, definição de contratos, preparação para PRD, TechSpec, SDD, épicos e features.
tracker-to-prd	product-manager	Ler uma user story ou epico no Jira ou Azure DevOps, confrontar com o codebase e consolidar contexto para iniciar um PRD.	Transformar US/epico em insumo para PRD, com confronto de codebase e clarificacao iterativa antes do handoff para create-prd.
user-stories	product-manager	Criar historias de usuario robustas a partir de input livre, tickets, PRDs ou evidencias da base de codigo, com criterios de aceite, perguntas de multipla escolha e validacao local.	Refinamento direto de backlog, decomposicao de funcionalidade em US, confronto com codebase antes de fechar aceite.

Catalogo detalhado

azure-devops-epic-stories

Objetivo: consumir um bundle produzido por epic-story-discovery e publicar epico mais user stories no Azure DevOps com processo detectado automaticamente, checagem de duplicata deterministica, batching e audit log.

Entradas esperadas:

• bundle local em ./discoveries/epic-<slug>/;
• organization, project e board, informados pelo usuario ou por .ado-epic-stories.yml.

Saida principal:

• work items criados no Azure DevOps;
• audit-<timestamp>.json no bundle.

Use quando:

• voce ja concluiu a discovery e quer materializar backlog no ADO;
• precisa de dry-run antes de criar work items;
• quer reconciliar criacoes por audit log.

Nao use quando:

• a discovery ainda nao foi feita;
• o objetivo e criar tasks tecnicas detalhadas;
• o destino nao e Azure DevOps.

Dependencias:

• Azure DevOps MCP;
• Python 3;
• bundle valido de epic-story-discovery.

c4-container-diagram

Objetivo: gerar e validar diagramas de containers C4 production-ready em PT-BR, seguindo o modelo oficial de Simon Brown, com elementos obrigatorios, notacao padrao e regras de seguranca, eficiencia e escalabilidade.

Entradas esperadas:

• nome do sistema de software em escopo;
• proposito do diagrama (novo desenho, revisao, migracao, onboarding ou alinhamento);
• fonte de verdade da arquitetura (codigo, manifests, API specs, docs ou descricao estruturada);
• formato de saida preferido: mermaid, plantuml, drawio ou texto-estruturado.

Saida principal:

• bundle local em ./discoveries/c4-container-<slug>/ com bundle.json, container-diagram.<ext>, containers.md, decisions.md e transcript.md;
• resultado de python3 scripts/validate-c4-container.py igual a SUCCESS.

Use quando:

• precisa criar ou revisar um diagrama de containers C4;
• quer converter descricao de infraestrutura ou arquitetura em diagrama valido;
• precisa de consistencia entre agentes ao documentar a arquitetura de um sistema.

Nao use quando:

• o objetivo for diagrama de contexto, componentes, codigo ou deployment;
• nao houver infraestrutura ou arquitetura real para representar;
• o pedido for apenas brainstorming sem evidencia tecnica.

Dependencias:

• Python 3;
• escrita local no repositorio.

confluence-changelog-publisher

Objetivo: publicar changelogs e resumos tecnicos em paginas do Confluence com confirmacao explicita antes da consulta e antes da escrita.

Entradas esperadas:

• conteudo final ou texto-base aprovado;
• space, title e modo de publicacao;
• opcionalmente ID, URL, pagina-pai ou publicacao na raiz.

Saida principal:

• pagina criada ou atualizada no Confluence;
• conteudo final pronto para uso manual quando a publicacao nao acontecer.

Use quando:

• precisa publicar release notes ou resumo tecnico em wiki;
• precisa de rastreabilidade e confirmacao humana.

Nao use quando:

• quer publicacao automatica sem revisao;
• o destino nao e Confluence;
• o texto final ainda nao existe.

Dependencias:

• Atlassian MCP;
• Python 3.

epic-story-discovery

Objetivo: conduzir discovery estruturada de epico e user stories em PT-BR, com pelo menos duas rodadas obrigatorias de perguntas e validacao sem falso positivo.

Entradas esperadas:

• nome curto ou contexto da feature;
• descricao do problema, objetivo, personas e restricoes.

Saida principal:

• bundle local em discoveries/epic-<slug>/ com bundle.json, epic.md, us/ e transcript.md.

Use quando:

• precisa refinar uma feature antes de criar backlog;
• quer padronizar discovery com KPIs, trade-offs e edge cases;
• precisa de um bundle reutilizavel para ADO, Jira, GitHub Issues ou PRD local.

Nao use quando:

• quer criar work items diretamente sem etapa de discovery;
• quer apenas um PRD sem epico e US.

Dependencias:

• Python 3;
• escrita local no repositorio.

github-diff-changelog-publisher

Objetivo: ler diffs do GitHub para releases, PRs, branches ou compares e produzir um changelog claro, objetivo e publicavel.

Entradas esperadas:

• repositorio no GitHub;
• origem do diff, como release, PR, branch ou compare;
• confirmacao do destino de publicacao, quando houver.

Saida principal:

• changelog estruturado;
• opcionalmente publicacao no GitHub ou handoff para Confluence.

Use quando:

• precisa de release notes baseadas em evidencia;
• quer resumir impacto de uma comparacao de branches;
• precisa preparar conteudo antes de publicar.

Nao use quando:

• o repositorio nao esta no GitHub;
• o changelog e puramente de marketing sem diff de origem.

Dependencias:

• GitHub;
• ferramentas nativas do GitHub e possivel fallback web;
• opcionalmente Atlassian MCP para Confluence.

github-pr-comment-triage

Objetivo: transformar comentarios ja publicados em uma PR em uma fila clara de decisao, resposta e possivel implementacao.

Entradas esperadas:

• identificador da PR;
• acesso ao GitHub via gh;
• opcionalmente politica de resposta ou idioma.

Saida principal:

• classificacao dos comentarios;
• resposta sugerida por item;
• plano de acao rastreavel.

Use quando:

• quer consolidar feedback de code review;
• precisa responder comentarios em pt-BR;
• quer decidir o que implementar e o que apenas justificar.

Nao use quando:

• nao existem comentarios publicados;
• o objetivo e abrir PR ou fazer review do zero.

Dependencias:

• gh;
• acesso ao GitHub.

github-release-publication-flow

Objetivo: orquestrar de ponta a ponta a leitura de diffs do GitHub, a geracao de changelog e a publicacao aprovada pelo usuario.

Entradas esperadas:

• origem do diff no GitHub;
• destino final, GitHub ou Confluence;
• confirmacoes obrigatorias do usuario.

Saida principal:

• changelog final;
• publicacao concluida ou conteudo pronto para uso manual.

Use quando:

• precisa de um fluxo unico entre analise e publicacao;
• quer reduzir etapas manuais em release notes.

Nao use quando:

• o conteudo ja esta pronto e voce so precisa publicar;
• nao ha aprovacao humana para escrita.

Dependencias:

• GitHub;
• opcionalmente Atlassian MCP.

jira-tasks

Objetivo: publicar decomposicao tecnica local como tasks abaixo de uma user story no Jira, resolvendo tipo, campos obrigatorios, estimativa e assignee.

Entradas esperadas:

• user story de destino;
• arquivos locais de task ou bundle de decomposicao;
• acesso ao Jira.

Saida principal:

• tasks criadas e vinculadas abaixo da US.

Use quando:

• a discovery ja virou plano tecnico;
• quer sincronizar tasks.md ou bundle local com Jira.

Nao use quando:

• precisa fazer discovery do zero;
• quer criar PRD;
• nao existe uma US pai clara.

Dependencias:

• Jira MCP ou integracao equivalente;
• arquivos locais de decomposicao.

otel-grafana-dashboards

Objetivo: gerar dashboards Grafana prontos para producao com base em uma codebase Go instrumentada com OpenTelemetry.

Entradas esperadas:

• codebase Go com instrumentacao OTel;
• metricas, traces e logs acessiveis pelos padroes esperados.

Saida principal:

• arquivos JSON de dashboard Grafana;
• opcionalmente artefatos de suporte para ambiente local.

Use quando:

• precisa criar paineis para servicos ja instrumentados;
• quer acelerar observabilidade padronizada para Grafana.

Nao use quando:

• a aplicacao nao usa OTel;
• o foco e apenas infraestrutura;
• o objetivo e configurar collectors ou ingestao.

Dependencias:

• codebase Go;
• OpenTelemetry;
• Grafana.

otel-hybrid-dashboard-blueprint

Objetivo: desenhar um blueprint de observabilidade hibrida para Grafana e Coralogix com padronizacao de metricas, logs, traces, SLOs e variaveis.

Entradas esperadas:

• contexto do servico;
• definicao minima de ambiente, sinais e necessidades de observabilidade.

Saida principal:

• JSON Grafana importavel;
• estrutura equivalente para Coralogix.

Use quando:

• precisa padronizar dashboards entre local e producao;
• quer um blueprint antes de gerar dashboards definitivos.

Nao use quando:

• o servico nao e baseado em OTel;
• quer apenas configuracao de ingestao;
• quer conversao direta de um dashboard ja pronto.

Dependencias:

• OTel;
• Grafana;
• Coralogix.

postman-collection-generator

Objetivo: analisar handlers, DTOs, modelos e middlewares para montar uma collection Postman realista e util para onboarding ou integracao.

Entradas esperadas:

• codebase HTTP em Go, C# ou TypeScript;
• rotas e contratos no codigo.

Saida principal:

• collection Postman com cenarios de sucesso e erro.

Use quando:

• precisa documentar endpoints a partir do codigo;
• quer uma collection para onboard ou testes exploratorios.

Nao use quando:

• o objetivo e gerar OpenAPI;
• o servico nao e HTTP;
• quer testes unitarios.

Dependencias:

• codebase suportada;
• schema/validacao local da collection.

prompt-enricher

Objetivo: transformar um prompt bruto em um prompt mais robusto, objetivo e economico em tokens, com contrato de saida e restricoes explicitas.

Entradas esperadas:

• prompt bruto;
• opcionalmente contexto, restricoes e criterio de aceite.

Saida principal:

• prompt reescrito e operacionalizado.

Use quando:

• um prompt esta fragil, vago ou prolixo;
• quer melhorar latencia e confiabilidade de um agente ou chamada de API.

Nao use quando:

• quer selecionar modelo;
• quer avaliar output;
• quer escrever requisitos amplos de produto.

Dependencias:

• nenhuma integracao externa obrigatoria.

pull-request

Objetivo: gerar, revisar, criar ou atualizar PRs com base em diff, commits e contexto do repositorio, produzindo titulo e body em pt-BR.

Entradas esperadas:

• branch atual;
• diff local ou remoto;
• opcionalmente modo de publicacao.

Saida principal:

• titulo e body da PR;
• opcionalmente PR criada ou atualizada no GitHub.

Use quando:

• precisa abrir PR com melhor qualidade editorial;
• quer revisar se a PR atual representa corretamente as mudancas;
• quer rascunho antes de publicar.

Nao use quando:

• o objetivo e code review profundo;
• precisa apenas de mensagem de commit;
• nao existe delta util entre base e HEAD.

Dependencias:

• Git;
• gh para escrita remota.

recursive-review-bugfix

Objetivo: executar um ciclo iterativo de review critica e bugfix guiado por artefatos de PRD, TechSpec e tasks ate obter aprovacao sem achados criticos ou importantes.

Entradas esperadas:

• caminho da pasta com os artefatos de referencia;
• diff atual a ser revisado.

Saida principal:

• rodadas sucessivas de review e correcao;
• resumo executivo com achados resolvidos e comandos de validacao executados.

Use quando:

• quer uma validacao final rigorosa antes de merge;
• precisa eliminar achados importantes com base em requisitos explicitamente documentados.

Nao use quando:

• precisa apenas de uma revisao pontual;
• nao existem artefatos de contexto suficientes;
• o objetivo e abrir PR.

Dependencias:

• skills review e bugfix disponiveis no ambiente;
• artefatos locais de produto e implementacao.

semantic-commit

Objetivo: sugerir, revisar ou refinar mensagens de commit semantico com Conventional Commits e criterio explicito de classificacao.

Entradas esperadas:

• git diff --staged, git diff ou descricao clara das mudancas.

Saida principal:

• cabecalho de commit validado;
• opcionalmente sugestao de split em multiplos commits.

Use quando:

• quer padronizar commit messages;
• precisa decidir tipo, scope e breaking change;
• quer resumo curto alinhado a um commit ou PR.

Nao use quando:

• quer criar o commit automaticamente;
• precisa de revisao tecnica detalhada do codigo.

Dependencias:

• Git;
• Python 3 para o validador do cabecalho.

taskfile-production

Objetivo: Configurar e operacionalizar o Taskfile (go-task) de forma robusta e production-ready, padronizando tarefas de build, geracao de mocks, testes, lint, segurança e automacao em esteiras CI/CD.

Entradas esperadas:

• Projeto alvo (novo ou existente);
• Stack principal e gerenciador de dependencias;
• Opcionalmente: ferramentas ja adotadas e plataforma de CI/CD.

Saida principal:

• Taskfile.yml orquestrador na raiz;
• Diretorio taskfiles/ com Taskfiles modulares (build.yml, test.yml, lint.yml, etc.);
• Scripts auxiliares isolados em taskfiles/scripts/;
• Workflows de CI/CD e configuracoes de ambiente.

Use quando:

• precisa criar, padronizar ou versionar Taskfile;
• quer migrar de Makefile ou scripts soltos para uma ferramenta moderna;
• precisa de automacao multiplataforma consistente entre local e CI/CD.

Nao use quando:

• quer gerenciar pipelines que nao usam Taskfile;
• o objetivo e escrever a logica de negocio da aplicacao.

Dependencias:

• Task (go-task);
• Python 3 para scripts de validacao e versao.

tech-debt-register

Objetivo: registrar debito tecnico de forma estruturada a partir de uma descricao livre, confrontar com o codebase informado e produzir documento detalhado com problema e plano de acao.

Entradas esperadas:

• descricao livre do debito (ex.: "preciso criar autenticacao na minha API");
• opcional: path local ou modulo suspeito;
• opcional: owner/repo no GitHub para confronto via gh.

Saida principal:

• .specs/tech-debt-<slug>/debt.md com 12 secoes (identificacao, problema, natureza, localizacao no codebase, blast radius, severidade x urgencia, estrategia, esforco, riscos, plano de acao, lacunas, proximo passo);
• .specs/tech-debt-<slug>/clarifications.md append-only com cada rodada.

Use quando:

• precisa registrar debito tecnico ja conhecido com rastreabilidade;
• quer confrontar a descricao com o codigo antes de planejar pagamento;
• precisa de clarificacao iterativa em multipla escolha para chegar em problema + solucao alinhados.

Nao use quando:

• o item e PRD de feature nova (use tracker-to-prd);
• e bug ativo em producao (use canais de incidente);
• e planejamento de arquitetura completa.

Dependencias:

• Python 3 para slugify.py;
• gh autenticado quando confrontar repo remoto.

decision-brainstorming

Objetivo: conduzir uma etapa formal de pre-discovery em PT-BR para explorar alternativas, confrontar premissas, analisar riscos, custos, impactos operacionais e trade-offs antes de iniciar discovery tecnico, discovery de epico/story ou PRD.

Entradas esperadas:

• ideia inicial, problema, oportunidade ou hipotese de solucao;
• contexto de negocio ou tecnico suficiente para comparar alternativas;
• opcionalmente restricoes, prazo, orcamento, sistemas impactados, metricas, incidentes ou requisitos regulatorios.

Saida principal:

• discoveries/brainstorm-<slug>/bundle.json;
• discoveries/brainstorm-<slug>/decision-brief.md;
• discoveries/brainstorm-<slug>/transcript.md;
• discoveries/brainstorm-<slug>/assumptions.md;
• discoveries/brainstorm-<slug>/option-scorecard.md.

Use quando:

• precisa reduzir incerteza antes de discovery;
• o usuario trouxe uma solucao prematura que precisa ser comparada com alternativas;
• quer registrar uma decisao preliminar auditavel antes de aprofundar arquitetura, produto ou PRD.

Melhor forma de usar:

• acione esta skill logo depois de prompt-enricher, quando ainda existe uma ideia bruta ou uma solucao preferida, mas antes de pedir discovery tecnico, PRD ou backlog;
• forneca problema, objetivo, solucao suspeita, restricoes conhecidas e contexto de negocio/tecnico em um unico prompt inicial;
• deixe a skill comparar de 3 a 5 alternativas e exigir decisao explicita antes do handoff;
• use o bundle discoveries/brainstorm-<slug>/ como insumo da proxima etapa, sem pular direto para implementacao.

Prompt recomendado:

Use a skill decision-brainstorming para avaliar a decisao sobre <tema>.
Contexto: <problema, objetivo e impacto esperado>.
Solucao sugerida, se houver: <hipotese inicial>.
Restricoes conhecidas: <prazo, custo, time, sistemas, seguranca, operacao>.
Compare alternativas reais antes de recomendar uma direcao e gere o bundle auditavel para handoff.

Handoff recomendado:

• use technical-discovery-production quando a decisao envolver arquitetura, operacao, seguranca, escalabilidade, observabilidade, confiabilidade ou custo de producao;
• use epic-story-discovery quando a direcao ja estiver madura para decompor capacidade de produto em epico e user stories;
• use tracker-to-prd quando existir uma US ou epico em Jira/Azure DevOps e o proximo passo for preparar contexto para PRD.

Nao use quando:

• o objetivo ja e implementar codigo;
• precisa criar backlog, PRD, epicos, user stories ou tasks finais;
• ja existe uma decisao validada e o proximo passo correto e discovery tecnico ou decomposicao.

Dependencias:

• Python 3;
• escrita local no repositorio;
• disciplina de perguntas estruturadas em multiplas rodadas.

design-patterns-mandatory

Objetivo: padronizar a selecao, justificativa, especificacao e validacao de design patterns classicos com foco obrigatorio em economia, eficiencia e robustez, sempre com evidencia tecnica concreta.

Entradas esperadas:

• problema tecnico e objetivo da mudanca;
• codigo, diff, pseudocodigo ou descricao estrutural suficiente para inferir sinais;
• restricoes reais de custo, desempenho, concorrencia, testabilidade e compatibilidade.

Saida principal:

• bundle decisorio conforme assets/pattern-decision-template.md;
• recomendacao explicita de pattern ou decisao de nao aplicar pattern;
• pseudocodigo canonico, plano de implementacao/refatoracao e plano de testes.

Use quando:

• precisa escolher, aplicar, revisar, comparar ou rejeitar patterns classicos;
• quer reduzir overengineering antes de introduzir classes, interfaces ou indirecao extra;
• precisa justificar tecnicamente um refactor orientado a pattern.

Nao use quando:

• o problema pode ser resolvido por codigo direto mais simples;
• falta evidencia estrutural suficiente;
• o objetivo e apenas ensinar pattern sem contexto de implementacao.

Dependencias:

• Python 3;
• escrita local no repositorio;
• evidencia concreta do problema e do codigo.

docker-postgres-production-stack

Objetivo: construir stacks Docker + PostgreSQL prontos para producao usando Docker Compose ou Docker Swarm, com regras obrigatorias de seguranca, eficiencia, robustez, escalabilidade, secrets, configs, redes e hardening do PostgreSQL.

Entradas esperadas:

• aplicacao ou servicos que precisam rodar com PostgreSQL;
• modo de orquestracao desejado: Compose ou Swarm;
• imagens, hosts, limites de recursos e requisitos de TLS/secrets.

Saida principal:

• arquivos de stack, compose, secrets/configs e configuracoes PostgreSQL;
• validacao local dos artefatos gerados.

Use quando:

• precisa containerizar uma aplicacao com PostgreSQL;
• quer definir stack multi-servico com defaults production-ready;
• precisa operar servico stateful em Docker Swarm.

Nao use quando:

• o banco nao e PostgreSQL;
• o objetivo e apenas rodar um container isolado;
• o ambiente e experimento local sem requisitos de producao.

Dependencias:

• Docker Engine e Docker Compose CLI;
• Python 3;
• permissao para criar arquivos locais e, quando aplicavel, recursos Swarm.

excalidraw-embedding-best-practices

Objetivo: aplicar praticas obrigatorias e prontas para producao ao incorporar o Excalidraw em aplicacoes React, Next.js e navegador, cobrindo instalacao, SSR, customizacao de UI, serializacao, persistencia, exportacao, seguranca e performance.

Entradas esperadas:

• projeto React, Next.js, Preact ou navegador;
• objetivo de integracao, como renderizar, customizar, persistir, exportar ou colaborar;
• contexto de seguranca, armazenamento e restricoes de runtime.

Saida principal:

• orientacao de implementacao ou revisao baseada nas referencias da skill;
• checklist de pre-voo e verificacao final antes do commit.

Use quando:

• precisa adicionar ou operar <Excalidraw> em produto;
• quer persistir cenas ou bibliotecas com seguranca;
• precisa customizar UI, temas, exportacao ou integracao de colaboracao.

Nao use quando:

• o desenho sera feito manualmente fora da aplicacao;
• o projeto nao usa Excalidraw;
• a tarefa e gerar um diagrama estatico sem incorporacao no produto.

Dependencias:

• React/ReactDOM e @excalidraw/excalidraw;
• ambiente de build compatibilizado com as restricoes de SSR;
• leitura das referencias internas antes de alterar codigo.

domain-modeling-production

Objetivo: conduzir modelagem de dominio orientada a producao em PT-BR, transformando problema de negocio, linguagem ubiqua, regras, invariantes, comandos, eventos, estados e fronteiras em um modelo explicito e pronto para handoff.

Entradas esperadas:

• problema, fluxo ou capacidade de negocio a ser modelado;
• objetivo da modelagem, como esclarecer regra, desenhar workflow ou preparar implementacao;
• opcionalmente materiais de apoio e escopo de codebase para confronto.

Saida principal:

• discoveries/domain-<slug>/bundle.json;
• discoveries/domain-<slug>/domain-model.md;
• discoveries/domain-<slug>/transcript.md.

Use quando:

• a ambiguidade principal estiver em termos de negocio, regras, invariantes, ownership ou fronteiras;
• precisa definir workflow, comandos, eventos, erros de dominio e bounded contexts antes de API, backlog ou codigo;
• quer preparar um handoff mais seguro para technical-discovery-production, epic-story-discovery ou implementacao guiada pelo processo do agente.

Nao use quando:

• o objetivo ja e discutir tecnologias, filas, APIs, banco, rollout, volumetria ou custo operacional em profundidade;
• quer brainstorming de alternativas antes de definir a direcao;
• quer gerar backlog, PRD, TechSpec, SDD ou codigo automaticamente.

Dependencias:

• Python 3;
• escrita local no repositorio;
• gh apenas quando o confronto for com repo remoto.

technical-discovery-production

Objetivo: conduzir discovery técnico production-ready em PT-BR com rodadas obrigatórias de múltipla escolha sobre objetivo, escopo, codebase, tecnologias, contratos, APIs, eventos, filas, banco de dados, viabilidade, arquitetura, volumetria, segurança, confiabilidade, observabilidade, rollout e custo, produzindo um dossiê local pronto para PRD, TechSpec, SDD ou decomposição em épicos e features.

Entradas esperadas:

• tema da iniciativa, problema ou oportunidade;
• contexto inicial de negócio e técnico;
• opcionalmente materiais de apoio como PRD, RFC, diagramas, contratos, logs, dashboards e restrições regulatórias;
• escopo de codebase quando houver sistema existente: path local, módulo, repositório remoto, serviço ou confirmação de greenfield.

Saida principal:

• discoveries/technical-<slug>/bundle.json;
• discoveries/technical-<slug>/discovery.md;
• discoveries/technical-<slug>/transcript.md.

Use quando:

• precisa confrontar uma ideia ou demanda com riscos reais de produção;
• quer alinhar product manager e dev team em viabilidade, arquitetura, contratos e trade-offs antes de backlog;
• precisa definir tecnologias, APIs, tópicos, filas, tabelas, migrações e estratégia operacional antes de escrever TechSpec;
• precisa sair com um documento técnico pronto para PRD, TechSpec, SDD ou decomposição em épicos e features.

Melhor forma de usar:

• acione depois de decision-brainstorming quando ainda houver decisao técnica, risco operacional, custo, contrato ou compatibilidade com codebase a resolver;
• informe o problema, objetivo, restrições, orçamento, sistemas impactados e o escopo de codebase logo no primeiro prompt;
• deixe a skill fazer perguntas de múltipla escolha e bloquear a prontidão quando faltar contrato aplicável;
• use o dossiê discoveries/technical-<slug>/discovery.md como fonte de verdade para PRD, TechSpec e SDD.

Prompt recomendado:

Use a skill technical-discovery-production para refinar tecnicamente <tema>.
Problema: <dor atual e impacto>.
Objetivo: <resultado esperado>.
Codebase para confronto: <path local, modulo, owner/repo ou greenfield>.
Restricoes: <prazo, custo, seguranca, compliance, operacao>.
Materiais: <PRD/RFC/diagramas/logs/contratos, se houver>.
Defina tecnologias, contratos de API/eventos/filas/tabelas, volumetria, seguranca, observabilidade, custo, rollout e handoff para PRD/TechSpec/SDD.
Nao implemente codigo.

Handoff recomendado:

• use create-prd ou o processo de PRD do seu agente quando ainda faltarem requisitos de produto, persona, escopo funcional ou métricas;
• use TechSpec/SDD quando a decisão técnica, os contratos e os gates de produção já estiverem definidos no dossiê;
• use epic-story-discovery quando a direção estiver pronta para virar épico e user stories;
• use recursive-review-bugfix no fim da implementação, apontando para a pasta com PRD, TechSpec, SDD e tasks.

Nao use quando:

• o objetivo ja e implementar codigo;
• quer apenas brainstorming sem tomada de decisão;
• precisa criar tasks finais diretamente no tracker.

Dependencias:

• Python 3;
• escrita local no repositório;
• disciplina de clarificação em múltipla escolha, com ou sem UI estruturada do agente.

postgresql-production-standards

Objetivo: projetar, revisar e endurecer o uso de PostgreSQL com foco mandatario em economia, eficiencia, robustez, seguranca, escalabilidade e operacao confiavel, usando apenas regras oficiais do PostgreSQL.

Entradas esperadas:

• projeto, migration, SQL, plano ou configuracao relacionada a PostgreSQL;
• objetivo tecnico claro, como modelagem, tuning, transacao, seguranca, observabilidade ou backup;
• opcionalmente versao observada e evidencias do projeto.

Saida principal:

• recomendacao tecnica, review findings ou needs_input com dupla evidencia;
• decisao objetiva, impacto operacional e validacao minima obrigatoria.

Use quando:

• precisa criar, revisar, validar ou corrigir uso de PostgreSQL em qualquer linguagem;
• quer endurecer modelagem, SQL, indices, transacoes, privilegios, manutencao ou replicacao;
• precisa de diagnostico apoiado em fato observado no projeto e regra oficial correspondente.

Nao use quando:

• o banco nao e PostgreSQL;
• falta evidencia minima de SQL, migration, versao ou configuracao;
• o pedido depende de ferramenta ou fonte nao oficial fora do escopo da skill.

Dependencias:

• Python 3;
• evidencia concreta do projeto;
• acesso a documentacao oficial do PostgreSQL quando necessario.

tracker-to-prd

Objetivo: ler uma user story ou epico completo no Jira (MCP Atlassian) ou Azure DevOps (MCP azure-devops), confrontar requisitos com o codebase informado e consolidar contexto para iniciar a criacao de um PRD.

Entradas esperadas:

• identificador de origem: PROJ-123 (Jira), URL ou triplo org/project/id (Azure DevOps);
• opcional: escopo de codebase (caminho local ou owner/repo no GitHub);
• opcional para Jira: cloudId.

Saida principal:

• bundle em .specs/prd-<slug>/context.md e clarifications.md append-only com cada rodada;
• instrucao explicita de handoff para a skill create-prd.

Use quando:

• a US ou epico ja existe no Jira ou Azure DevOps e voce quer subir o nivel para PRD;
• precisa preservar comentarios, dependencias e contexto funcional relevante;
• quer confrontar requisitos com codigo existente antes de redigir PRD.

Nao use quando:

• nao existe issue/work item de origem;
• o objetivo e apenas consultar o tracker sem preparar PRD;
• precisa criar work items em ferramentas externas.

Dependencias:

• Atlassian MCP;
• Python 3;
• fluxo .claude/commands/create-prd.md.

user-stories

Objetivo: criar historias de usuario prontas para backlog a partir de entrada livre, tickets, PRDs ou evidencias da base de codigo, seguindo o formato persona, necessidade e beneficio, com criterios de aceite verificaveis e validacao contra lacunas.

Entradas esperadas:

• descricao da funcionalidade, problema, ticket, PRD, conversa ou bug;
• opcional: arquivos locais, diff, caminho de repositorio ou modulo para confronto com a base de codigo;
• opcional: restricoes de produto, persona, destino do backlog e granularidade desejada.

Saida principal:

• historias de usuario em Markdown seguindo assets/modelo-historia-usuario.md;
• perguntas de multipla escolha quando houver ambiguidade material;
• evidencias separadas por entrada, base de codigo, inferencias e itens nao evidenciados.

Use quando:

• precisa transformar um input bruto em historias de usuario sem criar epico completo;
• quer confrontar regras, fluxos, permissoes ou dependencias com a base de codigo antes de fechar aceite;
• precisa gerar US robustas com cenario feliz, alternativo e erro.

Nao use quando:

• o objetivo e publicar work items em Jira ou Azure DevOps;
• precisa conduzir discovery completa de epico com bundle e transcript;
• quer escrever codigo de implementacao.

Dependencias:

• Python 3;
• escrita local apenas quando a saida for materializada em arquivos;
• base de codigo acessivel quando o pedido exigir confronto tecnico.

Como instalar

Nao existe um unico modo universal de instalacao, porque diferentes agentes carregam skills de formas diferentes. A abordagem correta depende do ambiente em que voce pretende consumir este repositorio.

Opcao 1: instalar via comando do seu ambiente

Se o seu runtime de agentes suporta adicionar skills diretamente a partir de um repositorio Git, use a URL publica do projeto:

npx skills add https://github.com/JailtonJunior94/skills

Use esta opcao quando seu ambiente ja entende a convencao de pastas e o formato SKILL.md.

Opcao 2: clonar o repositorio localmente

Esta e a opcao mais universal para exploracao, contribuicao e uso manual.

git clone https://github.com/JailtonJunior94/skills.git
cd skills

Depois disso, voce pode:

• apontar sua ferramenta para este diretorio;
• copiar apenas as skills que interessam;
• criar links simbolicos para uma pasta de skills do seu agente.

Opcao 3: copiar uma skill especifica

Se voce quer testar apenas uma skill, copie somente o diretorio desejado:

mkdir -p ~/.claude/skills
cp -R skills/semantic-commit ~/.claude/skills/semantic-commit

Esse mesmo padrao pode ser adaptado para qualquer pasta de skills usada pelo seu agente.

Opcao 4: link simbolico para desenvolvimento local

Durante desenvolvimento, o link simbolico costuma ser a opcao mais pratica porque evita copiar arquivos a cada mudanca:

mkdir -p ~/.claude/skills
ln -s "$(pwd)/skills" ~/.claude/skills/custom-skills

Se o seu ambiente usar outro diretorio-base, troque ~/.claude/skills pelo caminho equivalente.

Requisitos minimos

Os requisitos variam por skill, mas em geral voce vai precisar de:

• Git para clonar e atualizar o repositorio;
• um agente ou runtime que reconheca skills baseadas em SKILL.md;
• Python 3 para skills que dependem de scripts locais de validacao;
• ferramentas externas especificas em alguns casos, como gh, integracoes com Jira/Confluence, Azure DevOps ou MCPs correspondentes.

Guia operacional por agente

Se voce quer um material mais pratico, com prompts mandatorio, eficiente e economico para cada skill e notas de uso em Claude Code, Codex, Gemini e Copilot CLI, use o handbook central:

• Handbook de Skills

Ele nao substitui os SKILL.md; funciona como guia de invocacao, compatibilidade e economia de tokens.

Como usar

Depois de instalar a skill no ambiente correto, voce normalmente a invoca pelo nome no prompt ou no fluxo do agente.

Exemplo basico

Use a skill semantic-commit para sugerir uma mensagem de commit para as mudancas atuais.

Exemplo com contexto operacional

Use a skill pull-request para gerar um rascunho de PR em pt-BR a partir da branch atual.

Exemplo com destino externo

Use a skill jira-tasks para criar tasks filhas da US PAY-142 a partir do bundle local em ./tasks/prd-checkout/.

Exemplo de reescrita de prompt

Use a skill prompt-enricher para transformar este prompt bruto em uma versao mais robusta e economica em tokens.

Exemplo de discovery e publicacao no Azure DevOps

Use a skill epic-story-discovery para refinar um epico de onboarding self-service. Hoje 35% dos novos clientes abandonam no passo de validacao de documentos.

Use a skill azure-devops-epic-stories para publicar o bundle em ./discoveries/epic-onboarding-self-service/ na organizacao acme-co, projeto Plataforma, board Squad-Aquisicao. Faca dry-run antes de criar.

Exemplos por perfil de usuario

1. Pessoa desenvolvedora que quer produtividade imediata

Objetivo: reaproveitar skills prontas sem mexer na estrutura interna.

Exemplos:

Use a skill semantic-commit para classificar meu diff atual e sugerir uma mensagem de commit.

Use a skill pull-request para montar titulo e body da PR com base na branch atual.

Use a skill github-pr-comment-triage para analisar os comentarios da PR 128 e montar uma fila de decisao.

2. Maintainer ou tech lead que quer padronizar o time

Objetivo: adotar um conjunto de workflows previsiveis para reduzir variacao entre agentes e pessoas.

Exemplos:

Use a skill github-release-publication-flow para gerar e revisar o changelog da release antes de publicar.

Use a skill jira-tasks para transformar esta decomposicao local em tasks filhas no Jira, preservando assignee e estimativa.

Use a skill tracker-to-prd para consolidar a US PROJ-231 e preparar o contexto do PRD.

Use a skill domain-modeling-production para modelar o dominio de aprovacao de cadastro, explicitar linguagem ubiqua, comandos, eventos e invariantes, e preparar o handoff para discovery tecnico.

Use a skill tech-debt-register para registrar o debito "preciso criar autenticacao na API", confronte com o path internal/ e conduza clarificacao nos oito eixos.

Use a skill epic-story-discovery para refinar a feature de portal de assinaturas com pelo menos duas rodadas de clarificacao, e em seguida a skill azure-devops-epic-stories para publicar o bundle resultante no projeto Plataforma do Azure DevOps.

3. Pessoa autora de novas skills

Objetivo: usar este repositorio como referencia de estrutura e estilo.

Exemplos:

Leia a skill semantic-commit e use o padrao dela para criar uma nova skill de release review.

Use a skill prompt-enricher como referencia para separar SKILL.md, assets, references e scripts na minha nova skill.

4. Equipe de plataforma ou enablement

Objetivo: manter skills versionadas, revisaveis e distribuidas em um repositorio unico.

Exemplos:

• versionar workflows internos como codigo revisavel;
• compartilhar templates e regras auxiliares em assets/ e references/;
• centralizar automacoes com scripts pequenos e de responsabilidade clara;
• reaproveitar o mesmo desenho de skill em multiplos agentes, com pequenas adaptacoes de integracao.

Fluxo recomendado: definicao ate entrega da feature

Use este fluxo quando a feature ainda precisa sair de uma necessidade pouco definida e chegar a uma entrega revisavel, com foco em robustez, economia e production-ready sem falso positivo.

1. Enriquecer a necessidade

Use prompt-enricher quando o pedido inicial estiver solto, misturando objetivo, solucao sugerida e restricoes.

Use a skill prompt-enricher para transformar esta ideia em um prompt operacional:
<ideia bruta, problema, restricoes e contexto conhecido>.
O objetivo e preparar uma discovery tecnica e de produto sem perder riscos, custo e operacao.

Resultado esperado: prompt inicial mais claro, com objetivo, contexto, restricoes e insumos que reduzem rodadas desnecessarias.

2. Decidir direcao antes de aprofundar

Use decision-brainstorming quando ainda houver solucao prematura, incerteza estrategica ou alternativas relevantes.

Use a skill decision-brainstorming para avaliar a decisao sobre <tema>.
Contexto: <problema e impacto>.
Solucao sugerida: <hipotese inicial>.
Restricoes: <prazo, custo, sistemas, seguranca, operacao>.
Compare alternativas reais, registre trade-offs e gere um decision brief para handoff.

Resultado esperado: discoveries/brainstorm-<slug>/ com alternativas, scorecard, riscos, custos e decisao preliminar explicita.

3. Refinar tecnicamente com codebase e contratos

Use domain-modeling-production antes do discovery tecnico quando a ambiguidade dominante ainda estiver em linguagem de negocio, invariantes, estados, ownership ou fronteiras de dominio.

Use a skill domain-modeling-production para modelar o dominio de <tema>.
Problema: <ambiguidade atual>.
Objetivo da modelagem: <resultado esperado>.
Codebase para confronto: <path local, modulo, owner/repo ou greenfield>.
Defina linguagem ubiqua, bounded contexts, workflow principal, comandos, eventos, invariantes, erros de dominio e fronteiras externas.

Resultado esperado: discoveries/domain-<slug>/domain-model.md validado, com termos canonicos, regras, ownership e handoff claro para backlog, discovery tecnico ou implementacao.

4. Refinar tecnicamente com codebase e contratos

Use technical-discovery-production quando a direcao precisar virar desenho tecnico defensavel.

Use a skill technical-discovery-production para refinar tecnicamente <tema>.
Problema: <dor atual>.
Objetivo: <resultado esperado>.
Codebase para confronto: <path local, modulo, owner/repo ou greenfield>.
Restricoes: <prazo, custo, seguranca, compliance, operacao>.
Materiais: <PRD/RFC/diagramas/logs/contratos, se houver>.
Defina tecnologias, APIs, eventos, topicos, filas, tabelas, migracoes, seguranca, observabilidade, custo, rollout e handoff para PRD/TechSpec/SDD.

Resultado esperado: discoveries/technical-<slug>/discovery.md validado, com evidencias de codebase path:linha quando houver sistema existente, contratos aplicaveis e riscos residuais.

5. Criar PRD, TechSpec e SDD

Use o dossie tecnico como fonte de verdade. O repositorio nao inclui uma skill local dedicada a gerar TechSpec/SDD, entao use o processo do seu agente ou comando interno, sempre apontando para o bundle validado.

Crie o PRD, TechSpec e SDD a partir de discoveries/technical-<slug>/discovery.md.
Preserve as decisoes, contratos, riscos, evidencias de codebase, gates de producao e itens em aberto.
Nao adicione tecnologia, API, tabela, fila ou evento que nao esteja no dossie sem registrar nova decisao.

Resultado esperado: pasta de especificacao com PRD, TechSpec, SDD e criterios de aceite/validacao consistentes com o discovery.

6. Decompor em epico e user stories

Use epic-story-discovery quando os artefatos ja estiverem maduros para virar backlog.

Use a skill epic-story-discovery para decompor <feature>.
Contexto base: discoveries/technical-<slug>/discovery.md e os artefatos de PRD/TechSpec/SDD.
Conduza as rodadas obrigatorias, gere epico e user stories em PT-BR e valide o bundle antes de encerrar.

Resultado esperado: discoveries/epic-<slug>/ com epic.md, us/, transcript.md e bundle validado.

Use user-stories quando o objetivo for gerar somente historias de usuario robustas a partir de input livre, ticket, PRD ou codebase, sem materializar um epico completo.

Use a skill user-stories para transformar <input> em historias de usuario.
Confronte com a base de codigo em <path/modulo>, faca perguntas de multipla escolha se houver lacunas e valide criterios de aceite antes de finalizar.

Resultado esperado: historias de usuario em Markdown com declaracao, regras de negocio, criterios de aceite, dependencias, fora de escopo e evidencias.

7. Publicar ou executar a entrega

Use azure-devops-epic-stories se o destino for Azure DevOps, ou use o bundle local para Jira/GitHub Issues/processo interno.

Use a skill azure-devops-epic-stories para publicar o bundle ./discoveries/epic-<slug>/ no Azure DevOps.
Organizacao: <org>.
Projeto: <project>.
Board: <board>.
Faca dry-run, detecte duplicatas e peca confirmacao antes de criar work items.

Resultado esperado: backlog criado com audit log, ou plano de publicacao bloqueado por duplicata/campo obrigatorio antes de qualquer escrita.

8. Revisar implementacao contra os artefatos

Use recursive-review-bugfix antes de merge quando houver diff implementado e pasta com PRD/TechSpec/SDD/tasks.

Use a skill recursive-review-bugfix.
Caminho dos artefatos: <pasta com PRD, TechSpec, SDD e tasks>.
Revise o diff atual contra esses artefatos e corrija ate nao haver achados criticos ou importantes.

Resultado esperado: implementacao validada contra requisitos, contratos e gates definidos, com achados criticos/importantes resolvidos antes do merge.

Atalho economico

Quando o tempo for curto, o minimo recomendado e:

decision-brainstorming -> domain-modeling-production -> technical-discovery-production -> PRD/TechSpec/SDD -> epic-story-discovery -> recursive-review-bugfix

Pule decision-brainstorming apenas quando a direcao ja estiver decidida e documentada. Pule domain-modeling-production apenas quando a linguagem ubiqua, as invariantes, o ownership e as fronteiras do dominio ja estiverem inequivocos. Pule epic-story-discovery apenas quando o backlog ja existir em tracker e estiver coerente com PRD/TechSpec/SDD.

Fluxo composto: discovery + publicacao no Azure DevOps

As skills epic-story-discovery e azure-devops-epic-stories foram desenhadas para trabalhar em pipeline. A primeira faz a descoberta de produto/feature com rigor metodologico e gera um bundle local versionavel; a segunda consome o bundle e publica o epico mais as user stories no Azure DevOps. Esta separacao traz quatro ganhos praticos:

• Reutilizacao do mesmo bundle em outros destinos, como Jira, GitHub Issues, Confluence ou PRD interno, sem repetir a discovery.
• Retomada sem perda de contexto se a publicacao no ADO falhar parcialmente ou se o usuario quiser revisar antes de criar.
• Auditoria clara via transcript.md na discovery e audit-<timestamp>.json na publicacao.
• Portabilidade entre agentes: a discovery roda 100% local em qualquer agente que suporte SKILL.md; a publicacao depende apenas de um MCP do Azure DevOps configurado.

Diagrama do pipeline

                ┌─────────────────────────────┐
  pedido do  →  │   epic-story-discovery      │  →  ./discoveries/epic-<slug>/
   usuario      │  - coleta contexto          │       ├── bundle.json
                │  - Rodada 1 obrigatoria     │       ├── epic.md
                │  - Rodada 2 obrigatoria     │       ├── transcript.md
                │  - rodadas extras se ambiguo│       └── us/
                │  - valida sem falso positivo│           ├── 01_<slug>.md
                └─────────────────────────────┘           └── 02_<slug>.md
                              │
                              ▼
                ┌─────────────────────────────┐
                │ azure-devops-epic-stories   │  →  Work items no ADO
                │  - le .ado-epic-stories.yml │       + audit-<timestamp>.json
                │  - detecta processo         │
                │  - normaliza titulo (dedup) │
                │  - cria epico + US          │
                │  - vincula via Parent       │
                │  - batching 10 por execucao │
                └─────────────────────────────┘

Quando usar cada skill isoladamente

• Use apenas epic-story-discovery quando voce ainda nao decidiu o destino, vai publicar em outra ferramenta, quer revisar o bundle em PR antes de publicar, ou precisa apenas materializar um artefato local.
• Use apenas azure-devops-epic-stories quando voce ja tem um bundle pronto produzido em sessao anterior, quer republicar apos correcao, ou esta consumindo um bundle gerado por outro membro do time.

Exemplo end-to-end

Cenario: time de 6 pessoas quer criar um epico de autenticacao self-service e quatro user stories no Azure DevOps de uma organizacao chamada acme-co no projeto Plataforma, board Squad-Acesso.

Passo 1: registrar defaults do time (opcional, uma unica vez por repositorio)

Crie .ado-epic-stories.yml na raiz do repositorio para evitar reinformar organizacao, projeto e board a cada execucao:

organization: acme-co
project: Plataforma
board: Squad-Acesso
# process: Agile
# child_type_override:

Passo 2: rodar a discovery

Use a skill epic-story-discovery para refinar um epico de autenticacao self-service de clientes finais. Hoje o suporte recebe cerca de 1200 tickets/mes de acesso. Queremos reduzir esse volume oferecendo recuperacao de senha, desbloqueio de conta e MFA opcional.

Passo 3: revisar o bundle (opcional, mas recomendado para times maiores)

Os arquivos sao markdown puro em PT-BR. Versione em git, abra PR e use transcript.md como trilha de decisao da discovery.

Passo 4: publicar no Azure DevOps

Use a skill azure-devops-epic-stories para publicar o bundle em ./discoveries/epic-auth-self-service/ no Azure DevOps.

O agente vai:

1. Carregar defaults do .ado-epic-stories.yml.
2. Detectar o processo do projeto e escolher o tipo de child correto.
3. Normalizar o titulo do epico e consultar WIQL para detectar duplicata.
4. Apresentar o plano final e perguntar se voce quer criar agora, fazer dry-run ou cancelar.
5. Criar o epico, criar cada US, vincular via System.LinkTypes.Hierarchy-Reverse e gravar audit-<timestamp>.json.

Estrutura do repositorio

Estrutura atual, em alto nivel:

devteam/
├── README.md
geral/
├── README.md
product-manager/
├── README.md
skills/
├── azure-devops-epic-stories/
├── confluence-changelog-publisher/
├── decision-brainstorming/
├── design-patterns-mandatory/
├── docker-postgres-production-stack/
├── domain-modeling-production/
├── epic-story-discovery/
├── excalidraw-embedding-best-practices/
├── github-diff-changelog-publisher/
├── github-pr-comment-triage/
├── github-release-publication-flow/
├── jira-tasks/
├── otel-grafana-dashboards/
├── otel-hybrid-dashboard-blueprint/
├── postgresql-production-standards/
├── postman-collection-generator/
├── prompt-enricher/
├── pull-request/
├── recursive-review-bugfix/
├── semantic-commit/
├── taskfile-production/
├── tech-debt-register/
├── technical-discovery-production/
├── tracker-to-prd/
└── user-stories/

Exemplo de estrutura interna de uma skill:

skills/semantic-commit/
├── SKILL.md
├── assets/
├── references/
└── scripts/

Como criar uma nova skill

O formato basico e simples, mas o valor real esta em escrever instrucoes testaveis, especificas e orientadas a fluxo.

Passo 1: criar o diretorio

mkdir -p skills/minha-skill

Passo 2: criar o SKILL.md

---
name: minha-skill
description: Descreva de forma objetiva o que a skill faz, quando usar e quando nao usar.
---

# Minha Skill

## Procedimentos
1. Validar a entrada obrigatoria.
2. Coletar o contexto minimo necessario.
3. Executar a tarefa principal com regras claras.
4. Retornar um resultado verificavel.

Passo 3: adicionar arquivos auxiliares quando fizer sentido

Use:

• assets/ para templates, schemas e modelos de saida;
• references/ para regras detalhadas e criterios de decisao;
• scripts/ para validacoes locais, classificacoes e utilitarios pequenos.

Passo 4: testar a skill no agente alvo

Valide pelo menos:

• se o nome da skill esta claro e coerente com a tarefa;
• se a descricao explica bem quando usar e quando nao usar;
• se o fluxo nao depende de inferencias fracas;
• se os passos sao executaveis no ambiente real;
• se a saida final e util para o usuario final.

Boas praticas para escrever skills

Se voce pretende contribuir ou criar skills inspiradas neste repositorio, estes principios ajudam bastante:

• prefira instrucoes operacionais a texto promocional;
• declare entradas obrigatorias e estados de erro cedo;
• diferencie claramente "usar" de "nao usar";
• preserve fatos observaveis e evite que a skill invente contexto;
• mantenha scripts pequenos e com responsabilidade unica;
• use references/ para regras extensas, em vez de inflar o SKILL.md;
• escreva outputs que possam ser auditados por uma pessoa.

Exemplo de descricao ruim:

description: Ajuda com Jira.

Exemplo de descricao melhor:

description: Cria tasks no Jira abaixo de uma User Story com base em arquivos locais de decomposicao, resolvendo campos obrigatorios, assignee e estimativas antes da criacao.

Contribuindo

Contribuicoes sao bem-vindas, especialmente para:

• adicionar novas skills reutilizaveis;
• melhorar clareza e seguranca de skills existentes;
• incluir assets, references e scripts que reduzam ambiguidade operacional;
• corrigir exemplos, documentacao e instrucoes obsoletas.

Fluxo sugerido:

1. Faca um fork do repositorio.
2. Crie uma branch para sua alteracao.
3. Adicione ou atualize a skill com foco em comportamento verificavel.
4. Revise o README e a estrutura da skill para manter consistencia.
5. Abra um Pull Request explicando o problema resolvido e o impacto esperado.

Se a sua contribuicao introduzir uma nova skill, inclua no PR:

• objetivo da skill;
• quando usar e quando nao usar;
• exemplos de prompt ou invocacao;
• dependencias externas relevantes;
• riscos ou limitacoes conhecidas.

Compatibilidade e observacoes

• Este repositorio nao assume um unico agente. A mesma skill pode exigir pequenas adaptacoes dependendo do runtime que a consome.
• Algumas skills dependem de ferramentas externas como gh, Jira, Confluence, Azure DevOps, MCPs ou scripts Python locais.
• Nem toda skill e universalmente portavel sem ajustes de integracao.
• Os diretorios product-manager/, devteam/ e geral/ sao catalogos de navegacao. A fonte oficial continua sendo skills/.

Licenca

No momento, este repositorio nao possui um arquivo LICENSE versionado na raiz. Se voce pretende reutilizar este conteudo em ambiente aberto ou comercial, o ideal e adicionar uma licenca explicita antes da redistribuicao formal.