Skills

ghidra-headless

Installation
SKILL.md

Ghidra Headless

Use this umbrella skill when you need to choose the right standalone phase-specific contract before planning headless Ghidra work with speckit, when you need the explicit auto-evolution child skill after real task work uncovers a reusable improvement, or when you need one place that explains the collaboration loop across the full skill family.

This file is the entrypoint and routing guide. It is no longer the only normative collaboration surface. The phase-specific planning-brief.md files below are the canonical contract artifacts that downstream teams hand to speckit and reuse for audit. No downstream speckit extension or downstream constitution edit is required to use those files.

Phase Skill Family

Phase skill Use it when Canonical contract Primary example
ghidra-headless-intake You are shaping target intake, project initialization, scope, and planning inputs before deeper analysis starts. ../ghidra-headless-intake/planning-brief.md ../ghidra-headless-intake/examples/intake-speckit-handoff.md
ghidra-headless-evidence You are defining evidence extraction, replay expectations, and review surfaces for generated artifacts. ../ghidra-headless-evidence/planning-brief.md ../ghidra-headless-evidence/examples/evidence-speckit-handoff.md
ghidra-headless-script-review You are planning reusable headless script authoring, script review, registration, and post-planning violation handling. ../ghidra-headless-script-review/planning-brief.md ../ghidra-headless-script-review/examples/script-authoring-review-audit.md
ghidra-headless-auto-evolution You are reviewing a completed real task to extract reusable workflow or script improvements, classify them, and promote tracked assets when justified. ../ghidra-headless-auto-evolution/SKILL.md ../ghidra-headless-auto-evolution/examples/direct-promotion-example.md

Explicit Follow-On Skill

Use the auto-evolution child skill after a real task is complete and you need to decide whether an observed script, workflow step, or documentation pattern should become a supported tracked asset.

Child skill Use it when Primary contract surface Worked examples
ghidra-headless-auto-evolution You are reviewing completed real-task artifacts to extract reusable improvements, resolve overlap, and decide whether one task provides enough evidence for a direct tracked-asset change. ../ghidra-headless-auto-evolution/SKILL.md and ../ghidra-headless-auto-evolution/templates/auto-evolution-review-record.md ../ghidra-headless-auto-evolution/examples/direct-promotion-example.md and ../ghidra-headless-auto-evolution/examples/deferred-candidate-example.md

What Stays Non-Negotiable

Every phase skill preserves the same reverse-engineering baseline:

  • Headless-only Ghidra workflows. GUI actions stay out of scope.
  • Evidence-backed claims. Planning artifacts must point back to observable evidence, not intuition alone.
  • Reproducible workflows. Commands, inputs, and replay expectations must remain explicit.
  • Reviewable Markdown outputs. spec.md, plan.md, tasks.md, and audit findings must stay inspectable without hidden setup.

These constraints travel with the phase skill even when a downstream repository has its own constitution, templates, or conventions. Downstream speckit extensions and downstream constitution edits are not required to use this skill family.

Fixed Contract Surface

Each phase skill owns a fixed-name planning-brief.md at the root of its skill directory. That file is the portable contract surface for both:

  • handing the phase constraints into speckit
  • auditing generated spec.md, plan.md, and tasks.md

The umbrella skill explains how to choose among those files, but it does not replace them as the normative per-phase contract surface.

Allowed transport modes:

  • provide the planning-brief.md artifact directly
  • paste the contents inline into the speckit request

Changing the transport mode must not change or weaken the contract.

Collaboration Sequence

Use this sequence every time:

  1. Pick the phase skill that matches the current reverse-engineering stage.
  2. Prepare the phase skill's planning-brief.md with the required inputs and local context.
  3. Run speckit using the brief file or an inline paste of the same content.
  4. Re-open the same phase skill and apply its audit checklist to generated spec.md, plan.md, and tasks.md.
  5. If any blocking contract item is missing, refine or regenerate the planning artifacts. Do not weaken the phase contract.

Recommended routing:

  • Start with intake when the request is still being scoped or the target is not yet normalized.
  • Use evidence after intake when planning needs explicit replay, artifact, or validation expectations.
  • Use script authoring and review when the plan includes reusable headless scripts, registration, or checklist-governed review of script changes.
  • Use auto evolution after a real task completes and exposes a reusable improvement that should be reviewed explicitly instead of being left as an undocumented maintainer habit.

