Skip to content
REVERSE-SKILL

Tutorial · from zero to first case

You hand your agent the repo.
It handles the rest.

One startup prompt, one authorized task — environment detection, routing, tool checks, and reporting are automatic. This page shows what happens under the hood and how to verify it.

v1.1.041 routing rules163 regression cases42 tracked modulesWindows + Ubuntu CI

What you're reading

This site is an English-first rebuild of the MIT-licensed upstream reverse-skill project. The tutorial below documents the upstream project's workflow; commands and file references point to the upstream repository.

00

Before you start

reverse-skill is a client-neutral routing package — it is not tied to Claude Code, Codex, Cursor, OpenCode, or any other client. In normal use you do not run the workflow yourself. Open the repository with an AI agent, let it read README_AI.md, and give it an authorized task. Everything below exists so you can audit what the agent does and debug it when something goes wrong.

This page is organized exactly like the tutorial shipped with the project: from zero to your first case, with the automation shown step by step.

What you get

  • 41 structured routing rules (R0–R40)
  • Client-neutral skill modules and optional adapters
  • A local tool index with on-demand bootstrapping
  • Scope · Timeline · Evidence · Finding · Review chain

What the agent auto-checks

  • OS, distribution, and real install paths
  • Git, PowerShell / Bash, Node.js, Python
  • Whether the task needs Java / JDK or special tools
  • What it may auto-install — and what needs your approval
01

Pick your usage path

Authorization and network behavior differ per task type. Choose the path before starting — don't mix them:

PathNetwork profileTypical targets
Local samplesofflineAPKs, EXEs, firmware — files you own. No external connections.
Isolated lab / CTFlab_onlyYour own range or a public competition's explicit targets.
Authorized online targetauthorized_target_onlyAssets with written authorization and an inventory list.

The authorization gate is not optional

Before any action against a target, the agent must run case-init and confirm auth.status=granted plus a network_profile. Until then only read-only planning and preparation are allowed.
02

AI auto-initialization

After reading README_AI.md, the agent performs the setup itself and reports what changed. These commands show what it runs and what to check when debugging — not what you should type by hand.

Platform detection

The agent picks its entry point from the real system: Windows uses the PowerShell scripts, Kali Linux has its own bootstrap, generic Linux and macOS use the Bash scripts.

windows · refresh tool index
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/refresh-tool-index.ps1
linux / macOS · refresh tool index
bash skills/scripts/refresh-tool-index.sh

The tool index is the source of truth

skills/tool-index.md and skills/tool-index.json record what is actually installed on this machine with real paths. They are gitignored and generated on first run — do not copy another machine's index. The agent only bootstraps tools marked missing that the current PRIMARY skill actually requires.

windows · bootstrap a capability
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/bootstrap-reverse.ps1 -Capability @('jadx')
linux · list & bootstrap
bash skills/scripts/bootstrap-reverse.sh --list
bash skills/scripts/bootstrap-reverse.sh jadx

Commercial tools are different

IDA Pro, JEB, and BurpSuite may require a license or an in-app extension. Bootstrap only provides guidance — it never bypasses licensing, downloads unknown binaries, or fakes a successful install.
03

AI client integration

Integration means opening the repository with your agent and letting it read the bootstrap files. There is no plugin to install and no routing config to copy into your client.

ClientOpen asMust read
CodexWorkspaceAGENTS.md, README_AI.md, RULES.md
Claude CodeRepo rootREADME_AI.md, RULES.md
Cursor / Cline / WindsurfOpen folderREADME_AI.md, RULES.md — allow reading skills/
OpenCodeProjectREADME_AI.md, RULES.md
OthersProject instructionsREADME_AI.md, RULES.md

Client-neutral by contract

Switching clients must not change routing results or the case structure. skills/config/routing.json is the single source of truth for routing; clients only change how project instructions are loaded.
04

Your first authorized case

The only thing you supply is the task description. The agent handles routing, case initialization, scope structure, and guards automatically — it must never invent authorization for you. If anything is missing, it stops and asks.

Write the task prompt like this — the more specific, the more reliable the generated scope:

task prompt template
Target and ownership: <local file / lab URL / authorized target>
Authorization evidence: <ticket, contract, competition page, proof of ownership>
Allowed actions: <static analysis, replay, limited validation, ...>
Forbidden actions: <DoS, out-of-scope assets, real user data, ...>
Network mode: offline / lab_only / authorized_target_only
Deliverables: evidence, findings, reproduction, fixes, report

The scope contract, field by field

FieldExampleRule
auth.statusgrantedTraceable authorization basis; never inferred by the agent.
auth.evidence_of_authinternal ticket SEC-001Ticket, contract, competition page, or proof of ownership.
in_scope.assetshttps://lab.example/Assets listed one by one; no vague “all company domains”.
in_scope.activitiesrecon, reverse, reportOnly the actions you approved.
out_of_scope.activitiesDoS, phishing, data exfilExplicitly forbidden actions.
network_profile.modeauthorized_target_onlyNetwork only reaches the in_scope list.
signoff.ready_for_acttrueOnly true once every field above is complete.

