How to Contribute or Add New Skills to reverse-skill: The 8-Step Technical Guide

Adding a new skill to reverse-skill requires creating a structured SKILL.md definition, registering the route in routing.json and MASTER-ROUTING.md, and adding any required tools to bootstrap-manifest.json with corresponding discovery entries in ToolDiscovery.ps1 or tool-discovery.sh.

The reverse-skill repository provides a modular, platform-agnostic skill router for reverse-engineering, exploitation, and security testing workflows. Contributing a new skill follows a rigorous three-layer pipeline—spanning the shared definition layer, router integration layer, and infrastructure layer—to ensure automatic skill selection, tool auto-bootstrapping, and cross-platform documentation consistency.

The Three-Layer Contribution Architecture

Before writing code, understand how the system processes skills:

1. Shared Layer: Skill definitions live in skills/<skill-name>/SKILL.md and contain mandatory execution contracts.
2. Router Layer: The central matrix in skills/config/routing.json maps keywords to skills, synchronized with skills/MASTER-ROUTING.md.
3. Infrastructure Layer: Tool discovery scripts (scripts/lib/ToolDiscovery.ps1 and kali/scripts/lib/tool-discovery.sh) and the bootstrap manifest (scripts/bootstrap-manifest.json) handle dependency resolution.

Step 1: Scaffold the Skill Structure

Create a new directory under skills/ using your skill name. At minimum, this folder must contain SKILL.md. Optionally include scripts/ for automation and references/ for documentation.

mkdir skills/ghidra-headless
touch skills/ghidra-headless/SKILL.md

Step 2: Write the SKILL.md Contract

The SKILL.md file must follow the format defined in skills/CONTRIBUTING.md (lines 48-106). It requires YAML front-matter, an ACTION REQUIRED block, and a Task-completion self-check section.

---
name: ghidra-headless
description: Headless Ghidra analysis for binaries without a GUI
---

# Ghidra Headless Skill

## 适用范围

- 需要在 CI/CD 环境或无图形界面服务器上对 ELF / PE 进行自动反编译。

## 工具依赖

| 工具 | 必需 | 用途 | 可自动安装 |
|------|------|------|------------|
| ghidra | ✅ | Ghidra headless `analyzeHeadless` | ✅ |

## ACTION REQUIRED（读完后立刻执行）

1. `NOW`：确认任务符合本 skill 的适用范围。
2. `NOW`：读取 `../tool-index.md`，校验 `ghidra` 是否可用。
3. `NEXT`：缺工具时调用 `bootstrap-reverse.ps1` → `bootstrap‑manifest.json` 中的 `ghidra` 条目。
4. `ACT`：运行 `scripts/analyze.ps1` 进行批量分析。

## 工作流

1. 收集目标二进制路径。
2. 调用 `analyzeHeadless` 生成 `.cfile`、`.bcode`。
3. 导出报告（`scripts/report.ps1`）。

## 任务完成自检（声称完成前 MUST 通过）

- □ 确认上述每一步已执行并产出文件。  
- □ 结果已写入 `tool-index.md`。  
- □ 已将经验写入 `field-journal/`。

Step 3: Register the Skill in the Router

Add your skill to the routing matrix so the system can automatically select it. Edit skills/config/routing.json (see the "更新路由" section, lines 51-55) to append a new route entry:

{
  "routes": [
    {
      "keyword": "ghidra‑headless",
      "skill": "ghidra-headless",
      "priority": 210
    }
  ]
}

Then add a corresponding test case to skills/tests/routing-benchmark.json to validate routing behavior. Finally, synchronize the priority order in skills/MASTER-ROUTING.md to maintain human-readable documentation.

Step 4: Define Tool Capabilities

If your skill requires external CLI tools, declare them in scripts/bootstrap-manifest.json (JSON schema defined in lines 81-94). This enables the auto-installer to fetch and verify dependencies.