Auto-Evolution Routing

Use the auto-evolution child skill only after a real task or artifact set already exists. It is not a replacement for intake, evidence planning, or script-authoring review.

Route to ../ghidra-headless-auto-evolution/SKILL.md when all of the following are true:

  • a completed task exposed a potentially reusable workflow step, script, template pattern, or child-skill idea
  • the candidate can be tied back to concrete repository or workspace artifacts
  • you need an explicit decision on accepted, deferred, or rejected
  • you need to decide whether the candidate updates an existing asset or creates a new tracked path

Support surfaces for that route:

Do not use auto evolution to:

  • brainstorm reusable ideas before any real task evidence exists
  • bypass the runtime-output boundary under .work/
  • create duplicate tracked assets without overlap resolution

Source Comparison Entry Points

When the workflow reaches Stage 4 Source Comparison, use these tracked surfaces together:

Source-comparison routing rules:

  • upstream-reference.md is the always-present intake artifact.
  • reference_status is the canonical source-comparison trust signal.
  • third-party-diff.md begins only after the upstream reference is reviewable as accepted or qualified.
  • Fallback local references under .work/upstream-sources/<project-slug>/ default downstream source-derived use to qualified.
  • Deferred or stale source comparison must not be treated as a completed formal diff or an allowed source-derived baseline.

Reusable Script Support Boundary

The repository treats reusable scripts through three review states:

State Meaning Support Posture
Supported reusable script Clear purpose, replayable inputs, reviewable outputs or mutation notes, registration surfaces, and evidence. Part of the documented workflow.
Sample-specific helper Useful local helper that still depends on one narrow sample, one hardcoded scope, or missing review surfaces. Do not present as a supported workflow asset.
Unsupported candidate Concept or implementation that is still missing category fit, replayability, or runtime-policy compliance. Keep out of the supported workflow until the contract is satisfied.

The tracked support inventory lives in:

Those artifacts define the support boundary. Nearby candidate implementations do not become supported only because they exist in the worktree.

Auto-Evolution Guardrails

The auto-evolution child skill extends this support boundary rather than replacing it.

  • Real-task artifacts come first. Auto evolution reviews completed work that already exists in the repository or workspace.
  • One-task promotion is allowed only when the review record includes task context, reusable-part summary, benefit statement, and explicit non-sample-specific reasoning.
  • Overlap must be resolved before a new tracked asset path is created.
  • Runtime-only helpers, generated reports, and local scratch outputs stay under .work/ even when a related tracked asset is promoted.
  • Direct promotion may update this umbrella skill or create a new child-skill entry only when the resulting tracked paths are named explicitly in the review record.

Supported Reusable Script Categories

Category Typical Role Default Side-Effect Class Primary Registration Surfaces
analysis_export Export reviewable evidence from headless analysis. export_only SKILL.md, walkthrough, evidence records
verification_audit Check whether a reviewable claim or exported result still holds. read_only review checklist, evidence records
metadata_updating Apply justified names, types, or related analysis metadata. metadata_updating authoring guide, review checklist, mutation notes
orchestration_wrapper Discover tools, coordinate replay stages, and route explicit inputs and outputs. mixed_wrapper SKILL.md, walkthrough, command manifest

Registration Surface Expectations

A reusable script is only supported when all three surfaces exist:

  • Invocation guidance: where the script is discovered or called in the workflow
  • Review guidance: what a reviewer checks before support is claimed
  • Evidence guidance: which artifact records acceptance, downgrade, or failure

For this repository, the primary surfaces are:

Runtime Output Boundary

Treat the skill package as read-only during live runs:

  • .agents/skills/ is a tracked package surface.
  • .work/ghidra-projects/<target-id>/ is the disposable project root.
  • .work/ghidra-artifacts/<target-id>/ is the default writable runtime artifact root.
  • .work/ghidra-user-home/ is the default redirected local Ghidra user-home for logs, preferences, and bundle cache during headless runs.
  • Generated local helper scripts belong under a workspace path such as .work/ghidra-artifacts/<target-id>/generated-scripts/, not under .agents/skills/.
  • Files under examples/artifacts/ are reviewed sample surfaces, not default runtime destinations.

If a workflow attempts to write runtime-generated content under .agents/skills/, call it out as invalid and treat the related candidate as unsupported until the path contract is corrected.

Local Rule Policy

Local repository rules may:

  • add stricter review requirements
  • require extra planning metadata
  • tighten validation or naming conventions

