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

> Easily contribute to reverse-skill by following this 8-step technical guide. Learn to add new skills, define routes, and update manifest files for seamless integration into the repository.

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

---

**Adding a new skill to reverse-skill requires creating a structured [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) definition, registering the route in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) and [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md), and adding any required tools to [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json) with corresponding discovery entries in `ToolDiscovery.ps1` or [`tool-discovery.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) maps keywords to skills, synchronized with [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md).
3. **Infrastructure Layer**: Tool discovery scripts (`scripts/lib/ToolDiscovery.ps1` and [`kali/scripts/lib/tool-discovery.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/lib/tool-discovery.sh)) and the bootstrap manifest ([`scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md). Optionally include `scripts/` for automation and `references/` for documentation.

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

```

## Step 2: Write the SKILL.md Contract

The [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file must follow the format defined in [`skills/CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/CONTRIBUTING.md) (lines 48-106). It requires YAML front-matter, an **ACTION REQUIRED** block, and a **Task-completion self-check** section.

```markdown
---
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) (see the "更新路由" section, lines 51-55) to append a new route entry:

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

```

Then add a corresponding test case to [`skills/tests/routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tests/routing-benchmark.json) to validate routing behavior. Finally, synchronize the priority order in [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/bootstrap-manifest.json) (JSON schema defined in lines 81-94). This enables the auto-installer to fetch and verify dependencies.

```json
{
  "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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/lib/tool-discovery.sh) for Kali Linux.

For PowerShell, insert a custom object like:

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

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

```

On Kali:

```bash
./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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md).

## Step 7: Validate Your Contribution

Execute the routing test suite to verify integration:

```bash
./skills/scripts/test-routing.sh

```

Run the coherence verification script to ensure routing consistency:

```powershell
.\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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/CONTRIBUTING.md) is satisfied. Include the failing test case you added to [`routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing-benchmark.json) and confirm that [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) remains synchronized with [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), add test cases to [`skills/tests/routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tests/routing-benchmark.json), and sync [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md).
- **Bootstrap** tool dependencies by adding entries to [`scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/bootstrap-manifest.json) and implementing discovery in `scripts/lib/ToolDiscovery.ps1` or [`kali/scripts/lib/tool-discovery.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/lib/tool-discovery.sh).
- **Refresh** indexes using `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), then regenerate [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md).
- **Verify** with [`skills/scripts/test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) and [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md). Additionally, your new skill must appear correctly in [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md) after running the extraction script.