Elastic Create Integration: pacote, streams e testes com guardrails

ANÁLISE EDITORIAL

Criar uma integração para o ecossistema Elastic envolve muito mais do que montar uma pasta e escrever um pipeline. É preciso definir o pacote, organizar data streams, escolher a forma de coleta, mapear campos para ECS, testar o processamento e registrar o que ainda depende de infraestrutura real. A Create Integration transforma esse trabalho em um roteiro para agentes de código, com etapas explícitas de preparação, construção, teste e revisão.

Esta Skill é mantida no repositório oficial elastic/integration-skills. Ela está em beta e o próprio projeto avisa que o conteúdo segue em desenvolvimento. A curadoria considera esse vínculo oficial como exceção ao corte editorial de mil estrelas: o repositório tinha 15 estrelas na consulta de 20/08/2026. Isso comprova a origem, não popularidade nem qualidade automática.

Ilustração editorial exclusiva do Bastidores da IA. Não é captura de tela, painel real, logotipo oficial, arquitetura implantada nem prova de teste executado.

O que esta Skill faz de verdade

O SKILL.md fixado no commit auditado funciona como orquestrador. Ele ajuda a criar um pacote de integração novo, adicionar data streams, conferir a topologia esperada e coordenar etapas especializadas para coleta, programas CEL, pipelines de ingestão, mapeamento de campos, testes de sistema e revisão.

A Skill não substitui essas especialidades. Ela encaminha partes do trabalho para outras Skills do mesmo repositório, como cel-programs, integration-testing, ingest-pipelines e review-integration. Também depende de quatro referências próprias: fluxo de criação, fluxo para adicionar data stream, layout de pacote e comandos de scaffold.

O valor está na sequência. Primeiro vêm requisitos, amostras, documentação da fonte e critérios de aceitação. Depois entram o scaffold, as alterações necessárias, o pipeline, os testes e a revisão. A saída não deveria ser apenas uma árvore de arquivos plausível. O fluxo procura evidência de build, lint, testes e alinhamento entre manifestos e templates.

Para quem serve

A Create Integration é voltada a pessoas que desenvolvem ou mantêm pacotes para Elastic Agent e Fleet. Ela pode ajudar equipes do repositório elastic/integrations, parceiros que entregam integrações oficiais e profissionais que criam pacotes privados para fontes próprias de logs e métricas.

Ela é mais útil quando a equipe já entende data streams, ingest pipelines, Elastic Common Schema e o papel do elastic-package. Para quem só precisa conectar uma fonte pela interface, o caminho de Automatic Import documentado pela Elastic pode ser mais simples. A Skill é o caminho de engenharia, com repositório, arquivos, ferramentas e testes.

Não é uma boa escolha para começar sem amostras, documentação ou permissão sobre a fonte. Também não deve ser tratada como gerador autônomo de integração pronta para produção. APIs mudam, eventos podem conter dados pessoais, esquemas exigem decisão de negócio e alguns testes dependem de serviços externos que não cabem em um ambiente local.

Compatibilidade e pré-requisitos

O repositório declara compatibilidade com Cursor, Claude Code, Codex e outros ambientes capazes de ler Skills em Markdown. O arquivo principal declara versão 1.0 e licença Apache-2.0. O projeto está em beta, portanto o commit fixado é mais confiável para auditoria do que o nome da versão isolado.

Para o fluxo completo, a documentação oficial lista Docker e elastic-package. Dependendo do tipo de entrada, também aparecem ferramentas Go como celfmt, stream, mito, ceplx e kbdash. Nenhuma delas está incluída no download local desta página.

O projeto de destino precisa ter uma estrutura compatível com pacotes Elastic. A documentação oficial para criar uma integração explica a sequência de pacote, data stream, modo de implantação, pipeline, campos, dashboards e validação. A referência de definições da Elastic detalha manifestos, data streams e diretórios de desenvolvimento.

Instalação recomendada

O caminho funcional é instalar a Skill a partir do repositório oficial, em um projeto de teste: npx skills add elastic/integration-skills --skill create-integration. O comando usa código obtido pela rede e grava arquivos no projeto. Confira a origem do pacote, fixe o commit quando o cliente permitir e revise o diff antes de executar qualquer ferramenta indicada pela Skill.

A instalação completa deve preservar a pasta references e as Skills irmãs chamadas pelo orquestrador. Copiar apenas o SKILL.md não entrega o fluxo operacional descrito. O README também documenta clone local e marketplace para Claude Code, mas cada método tem superfície e atualização diferentes.

O download local do Bastidores é propositalmente documental. Ele contém somente SKILL.md, LICENSE.txt e ORIGEM.md. Serve para leitura, auditoria e comparação do núcleo. Não é apresentado como instalação autossuficiente, pois exclui as quatro referências operacionais e as Skills irmãs necessárias.

Configuração antes do primeiro uso

Comece com um briefing que informe produto, nome do pacote, tipo de entrada, data streams, autenticação, paginação, amostras e critérios de aceitação. Registre também onde o agente pode ler e escrever, quais comandos são permitidos e quais exigem aprovação adicional.

Separe dados de teste de credenciais reais. Tokens, chaves, senhas, cookies e endpoints privados não devem ser incorporados ao prompt ou ao repositório. Quando uma API exige autenticação, prefira uma conta de desenvolvimento com privilégio mínimo, variáveis de ambiente fora do controle de versão e amostras anonimizadas.

