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

> Learn how to report a bug in reverse-skill with this step-by-step guide. Find existing issues and submit clear bug reports for the zhaoxuya520/reverse-skill repository.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-04

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```markdown

### 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md)** – Auto-generated index of detected tools; include its state if tool detection fails
- **[`scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```markdown

### 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README.md) | Project overview with Issues badge |
| [`CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/CONTRIBUTING.md) | Contribution standards and community guidelines |
| [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) | Routing matrix for skill selection |
| [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) | Auto-generated tool detection index |
| [`scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/bootstrap-manifest.json) | Bootstrap capabilities manifest |

Understanding these files helps you describe bugs accurately. The routing matrix in [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) state and [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) and relevant entries from [`scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.