Home Assistant: desenvolva e revise integrações com a Skill oficial

ANÁLISE EDITORIAL

Uma integração do Home Assistant pode parecer simples até o primeiro dispositivo ficar indisponível, uma configuração precisar ser refeita ou um diagnóstico revelar um token. A Skill oficial ha-integration-knowledge, publicada dentro do repositório Home Assistant Core, serve como referência para um agente que desenvolve, testa ou revisa integrações. Ela aponta caminhos do código e dos testes, relaciona regras de qualidade e lembra limites que se perdem facilmente em uma revisão automatizada. É uma orientação para trabalho de desenvolvimento, não uma integração pronta para instalar na casa de alguém.

O que é esta Skill, e quem ganha com ela

O SKILL.md mantido no Home Assistant Core reúne regras para quem examina uma pasta de integração em homeassistant/components/<domain>/ e seus testes em tests/components/<domain>/. Ele recomenda começar por integrações de qualidade gold ou platinum ao procurar exemplos, preservar o ciclo de vida das entidades e usar as regras da Integration Quality Scale como verificação. O público é o desenvolvedor, mantenedor ou revisor de código Python para o Core. Um usuário que só quer adicionar uma lâmpada pelo painel do Home Assistant não precisa desta Skill.

Seu valor está em dar contexto específico a um agente de programação. Sem esse contexto, ele pode propor um campo de configuração de intervalo de consulta que o projeto não aceita, duplicar comportamento da classe base de uma entidade ou testar detalhes internos em vez da interface pública. A Skill não substitui a documentação nem a revisão humana: é um ponto de partida para formular perguntas melhores ao código real.

Compatibilidade e limites do formato

O pacote do Bastidores contém apenas arquivos Markdown. Ele pode ser lido manualmente ou colocado na pasta de Skills de um cliente que reconheça SKILL.md. O caminho original .claude/skills/ha-integration-knowledge/ mostra como o próprio repositório organiza o material; outros clientes têm convenções de instalação diferentes. Confirme na documentação do seu agente onde colocar a pasta e se ele carrega referências Markdown adjacentes. Não há comando universal de instalação garantido para todos os agentes.

As orientações foram escritas para o Home Assistant Core, não para qualquer repositório que use o nome Home Assistant. Uma integração personalizada em custom_components compartilha vários conceitos, mas não deve receber automaticamente regras de contribuição do Core. A documentação oficial da estrutura de integração distingue o local das integrações embutidas do diretório de componentes personalizados e alerta contra sobrescrever uma integração nativa com o mesmo domínio. Essa distinção deve ser mantida na revisão.

Pré-requisitos antes de pedir mudanças ao agente

Tenha uma cópia de desenvolvimento do repositório ou do projeto de integração, um domínio de integração identificado e permissão para examinar os arquivos. Para executar testes do Core, prepare o ambiente documentado pelo projeto, incluindo dependências e ferramentas da versão corrente. O guia oficial de ambiente oferece um devcontainer com VS Code, Docker e Git, além de um caminho manual com requisitos próprios. O ZIP da Skill não inclui esse ambiente, Python, dispositivos ou bibliotecas.

Antes de alterar código, localize manifest.json, __init__.py, plataformas como sensor.py e a pasta correspondente em tests/components. O domínio é parte da identidade da integração e não deve ser renomeado casualmente. Se houver equipamentos físicos, dados de conta ou serviços externos, separe um ambiente de teste e obtenha autorização antes de conectar o agente a eles. A Skill fornece conhecimento; as permissões de leitura, escrita, rede e terminal vêm do cliente e continuam sob sua responsabilidade.

Instalação documental e conferência do download

Baixe o pacote local pelo card desta página e compare o SHA-256 do ZIP com o valor exibido. Extraia em uma pasta temporária e leia ORIGEM.md, que lista o commit fixado, a licença e o hash de cada arquivo. O pacote contém SKILL.md, platform-diagnostics.md, platform-repairs.md e LICENSE.md. Não há script, binário ou dependência para executar. Se qualquer hash divergir, interrompa a instalação e obtenha uma cópia íntegra.

Copie a pasta ha-integration-knowledge inteira, sem separar as duas referências do arquivo principal, para o diretório de Skills aceito pelo seu agente. Em um cliente que não descubra Skills automaticamente, anexe ou mencione o SKILL.md como material de referência e preserve os links relativos para as duas páginas complementares. Evite instalar uma segunda cópia com o mesmo nome em outro escopo, pois ela pode disputar prioridade. Confira qual arquivo o agente de fato abriu antes de confiar em uma sugestão.

Configuração de escopo e primeiro uso

Comece com uma tarefa de leitura, por exemplo: “Revise a integração <domain> no Home Assistant Core usando esta Skill. Liste os arquivos examinados, confronte manifest.json, quality_scale.yaml e testes, e proponha mudanças sem aplicá-las”. Substitua <domain> pelo domínio real. Peça ao agente que diferencie o que está no repositório do que é apenas uma recomendação da Skill. Se a integração não possuir determinado arquivo ou regra, ele deve registrar a ausência, não inventar conteúdo.

O resultado esperado na primeira rodada é um diagnóstico rastreável: caminhos de arquivo, regra aplicável, evidência observada e ação proposta. Não é uma garantia de que a integração funciona nem de que passará pela revisão do projeto. Só depois de aprovar a proposta conceda escrita em uma branch de desenvolvimento. Revise o diff, execute os testes pertinentes e confira efeitos em uma instância de teste antes de abrir uma contribuição ou implantar algo em casa.

