| 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:
- 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.
- 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 <caminho-da-skill> para procurar paths que podem causar problemas de portabilidade.
- Dependências: Consulte
references/common-skill-issues.md e execute scripts/verify-dependencies.sh <caminho-da-skill> (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/.
- 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.
- 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 <caminho-da-skill-a-depurar>
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.
