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

Contributing a new skill module to reverse-skill requires creating a directory scaffold with SKILL.md, registering tools in the bootstrap and discovery systems, and integrating with the routing matrix—each step explicitly defined in 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 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 section "目录结构模板":

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 is mandatory.

---

Step 2: Write a Complete SKILL.md

The contribution guide enforces exact section ordering and mandatory headings. Missing any element triggers CI failure. Required sections per 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 Template

---
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—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 section "接入 bootstrap 系统":

3.1 Add to bootstrap-manifest.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

3.2 Add to ToolDiscovery.ps1

[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 section "接入路由系统", routing integration requires four coordinated changes:

Action	File	Description
Add failing test	skills/tests/routing-benchmark.json	Test case that validates routing correctness
Add route entry	skills/config/routing.json	Keywords, skill mapping, priority score
Sync priority table	skills/MASTER-ROUTING.md	Human-readable priority documentation
Update narrative docs	routing.md (optional)	Descriptive routing guidance

Example routing.json Entry

{
  "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 section "刷新索引" and "验证清单":

# 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 (module table)
• INDEX.md (root index)

---

Step 6: Submit the Pull Request

Per 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 contains all mandatory sections including ACTION REQUIRED and 任务完成自检
• bootstrap-manifest.json entry added with accurate canAutoInstall flag
• ToolDiscovery.ps1 entry registered with fallback paths
• routing-benchmark.json includes new failing test case
• routing.json updated with keywords and priority
• 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 mandatory, scripts/ and references/ optional.
• Compliance is enforced: ACTION REQUIRED blocks and self-check sections are non-negotiable per CONTRIBUTING.md.
• Bootstrap triple-registration: 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?

Your PR will fail CI compliance checks. Per the engineered constraints in 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 and 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 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 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 and my module's SKILL.md?

The root 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.

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