--- name: openclaw-skill-debugger description: "Identifica e resolve problemas comuns em AgentSkills do OpenClaw, incluindo: (1) Falhas de instalação via ClawHub, (2) Inconsistências de configuração (ex: paths absolutos), (3) Dependências ausentes ou mal documentadas, e (4) Erros de execução de scripts ou integração com APIs. Fornece um guia passo a passo para depurar e validar skills, garantindo sua correta operação em ambientes de quarentena ou produção. Use esta skill quando uma AgentSkill não se comporta como esperado ou você precisa auditar seu código." --- # OpenClaw Skill Debugger ## Visão Geral Esta skill foi projetada para auxiliar na depuração e análise de problemas em `AgentSkills` do OpenClaw. Ela fornece ferramentas e um fluxo de trabalho estruturado para identificar a causa raiz de falhas de instalação, erros de execução, problemas de dependência e outras inconsistências que podem impedir o funcionamento correto de uma skill. ## Workflow de Uso Ao depurar uma skill, siga estas etapas: 1. **Entender o Problema**: Comece coletando o máximo de informações possível sobre o erro: mensagens de erro, logs, passos para reproduzir o problema e o comportamento esperado da skill. 2. **Verificação Inicial**: Use os scripts de verificação rápida e consulte os documentos de referência para identificar problemas comuns. * **Caminhos Absolutos/Hardcoded**: Execute `scripts/check-hardcoded-paths.sh ` para procurar paths que podem causar problemas de portabilidade. * **Dependências**: Consulte `references/common-skill-issues.md` e execute `scripts/verify-dependencies.sh ` (se implementado) para confirmar que todos os pré-requisitos estão satisfeitos e corretamente documentados. * **Scripts Auxiliares Ausentes**: Verifique se todos os scripts referenciados no `SKILL.md` da skill alvo existem no seu diretório `scripts/`. 3. **Análise Detalhada**: Se as verificações iniciais não resolverem, siga o `references/debug-workflow.md` para uma análise mais aprofundada, incluindo a revisão do código-fonte da skill, logs do OpenClaw e testes em ambiente isolado. 4. **Correção e Validação**: Implemente as correções necessárias e teste a skill exaustivamente para garantir que o problema foi resolvido. ## Scripts ### `scripts/check-hardcoded-paths.sh` Este script recebe o caminho para uma skill e varre seus arquivos em busca de padrões que indicam o uso de caminhos absolutos ou "hardcoded" (ex: `/home/usuario/`, `/var/`, `/etc/`). * **Uso:** `bash scripts/check-hardcoded-paths.sh ` ### `scripts/verify-dependencies.sh` (TODO) **(Ainda a ser implementado)** Este script verificará se as dependências listadas no `SKILL.md` da skill alvo estão instaladas no ambiente. ## Referências ### `references/common-skill-issues.md` Este documento detalha problemas comuns encontrados no desenvolvimento e execução de skills do OpenClaw, como: * Caminhos absolutos em scripts. * Scripts auxiliares referenciados que não existem. * Declaração incorreta ou ausente de dependências. * Riscos e precauções ao usar `npx` para instalação (execução de código remoto). * Problemas de integração com telemetria (ex: falhas na emissão de logs OTLP como discutido no Issue #18794). ### `references/debug-workflow.md` Este documento fornece um fluxo de trabalho estruturado para depurar skills, desde a reprodução do problema até a identificação da causa raiz e a aplicação da correção. Inclui etapas como: * Isolamento do problema. * Revisão de logs do sistema e da skill. * Uso de ambientes de quarentena. * Técnicas de inspeção de código.