How to Migrate Existing Analysis Workflows into the reverse‑skill Framework: A Complete Migration Guide

TLDR: To migrate any existing security or reverse‑engineering workflow into the reverse‑skill framework, classify your target artifact and intent against the three‑axis routing matrix, initialize a sandboxed case workspace with case‑init.ps1, replace hard‑coded tool paths with ${ToolIndex.<tool>} references, and record each step using append‑evidence.ps1 for reproducible journaling and auto‑evolution.

The reverse‑skill repository provides a structured, layered architecture for security analysis that transforms ad‑hoc scripts into reproducible, routable, and automatically documented workflows. Migrating existing workflows—whether Bash automation, Python analysis pipelines, or manual tool chains—requires mapping your legacy logic onto the framework's routing matrix, tool‑index abstraction, and evidence‑finding‑path contract. This guide walks through the complete migration pipeline as implemented in zhaoxuya520/reverse‑skill.

Understanding the Framework's Core Architecture

Before migrating, grasp how reverse‑skill orchestrates analysis tasks. The framework centers on three interconnected systems defined in docs/ARCHITECTURE.md:

• Routing Matrix: A three‑axis classifier combining target type (APK, ELF, PCAP, AD domain), user intent (enumerate, exploit, report), and toolchain (Ghidra, nmap, Impacket, etc.)
• Tool Index: Auto‑generated registry at skills/tool-index.md that abstracts tool paths and versions
• Field Journal: Append‑only evidence log enabling auto‑evolution—the reuse of past findings in future analyses

Every migrated workflow gains these capabilities without modifying underlying security logic.

Step‑by‑Step Migration Pipeline

Follow these six stages to migrate any existing analysis workflow into reverse‑skill.

Step 1: Decompose Your Original Workflow

Extract three elements from your legacy script or process:

• Target artifact: What are you analyzing? (binary file, network capture, mobile app)
• User intent: What outcome do you need? (disassembly, vulnerability discovery, credential extraction, reporting)
• Toolchain: Which tools does your workflow invoke? (both installed binaries and custom scripts)

This tri‑axis classification matches the input format required by skills/routing.md. Document these explicitly—they drive every subsequent decision.

Step 2: Map to an Existing or New Skill Module

Query the routing matrix in skills/routing.md to locate the appropriate skill folder:

Target Type	Likely Skill Folder
Android APK	skills/apk-reverse/
Windows AD environment	skills/windows-ad/
Network penetration testing	skills/pentest-tools/

If no match exists, create a new skill following the Route Not Matched protocol documented at skills/routing.md#L70. This involves defining your target‑intent‑tool combination and proposing it for inclusion in MASTER-ROUTING.md.

Step 3: Initialize a Sandboxed Case Workspace

The case‑init.ps1 script enforces the gate‑keeping contract from RULES.md and ops/scope-contract.md. It creates a reproducible environment with scope.md, timeline, and sandbox profile.

powershell -File skills/scripts/case-init.ps1 `
    -Hint "Binary analysis of firmware.bin with Ghidra and custom extractor" `
    -CaseName "firmware-analysis" `
    -AuthGranted `
    -TargetUrl "file://$(pwd)/firmware.bin"

This generates work/firmware-analysis/ containing all required metadata structures.

Step 4: Replace Hard‑Coded Tool Paths with Tool‑Index References

The framework discovers and registers tools via skills/tool-index.md (generated from skills/tool-index.md.template). Update your scripts to use ${ToolIndex.<ToolName>} variables instead of absolute paths.

Old approach (brittle, environment‑dependent):

/opt/tools/ghidra_10.2.2/ghiraRun.sh -process firmware.bin

New approach (portable, auto‑bootstrapped):

& $ToolIndex.Ghidra -process "$(pwd)/firmware.bin" -analysis

Missing tools trigger automatic installation via bootstrap-manifest.json as described in docs/ARCHITECTURE.md#L11.

Step 5: Record Evidence for Each Workflow Stage

