# How to Contribute to the reverse-skill Project: A Step-by-Step Guide for Security Tooling Developers

> Learn how to contribute to the reverse-skill project with this step-by-step guide. Follow five key steps to integrate your security tooling and enhance the project.

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

---

**To contribute to reverse-skill, you must follow a five-step contract: update the routing matrix, create a SKILL.md with mandatory blocks, register the tool in bootstrap-manifest.json, refresh the tool index, and keep documentation synchronized—all enforced by RULES files that gate AI agent execution.**

The **reverse-skill** repository is a modular routing system that connects AI-driven security tasks to specialized reverse engineering and penetration testing tools. Its architecture centers on a **master routing layer** ([`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) and [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md)) that translates user intent into concrete skill executions. Whether you're adding support for a new decompiler, extending the Ghidra integration, or building an automated pentest chain, understanding how to contribute to reverse-skill ensures your work integrates seamlessly with the system's auto-bootstrap and discovery mechanisms.

## Understanding the reverse-skill Architecture

Before writing any code, review the system's layered design documented in [`docs/ARCHITECTURE.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md). The project separates concerns across three main layers:

- **Routing layer** – Maps natural language intent to skill endpoints via [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md)
- **Skill layer** – Self-contained units under `skills/<skill-name>/` with [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) entry points
- **Bootstrap layer** – Auto-installation manifests and discovery scripts in `scripts/` and `kali/scripts/`

Each layer communicates through **well-defined contracts** enforced by RULES files. These files act as gates: no AI agent may execute a skill that violates the contract. This design ensures contributions remain **reproducible, auto-bootstrappable, and immediately usable** by other agents.

## The Five-Step Contribution Contract

### 1. Update the Routing Matrix in [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md)

The routing matrix is the system's nervous system. To make your skill discoverable, add a row linking intent keywords to your skill directory:

```markdown
| Intent Pattern | Skill Path | Priority | Conditions |
|----------------|------------|----------|------------|
| `ghidra.*headless|batch.*analysis` | `skills/ghidra-headless/` | 2 | `tool-index.ghidra.available == true` |

```

Consult [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) for fast-track patterns that bypass complex routing decisions.

### 2. Create the Skill Definition with [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md)

Every skill requires a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) entry point at `skills/<skill-name>/SKILL.md`. This file must include two **mandatory blocks** as specified in [`skills/CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/CONTRIBUTING.md):

- **ACTION REQUIRED** – Explicit steps the AI agent must execute
- **Self-check** – Verification commands to confirm successful execution

Here is a minimal template structure:

```markdown

# ghidra-headless

## Description

Batch binary analysis using Ghidra's headless analyzer.

## ACTION REQUIRED

1. Locate target binary in `%WORKSPACE%`
2. Run: `analyzeHeadless %PROJECT_PATH% %PROJECT_NAME% -import %BINARY% -postScript analysis.py`
3. Export results to `%OUTPUT_DIR%/ghidra-results.json`

## Self-check

- Verify `%OUTPUT_DIR%/ghidra-results.json` exists and contains `> 0` functions
- Confirm no fatal errors in `%LOG_PATH%/ghidra.log`

```

The [`skills/CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/CONTRIBUTING.md) file contains the complete template with all required sections and naming conventions.

### 3. Register in the Bootstrap Manifest

The reverse-skill system auto-installs tools via **bootstrap manifests**. Choose the appropriate file for your target platform:

- [`scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/bootstrap-manifest.json) for Windows environments
- [`kali/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/bootstrap-manifest.json) for Kali Linux

A bootstrap entry specifies how to fetch, install, and verify a tool. Here is a complete Windows registration example using `jq`:

```bash
jq '.capabilities += [{
  "name": "ghidra",
  "bootstrapKind": "github-release-zip",
  "repo": "NationalSecurityAgency/ghidra",
  "assetRegex": "^ghidra_.*_PUBLIC_.*\\.zip$",
  "installDir": "%USERPROFILE%\\\\Tools\\\\ghidra",
  "canAutoInstall": true,
  "verifyCommand": "analyzeHeadless"
}]' bootstrap-manifest.json > tmp && mv tmp bootstrap-manifest.json

```

Key fields:
- **bootstrapKind** – Download method (`github-release-zip`, `apt`, `pip`, etc.)
- **assetRegex** – Pattern to match release artifacts
- **verifyCommand** – Executable that must exist post-installation

### 4. Add Tool Discovery Registration

The discovery scripts populate [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) at runtime. Append your tool to the appropriate catalog function:

For PowerShell (`scripts/lib/ToolDiscovery.ps1`):

```powershell
[PSCustomObject]@{
    Name = "ghidra"
    Category = "static-analysis"
    Verified = (Get-Command analyzeHeadless -ErrorAction SilentlyContinue -ne $null)
    Path = (Get-Command analyzeHeadless -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Source)
    Version = (& analyzeHeadless -version 2>$null | Select-String "GhidraVersion")
}

```