Offline samples work the same way

For your own APK, EXE, or firmware, the agent initializes with --preset offline-sample --sample ./samples/app.apk (or the PowerShell equivalents). The entry point stays conservative: ready_for_act=false until you confirm file ownership and the “no external connections” rule.
05

The full workflow

What the agent executes in the background, for audit and debugging. Each step keeps its inputs, outputs, and intermediate artifacts.

  1. 01

    Task → structured routing

    routing.json scores the hint and picks PRIMARY. The reason is saved in work/master-route-*/route-scope.md so you can see why.

    powershell -File skills\scripts\master-route.ps1 -Hint "authorized frontend signature JS reverse"
  2. 02

    Route → authorized case

    case-init writes scope.md, timeline.md, and workitems.md; case-guard is the machine check before any ACT.

    powershell -File skills\scripts\case-init.ps1 -Hint "..." -CaseName "demo-js-signature" -AuthGranted -AuthBasis "written_contract" -EvidenceOfAuth "internal ticket SEC-001" -TargetUrl "https://lab.example/" -NetworkProfile authorized_target_only
  3. 03

    Case → scenario skill

    The agent opens the PRIMARY SKILL.md, records its ACTION REQUIRED checklist, tool needs, and expected evidence.

  4. 04

    Check & bootstrap missing tools

    Only tools marked missing that the current skill requires. Paths come from tool-index.md; nothing is guessed.

  5. 05

    Timeline during execution

    Every significant action is appended: time, role, command, result, artifacts, evidence IDs, next step. Failed attempts stay in the record.

  6. 06

    Evidence → Finding

    Only conclusions that cite one or more evidence IDs become findings, with impact, confidence, scope, and validation status.

  7. 07

    Read-only case review

    Before handoff the agent runs the strict review with hash verification; every error is a blocker.

    python3 skills/case-review/scripts/review_case.py work/demo-js-signature --verify-hashes --strict
  8. 08

    Report & learn

    The formal report lands in report/. Only de-identified, reusable lessons are written to field-journal.

06

Three example paths

Full walkthroughs of what the agent does for common task types. The user input is one line; the rest is automation.

A · own APK, offline

Network: offline, no outbound packets. Confirm file ownership and hash, keep the original read-only. Expected route: R1 → apk-reverse. Allowed: unpacking, static analysis, local emulation. Forbidden: public network, modifying the original.

example a · offline apk
bash skills/scripts/master-route.sh --hint "own APK jadx smali static analysis"
bash skills/scripts/case-init.sh --hint "own APK static analysis" --case-name apk-local-001 --preset offline-sample --sample ./samples/app.apk
bash skills/scripts/case-guard.sh --case-root work/apk-local-001

B · isolated web range

Network: lab_only. The sample address must belong to your isolated lab network. Allowed: rate-limited validation on specific ports. Forbidden: leaving the lab, DoS, credential attacks against real accounts. Scope lists the timeout, concurrency, and time window first.

example b · lab web
bash skills/scripts/case-init.sh --hint "isolated lab web security validation" --case-name lab-web-001 --preset own-system --target-url "http://10.10.10.20/" --network-profile lab_only
bash skills/scripts/case-guard.sh --case-root work/lab-web-001

C · read-only handoff review

Network: none, evidence untouched. Reviewing an existing case package without modifying the original evidence. Errors must be zeroed before delivery; warnings are explained in the handoff record.

example c · case review
python3 skills/case-review/scripts/review_case.py work/case-001 --format markdown
python3 skills/case-review/scripts/review_case.py work/case-001 --verify-hashes --strict
07

Automatic verification

You don't run these tests when using the package. The agent runs them automatically after any change to routing, scripts, or skills — and so does the CI pipeline on Windows and Ubuntu.

CheckWhat it verifiesOn failure, look at
test-routing163 hints map to the expected PRIMARYFailing case, priority, must / exclude keywords
verify-coherenceRoutes vs priority, skill paths, supply-chain pinsFirst BAD entry; never bypass the pin gate
smokeScript parsing + quick bilingual route samplesMissing files, PowerShell parse errors
extract-summariesINDEX.md matches skill frontmatterRegenerate, then diff the actual change
windows · full verification suite
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/test-routing.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/verify-routing-coherence.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/smoke.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/extract-summaries.ps1 -Check

Routing change rules

Change only skills/config/routing.json — never rewrite a hardcoded routing table in the scripts. Every new rule ships with regression cases.
08

Troubleshooting & FAQ

The most common questions, answered the way the project's own documentation answers them.

Still stuck?

Open an issue on GitHub with the failing step, the exact command output, and your platform — or reach out via the community channels on the landing page.
09

Finding status semantics

Findings move through four statuses on the path to the report. This table is the project's own definition of what each one means.

Deliverables checklist

  • Route result matches the task intent
  • Authorization evidence, assets, allowed and forbidden actions in scope
  • Case Guard returns OK — no --force used
  • Tool paths come from tool-index.md, not guesses
  • Evidence traces to findings and the final report
  • Sanitized lessons written back to field-journal