# How to Migrate Existing Analysis Workflows into the reverse‑skill Framework: A Complete Migration Guide > Migrate analysis workflows to reverse-skill easily. Classify artifacts, initialize workspaces, update tool paths, and record steps for reproducible journaling and auto-evolution. Get the complete migration guide. - Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill) - Tags: migration-guide - Published: 2026-08-05 --- **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.}` 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md). ### Step 3: Initialize a Sandboxed Case Workspace The `case‑init.ps1` script enforces the gate‑keeping contract from [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) and [`ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/ops/scope-contract.md). It creates a reproducible environment with [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md), timeline, and sandbox profile. ```powershell 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) (generated from `skills/tool-index.md.template`). Update your scripts to use `${ToolIndex.}` variables instead of absolute paths. Old approach (brittle, environment‑dependent): ```bash /opt/tools/ghidra_10.2.2/ghiraRun.sh -process firmware.bin ``` New approach (portable, auto‑bootstrapped): ```powershell & $ToolIndex.Ghidra -process "$(pwd)/firmware.bin" -analysis ``` Missing tools trigger automatic installation via [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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 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 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. ```powershell # 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) | [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Primary fast‑path routing logic for common analysis patterns | | [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) | [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/ARCHITECTURE.md) | [`docs/ARCHITECTURE.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md) | Visual system overview and subsystem interactions | | [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) | Repository root | Global contracts enforced by gate‑keeping scripts | | [`ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/ops/scope-contract.md) | [`skills/ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) - **Initialize** sandboxed cases via `case‑init.ps1` to enforce scope contracts - **Abstract** tool references through `${ToolIndex.}` 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) following the template format, or add an installation entry to [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json). The framework treats all tools uniformly once indexed—custom scripts, commercial binaries, and containerized tools all use the same `${ToolIndex.}` 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md). Additional constraints are enforced through [`ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.