### 5. Refresh the Tool Index and Update Documentation

Run the platform-specific refresh script to regenerate [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md):

```powershell

# Windows

powershell -NoProfile -ExecutionPolicy Bypass -File "skills/scripts/refresh-tool-index.ps1"

# Kali Linux

bash kali/scripts/refresh-tool-index.sh

```

Finally, update [`docs/ARCHITECTURE.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md) if your skill introduces new patterns or data flows, and ensure your skill appears in any relevant key files lists.

## Complete Contribution Workflow

Here is the full command sequence from fork to pull request:

```bash

# 1. Fork and clone

git clone https://github.com/your-username/reverse-skill.git
cd reverse-skill

# 2. Create skill structure

mkdir -p skills/ghidra-headless
cp skills/TEMPLATE/SKILL.md skills/ghidra-headless/SKILL.md

# Edit SKILL.md with your specific ACTION REQUIRED and self-check blocks

# 3. Register bootstrap (edit file directly or use jq as shown above)

# scripts/bootstrap-manifest.json

# 4. Add discovery entry

# scripts/lib/ToolDiscovery.ps1

# 5. Update routing

# Edit skills/routing.md

# 6. Refresh indexes

powershell -NoProfile -ExecutionPolicy Bypass -File "skills/scripts/refresh-tool-index.ps1"

# 7. Commit and push

git checkout -b feature/ghidra-headless
git add .
git commit -m "Add ghidra-headless skill with bootstrap registration

- Implements headless batch analysis workflow
- Auto-installs from NSA GitHub releases
- Includes self-check verification for JSON output"
git push origin feature/ghidra-headless

# 8. Open Pull Request on https://github.com/zhaoxuya520/reverse-skill

```

## Critical Files to Reference

| Path | Purpose |
|------|---------|
| [`skills/CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/CONTRIBUTING.md) | Detailed checklist, templates, and conventions |
| [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Fast-track routing configuration |
| [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) | Complete intent-to-skill mapping matrix |
| [`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md) | Central aggregation point for all skills |
| [`docs/ARCHITECTURE.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md) | System layers and data flow visualization |
| [`scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/bootstrap-manifest.json) | Windows auto-install definitions |
| [`kali/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/bootstrap-manifest.json) | Kali Linux auto-install definitions |
| [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) | Generated runtime tool availability index |

## Contribution Validation Checklist

Before submitting your pull request, verify:

- [ ] [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) contains **ACTION REQUIRED** and **self-check** blocks
- [ ] Routing entry added to [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) with appropriate intent patterns
- [ ] Bootstrap manifest entry includes `verifyCommand` and `canAutoInstall: true`
- [ ] Discovery script registration returns proper object structure
- [ ] `refresh-tool-index.ps1` or `.sh` runs without errors
- [ ] No RULES violations detected by local validation (if available)
- [ ] Documentation updated in [`docs/ARCHITECTURE.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md) if architecture changed

## Summary

- **Route first**: Add your skill to [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) so the system can discover it
- **Contract always**: Include mandatory **ACTION REQUIRED** and **self-check** blocks in every [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md)
- **Bootstrap completely**: Register in the correct [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json) with valid `verifyCommand`
- **Discover properly**: Add entries to `ToolDiscovery.ps1` or equivalent
- **Refresh indexes**: Run platform-specific scripts to update [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md)
- **Document changes**: Keep [`docs/ARCHITECTURE.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md) synchronized with new patterns

Following this contract ensures your contribution to reverse-skill works immediately for AI agents and human operators alike.

## Frequently Asked Questions

### What happens if I skip the self-check block in SKILL.md?

The **RULES** files that gate AI agent execution will reject your skill. According to [`skills/CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/CONTRIBUTING.md), the self-check block is mandatory because it provides the verification mechanism that agents use to confirm successful execution. Without it, your skill cannot be trusted in automated workflows.

### Can I contribute a skill that requires manual installation only?

Yes, but you must set `canAutoInstall: false` in the bootstrap manifest and provide detailed **manual installation instructions** in your [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md). The system will still index your tool if discovery scripts detect it, but agents will route users to manual setup rather than attempting auto-bootstrap.

### How do I test my routing changes without deploying?

Run the refresh scripts (`skills/scripts/refresh-tool-index.ps1` or [`kali/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/refresh-tool-index.sh)) locally to validate that your tool appears in [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md). Then use the intent patterns you defined in [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) against the **routing test utilities** if available, or manually verify pattern matching logic against [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) fast-track rules.

### Which platforms does reverse-skill support for bootstrapping?

As of the source code analysis, reverse-skill maintains bootstrap manifests for **Windows** ([`scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/bootstrap-manifest.json)) and **Kali Linux** ([`kali/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/bootstrap-manifest.json)). Contributions for additional platforms require creating new manifest files and corresponding discovery scripts following the established JSON schema and PowerShell/Bash patterns.