After every substantive operation, invoke append‑evidence.ps1 to populate the field-journal. This enables the auto‑evolution mechanism to leverage your results in future analyses (docs/ARCHITECTURE.md#L52).

powershell -File skills/scripts/append-evidence.ps1 `
    -CaseRoot work/firmware-analysis `
    -Id "E-001" `
    -Title "Ghidra decompilation complete" `
    -ReproCommand "$ToolIndex.Ghidra -process $(pwd)/firmware.bin -analysis"

Step 6: Generate Structured Documentation

Produce markdown/HTML reports with embedded Mermaid diagrams for knowledge reuse:

powershell -File skills/scripts/generate-report.ps1 -CaseRoot work/firmware-analysis

Reports write back to the journal, completing the feedback loop for auto‑evolution.

Complete Migration Example: Binary Analysis Pipeline

Below is a full migration skeleton for a legacy workflow using Ghidra, Binwalk, and a custom Python post‑processor.

# 1️⃣ Initialize case workspace

powershell -File skills/scripts/case-init.ps1 `
    -Hint "Firmware RE: Ghidra + Binwalk + custom entropy analyzer" `
    -CaseName "fw-entropy-re" -AuthGranted `
    -TargetUrl "file://$(pwd)/suspected_backdoor.bin"

# 2️⃣ Refresh tool index (bootstrap missing tools)

powershell -File skills/scripts/verify-tool-index.ps1

# 3️⃣ Execute Ghidra via tool index

& $ToolIndex.Ghidra -process "$(pwd)/suspected_backdoor.bin" -analysis

# 4️⃣ Record Ghidra evidence

powershell -File skills/scripts/append-evidence.ps1 `
    -CaseRoot work/fw-entropy-re -Id "E-001" `
    -Title "Static analysis: primary functions identified" `
    -ReproCommand "$ToolIndex.Ghidra -process $(pwd)/suspected_backdoor.bin -analysis"

# 5️⃣ Execute Binwalk extraction

& $ToolIndex.Binwalk -e "$(pwd)/suspected_backdoor.bin"

# 6️⃣ Record Binwalk evidence

powershell -File skills/scripts/append-evidence.ps1 `
    -CaseRoot work/fw-entropy-re -Id "E-002" `
    -Title "Embedded filesystem extracted" `
    -ReproCommand "$ToolIndex.Binwalk -e $(pwd)/suspected_backdoor.bin"

# 7️⃣ Run custom Python analyzer (now a skill helper)

python "$(pwd)/skills/fw-entropy-re/helpers/entropy_analyze.py" `
    "$(pwd)/work/fw-entropy-re/extracted/"

# 8️⃣ Record custom analysis

powershell -File skills/scripts/append-evidence.ps1 `
    -CaseRoot work/fw-entropy-re -Id "E-003" `
    -Title "Entropy analysis: anomalous regions flagged" `
    -ReproCommand "python skills/fw-entropy-re/helpers/entropy_analyze.py $(pwd)/work/fw-entropy-re/extracted/"

# 9️⃣ Generate final report

powershell -File skills/scripts/generate-report.ps1 -CaseRoot work/fw-entropy-re

Key Configuration Files and Their Roles

File	Location	Purpose
MASTER-ROUTING.md	skills/MASTER-ROUTING.md	Primary fast‑path routing logic for common analysis patterns
routing.md	skills/routing.md	Complete three‑axis routing matrix with fallback protocols
tool-index.md.template	skills/tool-index.md.template	Template for auto‑generating tool registry
ARCHITECTURE.md	docs/ARCHITECTURE.md	Visual system overview and subsystem interactions
RULES.md	Repository root	Global contracts enforced by gate‑keeping scripts
ops/scope-contract.md	skills/ops/scope-contract.md	Detailed scope enforcement specifications
case-init.ps1	skills/scripts/case-init.ps1	Workspace initialization with sandbox profiles
append-evidence.ps1	skills/scripts/append-evidence.ps1	Field journal population helper
generate-report.ps1	skills/scripts/generate-report.ps1	Documentation and diagram generation

Scaling to Complex Multi‑Stage Pipelines

For workflows spanning multiple target types or requiring orchestration across skills, reference the CTF-Sandbox-Orchestrator/ implementation. This demonstrates large‑scale skill composition that can be replicated for custom enterprise pipelines. The orchestrator pattern uses the same evidence‑finding‑path contract at each stage, enabling seamless handoffs between reverse‑engineering, penetration testing, and reporting modules.

Summary

• Classify your workflow using target type × intent × toolchain against skills/routing.md
• Initialize sandboxed cases via case‑init.ps1 to enforce scope contracts
• Abstract tool references through ${ToolIndex.<tool>} for portability across environments
• Record every operation with append‑evidence.ps1 to enable auto‑evolution
• Generate structured reports automatically for knowledge reuse and compliance

Frequently Asked Questions

What if my workflow uses custom or proprietary tools not in the tool index?

Register them manually in skills/tool-index.md following the template format, or add an installation entry to bootstrap-manifest.json. The framework treats all tools uniformly once indexed—custom scripts, commercial binaries, and containerized tools all use the same ${ToolIndex.<name>} reference pattern.

Can I migrate workflows incrementally or must I convert everything at once?

Incremental migration is fully supported. Wrap your existing script as a single evidence step initially, then progressively decompose it into discrete, recorded operations. The framework accepts hybrid approaches where some stages use tool‑index references while others invoke legacy logic directly until refactored.

How does the evidence journal enable auto‑evolution?

Each evidence record in the field-journal includes a reproducible command string and structured metadata. Future analyses query this journal to discover applicable prior findings, avoiding redundant computation. The system described in docs/ARCHITECTURE.md#L52 automatically surfaces relevant historical evidence when routing new cases with matching target‑intent profiles.

What authorization controls exist for sensitive analysis workflows?

The -AuthGranted flag in case-init.ps1 signals explicit scope approval per RULES.md. Additional constraints are enforced through ops/scope-contract.md, which defines role‑based access, timeline checkpoints, and evidence tamper‑proofing. These contracts apply uniformly regardless of whether the underlying workflow is native to reverse‑skill or migrated from external sources.

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