{
  "name": "ghidra",
  "bootstrapKind": "github-release-zip",
  "repo": "NationalSecurityAgency/ghidra",
  "assetRegex": "^ghidra_.*_PUBLIC_.*\\.zip$",
  "installDir": "%USERPROFILE%\\Tools\\ghidra",
  "canAutoInstall": true,
  "verifyCommand": "analyzeHeadless"
}

Step 5: Implement Tool Discovery

The router must locate installed tools at runtime. Add discovery logic to scripts/lib/ToolDiscovery.ps1 for Windows (lines 106-119) or kali/scripts/lib/tool-discovery.sh for Kali Linux.

For PowerShell, insert a custom object like:

[pscustomobject]@{
    Name = 'analyzeHeadless'
    Skill = 'ghidra-headless'
    Purpose = 'Ghidra 无头分析'
    VersionArgs = @()
    Fallbacks = @(
        [pscustomobject]@{ Type = 'command'; Value = 'analyzeHeadless' },
        [pscustomobject]@{ Type = 'path'; Value = (Join-Path $env:USERPROFILE 'Tools\ghidra\support\analyzeHeadless.bat') }
    )
}

Step 6: Refresh Generated Indexes

After modifying tool definitions, regenerate the indexes so the router recognizes new capabilities.

On Windows:

.\skills\scripts\refresh-tool-index.ps1

On Kali:

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

Then update the master skill list by running extract-summaries.ps1 (or the equivalent script) to regenerate skills/INDEX.md.

Step 7: Validate Your Contribution

Execute the routing test suite to verify integration:

./skills/scripts/test-routing.sh

Run the coherence verification script to ensure routing consistency:

.\skills\scripts\verify-routing-coherence.ps1

All checks must pass before opening a pull request.

Step 8: Submit Your Pull Request

Open a PR referencing the new skill name and ensuring the checklist in skills/CONTRIBUTING.md is satisfied. Include the failing test case you added to routing-benchmark.json and confirm that skills/MASTER-ROUTING.md remains synchronized with skills/config/routing.json.

Summary

• Define your skill in skills/<name>/SKILL.md with mandatory ACTION REQUIRED and Task-completion self-check blocks.
• Register the route in skills/config/routing.json, add test cases to skills/tests/routing-benchmark.json, and sync skills/MASTER-ROUTING.md.
• Bootstrap tool dependencies by adding entries to scripts/bootstrap-manifest.json and implementing discovery in scripts/lib/ToolDiscovery.ps1 or kali/scripts/lib/tool-discovery.sh.
• Refresh indexes using skills/scripts/refresh-tool-index.ps1 or kali/scripts/refresh-tool-index.sh, then regenerate skills/INDEX.md.
• Verify with skills/scripts/test-routing.sh and skills/scripts/verify-routing-coherence.ps1 before submitting.

Frequently Asked Questions

What are the mandatory sections for a SKILL.md file?

A valid SKILL.md must include YAML front-matter with name and description, a tool dependency table, an ACTION REQUIRED block with immediate execution steps, and a Task-completion self-check checklist. These sections enforce the execution contract that the router expects, as detailed in skills/CONTRIBUTING.md lines 48-106.

Do I need to update both Windows and Kali discovery scripts?

Yes. If your skill supports both platforms, you must add corresponding discovery objects to scripts/lib/ToolDiscovery.ps1 for Windows and kali/scripts/lib/tool-discovery.sh for Kali Linux. This ensures the router can locate tools regardless of the operating system.

How does the router determine which skill to execute?

The router consults skills/config/routing.json, which maps keywords to specific skills using a priority integer. Higher priority values take precedence. When multiple routes match, the system selects the highest priority skill that has all required tools available according to the discovery scripts.

What validation must pass before I can open a pull request?

You must run skills/scripts/test-routing.sh (or the PowerShell equivalent) to validate routing logic, and skills/scripts/verify-routing-coherence.ps1 to ensure consistency between routing.json and MASTER-ROUTING.md. Additionally, your new skill must appear correctly in skills/INDEX.md after running the extraction script.

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