# How to Contribute a New Skill Module to the reverse-skill Repository: A Complete Guide

> Learn how to contribute a new skill module to the reverse-skill repository. Follow our complete guide to create scaffolds register tools and integrate with the routing matrix.

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

---

**Contributing a new skill module to reverse-skill requires creating a directory scaffold with [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md), registering tools in the bootstrap and discovery systems, and integrating with the routing matrix—each step explicitly defined in [`CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/CONTRIBUTING.md).**

The **reverse-skill** repository organizes security research workflows into modular, self-contained skill units. Each module bundles documentation, tool dependencies, and routing metadata to enable automated discovery and execution. This guide walks through the complete contribution pipeline, referencing the actual source files that enforce these patterns.

---

## When to Add a New Skill Module

Per [`CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/CONTRIBUTING.md) section *"什么时候该新增 skill"*, create a new module only when the target type, toolchain, or workflow is **distinct** from existing entries. Avoid duplication if the routing matrix already contains a suitable match.

- **Extension**: Add capabilities to an existing skill when workflows overlap significantly.
- **New module**: Required for new toolchains, targets, or analysis paradigms lacking routing coverage.

---

## Step 1: Create the Directory Scaffold

All skills live under `skills/<new-skill-name>/` with lower-case hyphenated naming. The minimum structure from [`CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/CONTRIBUTING.md) section *"目录结构模板"*:

```text
skills/
└── ghidra-headless/
    ├── SKILL.md          # required entry document

    ├── scripts/
    │   └── analyze.ps1   # optional automation scripts

    └── references/
        └── scripting-cheatsheet.md

```

Omit `scripts/` or `references/` if not needed, but [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) is mandatory.

---

## Step 2: Write a Complete [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md)

The contribution guide enforces **exact section ordering and mandatory headings**. Missing any element triggers CI failure. Required sections per [`CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/CONTRIBUTING.md) section *"SKILL.md 必须包含的内容"*:

| Section | Purpose |
|---------|---------|
| Front-matter (`name`, `description`) | Machine-readable metadata |
| `ACTION REQUIRED` | 4-step "NOW/NEXT/ACT" checklist (mandatory per compliance rules) |
| `工具依赖` | Table of required tools with auto-install flags |
| `工作流` | Step-by-step execution flow |
| `按需自举` | Bootstrap table mapping tools to install methods |
| `路由上下文` | Keywords and conditions for routing decisions |
| `任务完成自检` | Checkbox list for completion verification |

### Minimal [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) Template

```markdown
---
name: ghidra-headless
description: Headless Ghidra decompilation for binary analysis without UI.
---

# Ghidra Headless

## 适用范围

Binary decompilation scenarios where IDA Pro is unavailable.

## 工具依赖

| 工具 | 是否必需 | 用途 | 可自动安装 |
|------|----------|------|------------|
| ghidra | 必需 | Headless analysis | ✅ |

## 工作流

1. Verify `ghidra` availability via tool-index.
2. Run `analyzeHeadless` on target binary.
3. Export decompilation results to report.

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

1. NOW：确认任务属于 **二进制（无 IDA）** 场景。
2. NOW：读取 `../tool-index.md` 并确认 `ghidra` 可用。
3. NEXT：若缺工具，调用 bootstrap（`bootstrap-manifest.json` 中的 `ghidra` 条目）。
4. ACT：执行工作流第一步并生成报告。

## 任务完成自检

- □ 已执行工作流的每一步？
- □ 已使用 `tool-index` 中的真实工具路径？
- □ 已产出可复现的证据（命令、脚本、报告）？
- □ 已更新 `RULES` 中的 Checklist 项？

```

The **"ACTION REQUIRED"** and **"任务完成自检"** sections are *engineered constraints* per [`CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/CONTRIBUTING.md)—RFC 2119 terminology ("MUST", "SHALL") is expected throughout.

---

## Step 3: Register Tools in the Bootstrap System

New CLI tools or MCP servers require three registration points per [`CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/CONTRIBUTING.md) section *"接入 bootstrap 系统"*:

### 3.1 Add to [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json)

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

```

Path: [`scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/bootstrap-manifest.json)

### 3.2 Add to `ToolDiscovery.ps1`

```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') }
    )
}

```

Path: `skills/scripts/lib/ToolDiscovery.ps1`

### 3.3 Update `refresh-tool-index.ps1`