Defina as versões do Elastic Stack, do elastic-package e das ferramentas auxiliares. O fluxo contém recomendações específicas de formato e condições de Kibana, mas uma integração existente pode precisar preservar versões atuais. Toda mudança de versão deve ser justificada pelo recurso necessário e revisada no diff.

Primeiro uso seguro

Use uma fonte pequena e não sensível. Peça primeiro um plano de arquivos e uma matriz de requisitos, sem criar nada. Confirme nome do pacote, um único data stream, método de coleta, campos principais, exemplo de evento e limites do teste.

Depois autorize apenas o scaffold. Revise cada arquivo criado e trate o resultado como placeholder. A Skill é explícita ao dizer que um scaffold válido não equivale a implementação completa. Manifestos, templates e programas CEL precisam ser alinhados à fonte real.

Execute validações em etapas. Pipeline e mapeamento devem passar por fixtures conhecidas. Testes de sistema precisam usar ambiente descartável e o comando aceito pela equipe. A documentação de publicação da Elastic exige elastic-package check antes do pull request, mas esse resultado não substitui revisão de segurança, privacidade e comportamento da fonte.

Resultado esperado

Uma execução boa entrega um pacote rastreável, não apenas texto convincente. Deve haver árvore de arquivos coerente, manifestos sem variáveis órfãs, template compatível com o tipo de entrada, pipeline capaz de processar as amostras, campos documentados e evidência dos testes que realmente foram executados.

O relatório final deve separar o que passou, o que falhou e o que foi pulado. Entradas de armazenamento em nuvem podem não ter um mock local confiável; nesse caso, o teste de sistema deve ser marcado como não executado, com motivo, em vez de virar sucesso presumido.

Também se espera um registro de riscos: acesso à API, custos, volume de eventos, dados pessoais, retenção de amostras, permissões da conta e efeitos de comandos. A Skill organiza o trabalho, mas a decisão de publicar ou implantar continua humana.

Permissões e riscos

O ZIP local é textual e não executa nada. O uso funcional da Skill pode ler e alterar um repositório, instalar ferramentas, baixar dependências, iniciar Docker, abrir portas locais, consumir CPU e disco, acessar endpoints, usar credenciais, criar fixtures e executar testes que gravam artefatos.

A orquestração também delega tarefas a subagentes. Isso amplia o contexto que pode ser lido e a quantidade de alterações propostas. Passe somente os caminhos e dados necessários, evite fontes privadas desnecessárias e revise cada retorno antes de autorizar a próxima etapa.

Trate leitura, escrita, instalação, execução, rede, segredo e publicação como permissões diferentes. Não aceite uma autorização geral para todas elas. Em integração de produção, valide em ambiente isolado, use dados anonimizados, limite recursos do Docker e preserve um diff revisável.

Erros comuns

• Copiar só o arquivo principal: o fluxo completo depende de quatro referências e de Skills irmãs.
• Começar sem amostras: um pipeline plausível pode mapear campos que não existem.
• Tratar scaffold como pronto: arquivos gerados são pontos de partida e precisam de implementação.
• Executar todas as etapas de uma vez: separe scaffold, pipeline, testes e revisão.
• Usar credencial de produção: prefira conta de teste, menor privilégio e segredo fora do prompt.
• Inventar sucesso de teste: registre exatamente qual comando rodou e qual etapa foi pulada.
• Ignorar manifestos existentes: preserve versões quando a nova função não exige mudança.
• Confundir origem oficial com adoção: 15 estrelas não demonstram uso amplo.

Versão auditada e download local

A curadoria fixou o commit e4d8b66f4a3d01b42342de5ce9ff4dbec6a2fe57, publicado no histórico do repositório em 18/08/2026. O SKILL.md declara versão 1.0. A consulta de 20/08/2026 registrou 15 estrelas. A exceção ao corte de mil estrelas existe porque o projeto é mantido pela organização oficial Elastic e possui documentação e licença verificáveis.

O projeto usa Apache License 2.0. O pacote local tem 7.504 bytes e SHA-256 54bf0b8bfe010075855cb09645c8ac2546f729b33cfbdcc9a515c1cf71c54508. Ele contém três arquivos textuais permitidos, sem referências operacionais, executáveis, dependências, Docker, ferramentas, amostras, tokens, cookies ou credenciais.

O ORIGEM.md registra repositório, caminho, commit, licença, data, escopo e hashes dos arquivos copiados. Para operar a Skill, use a instalação oficial completa. Para revisar o núcleo e a licença, use o download local separado do botão do repositório.

Resultado esperado e limite final

A Create Integration pode reduzir omissões porque força a equipe a pensar em requisitos, coleta, pipeline, campos, testes e revisão como partes do mesmo trabalho. Esse é o ganho real do roteiro.

O limite também é claro. Uma Skill não conhece por conta própria a semântica dos eventos, a política de dados da organização ou a infraestrutura disponível. Se documentação, amostra, credencial de teste ou ambiente seguro estiverem ausentes, pare na fase de planejamento. Um pacote incompleto bem identificado é melhor do que uma integração aparentemente pronta com comportamento inventado.

Fontes primárias

• Repositório oficial da Elastic no commit auditado.
• Pasta oficial da Create Integration.
• SKILL.md versão 1.0.
• Licença Apache-2.0.
• Guia oficial para criar uma integração.
• Definições oficiais de pacote e data stream.
• Documentação oficial de Automatic Import.
• Validação e publicação de integrações.