Transpiler

---
name: transpiler
description: "Guides agents compiling circuits with transpile, Target,
  CouplingMap, Layout, PassManager, preset pass managers, and backend-specific
  pass routing."
disable-model-invocation: true
metadata:
  disco-role: operating
license: Apache 2.0
---

# Qiskit transpiler workflows

Use this sub-skill when the task is about compiling a circuit to a backend target or hardware topology with `qiskit.transpiler` or `qiskit.compiler.transpile`.

## Read next

- `references/workflows.md` for preset pass managers, targets, routing, and backend-driven recipes.
- `references/troubleshooting.md` for `TranspilerError`, basis-gate mismatches, layout/routing surprises, and missing optional pass dependencies.
- `../../references/module-map.md` for the package-level module map.
- `../../scripts/check_qiskit_environment.py --sections transpiler providers` for a source-free backend-transpile smoke check.

## Include here

- `transpile()` and `generate_preset_pass_manager()`.
- `Target`, `CouplingMap`, `Layout`, `PassManager`, `StagedPassManager`, `PropertySet`, and pass-plugin routing.
- Layout, routing, translation, optimization, scheduling, and seed/optimization-level selection.
- Hardware-driven compilation from a backend or fake backend.
- Basic control of backend-specific defaults, backend targets, and stage-method overrides.

## Exclude or route elsewhere

- Building the abstract circuit itself belongs in `../circuit/SKILL.md`.
- Sampler/estimator jobs and result access belong in `../primitives/SKILL.md`.
- Serialization to QASM/QPY belongs in `../serialization/SKILL.md`.
- State/operator analysis belongs in `../quantum-info/SKILL.md`.
- Visualization of the compiled output belongs in `../visualization/SKILL.md`.

## Default route

If the user mentions basis gates, coupling maps, backend targets, routing, or preset optimization levels, start here even if the input circuit was already valid. This sub-skill is also the right place to interpret a fake backend or `Target` object used as transpilation input.

## What to remember

- `target` takes precedence over loose backend constraints, and explicit loose constraints take precedence over backend defaults.
- `optimization_level` changes the preset stage mix; `0` is minimal runnable compilation and `3` is the most aggressive preset.
- Seed stochastic stages when the user wants reproducible output.
- Optional pass dependencies are part of the workflow surface. Check them before suggesting a pass that depends on `z3-solver`, `python-constraint`, or similar extras.