apk-reverse: an Agent Skill for Android APK patching, not a tutorial

The problem apk-reverse targets: an agent that agrees and then improvises

Most APK reverse engineering material is written for a human who reads it once and then works. apk-reverse is written for a model that reads it while working, and the README names the failure mode it is built around directly: the model reads the whole thing, agrees with it, and then reasons from first principles anyway. That is a different problem from ignorance, and it explains the shape of the repository. SKILL.md is described as a procedure with gates rather than advice. The body is meant to be acted on, not read.

Who it is for follows from that. The README frames the skill around decisions that are expensive to get wrong: whether a request is achievable client-side at all, what form the deliverable must take, which patch layer is safest, and whether a failure belongs to your patch, the app, or the server. The stated audience is an agent harness (Claude Code, Codex, or anything supporting the Agent Skills format), not a person looking for a walkthrough. If you want to learn APK internals from scratch, this is the wrong document.

Four override rules, a symptom index, and four gates: the actual mechanism

The architecture is progressive disclosure. A short decision-oriented SKILL.md sits at the top; detailed references load only when a step needs them; parameterized scripts run directly. Four mechanisms inside the body are described as things to act on.

R1 through R4 are override rules. Where they conflict with the agent's current plan, the README states they win until evidence overrides them. The symptom index is a table where each row is a failure that has already been paid for, and a matching row is a stop signal: load that file before running another command, not after a few more attempts. G1 through G4 are gates, each an action with a pass criterion, and the README is explicit that understanding the idea does not clear a gate. Classification, environment truth and a control build happen before the first patch.

Two more rules bound the loop. A two-strike rule says two failures of the same shape mean the model is wrong, not the parameters. And done has a six-item definition, of which a clean log is not one. Anything short of all six is a checkpoint and should be reported as one.

Installing apk-reverse and running the first command

The README does not give a pip install line or a package name, because this is a skill directory consumed by a harness rather than a library. The repository layout places the skill under skills/, with scripts beneath it. The README states that the cheapest possible first command for an agent is the doctor script, which reports which tools exist, which scripts can actually run, and whether something in the environment is already poisoning measurements.

python skills/apk-reverse/scripts/doctor.py

Run it before anything else and read the output as an inventory, not a formality. If the tools the skill expects are missing, the later gates cannot pass, and the README's position is that finding this out after the third failed patch is the expensive path.

The repository also carries its own checks, which are visible in the top-level entries: check_commands.py, check_refs.py, check_repo.py, check_routing.py, check_budget.py and build_scripts.py, alongside pytest.ini, mypy.ini and .flake8. Those are repository self-checks rather than user-facing installation steps, and the README does not document a supported way to run them as a consumer. Treat them as evidence that the skill's own references and routing are validated in CI, not as a setup procedure.

What the skill is built to catch, and where it stops

The capability list is unusually specific, and the specificity is the useful part. The README describes catching a repack failure that looks like success: an app that installs, launches and renders perfectly while every signed request is rejected, because the client derives its request-signing key from its own signing certificate. It describes separating a client-side sign-in gate, which is patchable, from an account-scoped resource that is empty because the server has nothing to answer with, and it states that forging a session produces a state worse than being signed out.

It also covers packed and hardened targets, including a hardened library that terminates the process on purpose, with a deliberate-crash shape the README writes as fault addr 0x4 that resembles an ordinary null dereference. The rule attached to that case is that you neutralise it but never by making it not return, because the fix then freezes the app in a way that looks nothing like the cause.

The boundary is stated as plainly. A repack refused by several independent checks is described as blocked, not expensive, and the fallback ladder is a system-level module, a local RPC service, or an honest report with a stated boundary. The README also notes that some tools exist only as a GUI, and the instruction in that case is to ask for a human rather than silently substitute a weaker method. That is an admission of incompleteness, and a reasonable one.

Where apk-reverse is the wrong tool

The README does not document rollback, and it does not document a standalone command-line interface for patching an APK. There is no release history in the repository metadata, so there is no upgrade path to reason about either. If your workflow is a person sitting at a terminal decompiling one APK, this repository gives you references and scripts but no application to drive them.

The harder limitation is the dependency on the harness. The whole design assumes an agent that loads SKILL.md and obeys gates, override rules and stop conditions. An agent that ignores them gets the same behaviour the README complains about, and nothing in the skill can force compliance. The two-strike rule and the six-item definition of done are conventions the model has to honour.

A second boundary is server-side enforcement. The README positions the skill as good at deciding fast whether a request is achievable client-side, which implies that when it is not, the answer is a boundary report rather than a patch. Anyone expecting the skill to defeat server-enforced paywalls has misread its scope.

apk-reverse compared with Apktool and other APK reverse engineering tools

The obvious comparison is Apktool, which appears repeatedly in what people search for alongside this project. The difference is in what each one is. Apktool is a tool: you give it an APK, it decodes resources and smali, and you edit and rebuild. apk-reverse is a skill: it contains no decoder of its own, and the README's own first command is a doctor script that checks which tools already exist on the machine. In practice the skill sits above tools like Apktool and decides when and how to use them, including where each one lies.

That is a real division of labour and also a real dependency. Apktool works with nothing but a JVM. apk-reverse works only if an agent harness loads it and the underlying tools are present. If you want a single binary that turns an APK into readable output, Apktool is the shorter path. If you want a procedure that stops an agent from burning hours on a server-enforced paywall, apk-reverse is aimed at that and Apktool has no opinion about it.

Maintenance, licence and what an upgrade would cost

The repository is not archived, and the last push was on 2026-09-24, four days before this article. That is recent enough to describe the project as maintained on the strength of that push alone, and no further claim is supported. There are no releases in the repository metadata, so there is no versioned upgrade path, no changelog to read before pulling, and no pinned version to depend on. Consumers track the main branch.

That matters more than usual here, because the skill's value is in its content: the symptom index, the gates and the override rules. Those change when someone pays for a new failure and writes it down. A pull can therefore change agent behaviour without any API change, and there is no semver signal to warn you. Reading the diff before updating is the only control the repository offers.

The licence is MIT, which permits use, modification and redistribution with the licence and copyright notice retained. The README carries a disclaimer section, and given that the subject matter is patching and repacking applications, the licence grants rights over the code and documentation, not over anyone else's APK. Nothing here is legal advice; if you are repacking a third-party application, the licence of this skill is not the question you need answered.

Editorial conclusion

Adopt apk-reverse if you already run an agent harness that supports the Agent Skills format and you want its procedure, symptom index and gates to constrain that agent during APK patching work. Do not adopt it if you want a standalone decompiler or a point-and-click tool; the README describes a skill, not an application, and it assumes the surrounding tools already exist on the machine. Before trusting it, run python skills/apk-reverse/scripts/doctor.py and read its output, because the README states that script reports which tools exist and whether something in the environment is already poisoning your measurements.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. newliver666/apk-reverse on GitHub
4. README