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

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 and 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. The project separates concerns across three main layers:

• Routing layer – Maps natural language intent to skill endpoints via skills/routing.md
• Skill layer – Self-contained units under skills/<skill-name>/ with 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

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

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

Consult skills/MASTER-ROUTING.md for fast-track patterns that bypass complex routing decisions.

2. Create the Skill Definition with SKILL.md

Every skill requires a SKILL.md entry point at skills/<skill-name>/SKILL.md. This file must include two mandatory blocks as specified in 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:

# 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 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 for Windows environments
• 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:

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 at runtime. Append your tool to the appropriate catalog function:

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

[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:

# 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 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:

# 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	Detailed checklist, templates, and conventions
skills/MASTER-ROUTING.md	Fast-track routing configuration
skills/routing.md	Complete intent-to-skill mapping matrix
skills/SKILL.md	Central aggregation point for all skills
docs/ARCHITECTURE.md	System layers and data flow visualization
scripts/bootstrap-manifest.json	Windows auto-install definitions
kali/scripts/bootstrap-manifest.json	Kali Linux auto-install definitions
skills/tool-index.md	Generated runtime tool availability index

Contribution Validation Checklist

Before submitting your pull request, verify:

• SKILL.md contains ACTION REQUIRED and self-check blocks
• Routing entry added to 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 if architecture changed

Summary

• Route first: Add your skill to skills/routing.md so the system can discover it
• Contract always: Include mandatory ACTION REQUIRED and self-check blocks in every SKILL.md
• Bootstrap completely: Register in the correct 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
• Document changes: Keep 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, 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. 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) locally to validate that your tool appears in skills/tool-index.md. Then use the intent patterns you defined in skills/routing.md against the routing test utilities if available, or manually verify pattern matching logic against 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) and Kali Linux (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.

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