Local repository rules may not:

  • relax headless-only expectations
  • remove evidence requirements
  • replace reproducibility obligations with informal notes
  • convert reviewable Markdown outputs into hidden or ad hoc outputs

Treat stricter local rules as additive overlays. Treat any attempt to soften the phase contract as an invalid weakening that must be called out during audit.

Outside-In Selection Terms

Use the following terms consistently across the workflow, sample artifacts, and generated review surfaces:

  • verified boundary: a reconstruction boundary whose compare result is explicitly recorded as matched
  • frontier-eligible: a function that is allowed to be considered now because it is either an outermost anchor or a child of the current matched boundary
  • entry-adjacent: directly anchored by the program entrypoint, a top-level imported call path, or another outermost boundary clue
  • dispatcher-like: a function whose reviewed role is to route, fan out, or hand off execution to downstream callees or dispatch edges
  • secondary metrics: visible counts or size-style clues such as incoming references, call counts, or body size that provide context but do not authorize progression on their own

Outside-In Selection Rules

When working through Stage 2 evidence review, Stage 3 target selection, and Stage 6 compare-gated decompilation:

  1. Start with one outermost evidence-backed function.
  2. Do not move to a deeper child until the current boundary is recorded as matched.
  3. Choose one automatic default target for the current frontier rather than leaving an unordered candidate list.
  4. Apply this precedence order when multiple rows are frontier-eligible: entry-adjacent dispatcher/helper/wrapper/thunk boundary, other entry-adjacent frontier row, helper-style child of a matched boundary, then other child of a matched boundary, with stable address order as the final tie-break.
  5. Treat wrappers, thunks, and dispatch helpers as legitimate frontier boundaries that outrank a deeper substantive body on the same frontier tier.
  6. Record frontier_reason, selection_reason, question_to_answer, and the applied tie-break rationale for every automatic default target.
  7. Record both deviation_reason and deviation_risk only when the reviewed workflow intentionally breaks the default frontier order.
  8. Keep visible metric fields explicitly secondary on evidence and target-selection surfaces.
  9. Treat blocked, unresolved, diverged, and deviation_only compare states as unable to authorize deeper selection.

Current Runtime Workflow Reference

When the work moves from planning into actual reverse engineering, the umbrella skill still points to the repository's headless workflow assets:

Those runtime assets remain useful after planning, but they do not replace the phase-specific contract files for speckit collaboration or the feature-level support catalog and runtime-output policy.

The active Java-only reusable-script family now includes:

  • ExportAnalysisArtifacts.java for baseline evidence export and selected decompilation output
  • ReviewEvidenceCandidates.java for Stage 2 evidence candidate export
  • PlanTargetSelection.java for Stage 3 target-selection export
  • ApplyRenames.java for manifest-driven function, symbol, and label rename application
  • VerifyRenames.java for manifest-driven function, symbol, and label rename verification
  • ApplyFunctionSignatures.java for manifest-driven function signature application
  • VerifyFunctionSignatures.java for manifest-driven function signature verification
  • LintReviewArtifacts.java for manifest lint with reviewable failure output

Retired or compatibility implementations do not remain part of the active supported surface once the Java workflow is registered. Support and validation claims should point at the Java scripts and their command surfaces only.

When the reviewed input is an ar archive, the supported order is:

  1. run normalize-ar-archive.sh
  2. inspect the archive intake, member inventory, handoff, and replay surfaces
  3. continue into run-headless-analysis.sh only for accepted extracted member paths

Do not treat the raw archive itself as the downstream program identity. For the feature-specific reviewer flow, use the archive-normalization gate in ./examples/analysis-selection-playbook.md and the wrapper expectations in ./examples/ghidra-script-authoring.md.

The current supported rename-manifest schema remains aligned to the active Java scripts:

  • executable rows may use Item Kind = function, symbol, or label
  • the latest recorded local replay explicitly validated executable function and symbol rows end to end
  • any future schema expansion must update the docs, samples, and validation record in the same review set

All of these scripts remain subject to the same headless-only, evidence-backed, reproducible, and reviewable-output baselines, and all runtime reports stay under .work/ghidra-artifacts/ rather than inside .agents/skills/.

Related skills

More from bytelandtechnology/ghidra-headless

Installs
5
Repository
bytelandtechnol…headless
First Seen
Apr 1, 2026