Como ler a escala de qualidade sem transformá-la em selo automático

A Integration Quality Scale oficial separa regras por níveis. A Skill orienta conferir a chave quality_scale do manifesto e, quando presente, o estado done, exempt ou todo no quality_scale.yaml. Regras bronze formam a base, enquanto as de níveis superiores dependem do nível perseguido. Um marcador done não basta como prova: confira a implementação e os testes. Um exempt requer justificativa pertinente, não serve como atalho para encerrar um problema.

Para uma integração nova ou modificada, compare também a documentação de manifesto e configuração. O guia oficial do manifesto explica o papel de integration_type, requisitos e config_flow. Se o agente sugerir um campo que não está no contrato documentado ou deixar de tratar um fluxo de configuração existente, peça que mostre a fonte e revise o código. Não transplante um padrão de outra integração apenas porque ela tem muitos arquivos ou boa classificação.

Entidades, consultas e fronteiras do código

A Skill chama atenção para a simetria entre async_added_to_hass() e async_will_remove_from_hass(). Se uma entidade assina eventos quando entra, precisa cancelar essa assinatura ao sair. Isso evita callbacks órfãos e comportamento difícil de reproduzir depois de recarregar uma integração. Também alerta para não redeclarar atributos ou proteções que a classe base já oferece. A análise deve verificar a classe concreta e o ciclo de vida real, não apenas procurar os nomes dos métodos.

Outro limite é arquitetural: uma integração deve ser uma camada fina sobre bibliotecas de domínio, sem enterrar nela um parser complexo de protocolo ou um estado inteiro do dispositivo. A Skill desencoraja contornar defeitos de biblioteca com remendos locais. Em integrações que consultam dados periodicamente, ela diz para não oferecer scan_interval, update_interval ou frequência de polling como opção ao usuário no fluxo de configuração. Confira essa orientação no contexto do código e da versão em trabalho; não a converta em uma busca e substituição automática.

Diagnósticos, reparos e dados sensíveis

O arquivo platform-diagnostics.md aponta a plataforma diagnostics.py e destaca que um diagnóstico não deve expor senhas, tokens nem coordenadas sensíveis. A regra oficial de diagnósticos traz um exemplo de remoção de campos sensíveis antes da exportação. Não peça ao agente que registre um dump completo de configuração para “facilitar a depuração”. Faça a revisão de privacidade antes de compartilhar arquivos de diagnóstico em uma issue pública.

platform-repairs.md trata de problemas em repairs.py que o usuário consegue resolver. A mensagem precisa dizer o que ocorreu, por que importa, quais passos concretos seguir e o que esperar depois. Um aviso vago como “atualize o firmware” não é uma instrução suficiente. A severidade também pede critério: um alerta futuro não equivale a um problema crítico. Peça ao agente para identificar a ação real disponível ao usuário, ou explicar por que não cabe abrir um reparo.

Testes, revisão humana e erros comuns

A Skill recomenda testar o comportamento pela interface da integração, evitando depender de detalhes internos ou de mocks que só confirmam a implementação atual. A documentação oficial de testes orienta preparar o ambiente e executar a suíte do componente pertinente. Um teste aprovado localmente não demonstra compatibilidade com todo dispositivo, versão ou serviço externo. Documente quais testes rodaram e quais cenários continuaram sem cobertura.

Se o agente não encontrar a pasta de testes, confirme o domínio e se você está no repositório Core correto. Se ele reclamar que quality_scale.yaml não existe, não crie um arquivo apenas para silenciar a mensagem: verifique primeiro se a escala se aplica à integração. Se o devcontainer não iniciar, siga o erro específico de Docker, dependência ou acesso a hardware do guia oficial; a Skill não instala um ambiente. Se um teste falhar após mudança, compare o comportamento exposto e o diff antes de alterar a expectativa do teste. Não envie logs com credenciais para uma conversa pública.

Commit, licença e limites da curadoria

Esta cópia foi fixada no commit 9dc9881d37821579175a4f3297876df43d002985 do ramo dev. É uma fotografia do material, não uma promessa de compatibilidade eterna com todas as releases do Home Assistant. O projeto tinha 91.382 estrelas no GitHub na consulta de 11/10/2026, às 16h05 de São Paulo; esse número se refere ao repositório, não mede usuários da Skill. A licença Apache-2.0 permite redistribuição com as condições e avisos preservados. O texto integral segue no pacote local.

A escolha editorial foi priorizar uma Skill da organização que mantém o próprio Core, com caminho e commit identificáveis, documentação de desenvolvimento e licença conferíveis. Isso a diferencia de Skills não oficiais sobre automações e dashboards: aqui o foco é desenvolver e revisar integrações do Core. O Bastidores não executou testes com dispositivos nem certificou uma integração específica. A capa é uma ilustração editorial exclusiva, não uma captura real do produto.

Download local e fonte oficial são caminhos distintos

O card de download oferece o ZIP documental auditado na hospedagem do Bastidores. Confira o SHA-256, abra ORIGEM.md e só então copie a pasta para o seu cliente. O botão separado “Abrir repositório oficial” leva à pasta mantida pelo Home Assistant, onde você pode comparar conteúdo e acompanhar mudanças posteriores. Nenhum desses dois caminhos instala uma integração doméstica ou autoriza o agente a mexer em dispositivos. Para alterações reais, mantenha confirmação humana, revisão de diff, testes e controle de permissões.