How to Report a Bug in reverse-skill: A Step-by-Step Guide

Reporting a bug in reverse-skill requires searching existing issues first, then submitting a detailed issue with environment info, reproduction steps, and the affected skill directory from the skills/ folder.

The reverse-skill repository by zhaoxuya520 provides AI-driven reverse engineering methodologies organized as modular skills. When something breaks—whether in the routing system, a specific skill script, or tool detection—providing structured information helps maintainers reproduce and fix issues quickly. This guide walks through the complete bug reporting workflow based on the actual repository structure.

Before You Report: Search Existing Issues

Always check if your bug has already been reported. The repository README displays an Issues badge at line 14 that links directly to the GitHub issue tracker. Duplicate reports slow down triage and fragment discussion.

If you find a related issue, add your reproduction details as a comment rather than opening a new ticket.

Gather Required Context

A complete bug report in reverse-skill requires five categories of information:

• Operating Environment – OS (Windows, Linux, macOS), architecture (x86_64, ARM64), and shell (PowerShell, Bash, Zsh)
• reverse-skill Version – The exact commit hash from git rev-parse HEAD
• Affected Skill – The specific directory under skills/, such as skills/js-reverse/ or skills/ida-reverse/
• Tool Versions – Relevant tools like IDA, radare2, Ghidra, or Node.js with their versions
• Log Output – Console messages, stack traces, or screenshots showing the failure

The routing matrix in skills/routing.md determines which skill handles a given task. Including this context ensures maintainers can trace how the AI agent selected—or failed to select—the correct methodology.

Use the Bug Report Template

Copy and paste this markdown template into your GitHub issue description:

### Description

A short, clear description of what is wrong.

### Environment

- OS:  
- Architecture:  
- Shell: (PowerShell / Bash)  
- reverse-skill version: `git rev-parse HEAD`

### Steps to Reproduce

1.  
2.  
3.  

### Expected behavior

What you expected to happen.

### Actual behavior

What actually happened (include error messages, screenshots, logs).

### Additional context

*Skill directory:* `skills/<skill-name>/`  
*Tool(s) involved:* `<tool-name>`  
*Any relevant configuration files:* (e.g., `tool-index.md`, `bootstrap-manifest.json`)

The template references two critical configuration files:

• skills/tool-index.md – Auto-generated index of detected tools; include its state if tool detection fails
• scripts/bootstrap-manifest.json – Lists bootstrap capabilities for automatic tool installation

Submit and Follow Up

Click New issue on the GitHub issues page, paste your completed template, then click Submit new issue. The maintainers will link the issue to the appropriate skill module based on the directory you specified.

Respond promptly to requests for clarification. Issues close automatically when fixes merge, or you can close them after verifying the resolution.

Complete Bug Report Example

Here is a realistic issue body for a PowerShell crash in the JavaScript deobfuscation skill:

### Description

`deobfuscate.ps1` crashes with a "Missing variable" error when processing `sample.js`.

### Environment

- OS: Windows 11
- Architecture: x86_64
- Shell: PowerShell 7.4
- reverse-skill version: `c0a1b2f`

### Steps to Reproduce

1. `git clone https://github.com/zhaoxuya520/reverse-skill.git`
2. `cd reverse-skill && powershell -File skills/scripts/refresh-tool-index.ps1`
3. Run: `powershell -NoProfile -ExecutionPolicy Bypass -File skills/js-reverse/scripts/deobfuscate.ps1 -InputFile sample.js`

### Expected behavior

The script should output the deobfuscated JavaScript.

### Actual behavior

PowerShell throws:

ERROR: Missing variable $obfuscatedCode at line 42

### Additional context

*Skill directory:* `skills/js-reverse/`  
*Tool(s) involved:* Node.js 22.12, PowerShell 7.4  
*Relevant config:* `skills/tool-index.md` shows `node` and `powershell` as available.

Key Files for Reference

File	Purpose
README.md	Project overview with Issues badge
CONTRIBUTING.md	Contribution standards and community guidelines
skills/routing.md	Routing matrix for skill selection
skills/tool-index.md	Auto-generated tool detection index
scripts/bootstrap-manifest.json	Bootstrap capabilities manifest

Understanding these files helps you describe bugs accurately. The routing matrix in skills/routing.md is especially important when the AI agent selects the wrong skill or fails to route entirely.

Summary

• Search existing issues before reporting to avoid duplicates
• Include git rev-parse HEAD, OS, shell, and affected skills/<name>/ directory
• Paste the standard template and fill all sections completely
• Attach tool-index.md state and bootstrap-manifest.json details for tool-related bugs
• Follow up promptly when maintainers request additional information

Frequently Asked Questions

Where do I find the reverse-skill version to include in my report?

Run git rev-parse HEAD in your local reverse-skill clone. This outputs the exact commit hash. Paste this value into the Environment section so maintainers can pull the same code state.

What should I do if I am not sure which skill caused the bug?

Check skills/routing.md to understand how tasks map to skills. Describe the task you were attempting and any tools involved. Maintainers can trace the routing logic even if you cannot identify the exact skill directory.

Does reverse-skill have a formal bug bounty or security disclosure process?

The repository's CONTRIBUTING.md focuses primarily on skill creation standards. For security issues involving reverse engineering targets, use your judgment regarding disclosure timelines. Standard practice is coordinated disclosure after maintainers confirm a fix.

How do I report bugs in the tool detection or bootstrap system?

Include the output of skills/tool-index.md and relevant entries from scripts/bootstrap-manifest.json. These files control how reverse-skill detects and installs dependencies. Errors in automatic tool installation almost always trace to parsing or path issues in these two files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}