Add a script reference so the new tool appears in regenerated indexes.

---

## Step 4: Integrate with the Routing System

Per [`CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/CONTRIBUTING.md) section *"接入路由系统"*, routing integration requires four coordinated changes:

| Action | File | Description |
|--------|------|-------------|
| Add failing test | [`skills/tests/routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tests/routing-benchmark.json) | Test case that validates routing correctness |
| Add route entry | [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) | Keywords, skill mapping, priority score |
| Sync priority table | [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Human-readable priority documentation |
| Update narrative docs | [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) (optional) | Descriptive routing guidance |

### Example [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) Entry

```json
{
  "routes": [
    {
      "keywords": ["ghidra-headless", "binary-analysis", "decompile"],
      "skill": "ghidra-headless",
      "priority": 30
    }
  ]
}

```

Priority values determine match precedence—higher numbers win when multiple routes match.

---

## Step 5: Refresh Indexes and Verify

Run the refresh scripts per [`CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/CONTRIBUTING.md) section *"刷新索引"* and *"验证清单"*:

```powershell

# Windows: regenerate tool index

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

# Verify routing logic

powershell -NoProfile -ExecutionPolicy Bypass -File "skills/scripts/test-routing.ps1"

```

For Kali/Linux environments, use the `.sh` equivalents in `kali/scripts/`.

Also execute `extract-summaries.ps1` to rebuild:
- [`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md) (module table)
- [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/INDEX.md) (root index)

---

## Step 6: Submit the Pull Request

Per [`skills/field-journal/CONTRIBUTE-BACK.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/field-journal/CONTRIBUTE-BACK.md) section 7.1, use the PR template:

```

[skill] YYYY-MM-DD <skill-name>

```

CI automatically runs:
- Routing benchmark validation
- Tool-index completeness checks
- Compliance verification (mandatory sections, RFC 2119 usage)

---

## Contribution Checklist

- [ ] Directory follows lower-case hyphenated naming (`skills/<name>/`)
- [ ] [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) contains all mandatory sections including `ACTION REQUIRED` and `任务完成自检`
- [ ] [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json) entry added with accurate `canAutoInstall` flag
- [ ] `ToolDiscovery.ps1` entry registered with fallback paths
- [ ] [`routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing-benchmark.json) includes new failing test case
- [ ] [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) updated with keywords and priority
- [ ] [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) priority table synchronized
- [ ] Root indexes refreshed via `extract-summaries.ps1`
- [ ] `refresh-tool-index` executed and new tool appears in index
- [ ] All routing tests pass on both Windows and Kali platforms

---

## Summary

- **Scaffold first**: Create `skills/<name>/` with [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) mandatory, `scripts/` and `references/` optional.
- **Compliance is enforced**: `ACTION REQUIRED` blocks and self-check sections are non-negotiable per [`CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/CONTRIBUTING.md).
- **Bootstrap triple-registration**: [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json), `ToolDiscovery.ps1`, and index refresh script.
- **Routing requires four updates**: test case, machine config, priority table, and optional narrative docs.
- **Verification is cross-platform**: Run `.ps1` on Windows, `.sh` on Kali before PR.

---

## Frequently Asked Questions

### What happens if I skip the `ACTION REQUIRED` section in [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md)?

Your PR will fail CI compliance checks. Per the *engineered constraints* in [`CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/CONTRIBUTING.md), this section is mandatory for all skill modules—the section enforces immediate execution steps and uses RFC 2119 terminology to eliminate ambiguity.

### How do I determine the correct priority value for a new routing entry?

Examine [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) for comparable skills. Higher priority (typically 20-40) reserves routing for specialized tools over generic fallbacks. Add a failing test case to [`routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing-benchmark.json) first, then adjust priority until tests pass.

### Can I contribute a skill that wraps a proprietary tool without auto-install?

Yes. Set `canAutoInstall: false` in [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json) and provide manual installation guidance in `按需自举`. The `ToolDiscovery.ps1` entry should include robust fallbacks pointing to common install locations so the skill still functions if users install manually.

### What's the difference between [`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md) and my module's [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md)?

The root [`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md) is an auto-generated **index** of all modules—do not edit it directly. Your module's `skills/<name>/SKILL.md` is the **source document** you author. Run `extract-summaries.ps1` to regenerate the index after adding your module.