Guide · Agent skill

How to use the Qiskit Quantum ML Reference agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The quantum-qiskit skill is a reference file that teaches an AI agent how to write Python code with IBM's Qiskit libraries, using the 2.x API. It covers data-encoding feature maps, variational quantum classifier (VQC) training, variational quantum eigensolver (VQE) chemistry code, matrix-product-state circuits and noise model integration. After reading this guide you will know what the skill does, how to install it, how to ask for it in plain language and what to check before trusting the code it produces.

Qiskit Quantum ML Referenceaiming-lab/AutoResearchClaw · MIT Download the skill

Quick start

1Download the ZIP. Get the quantum-qiskit ZIP from the page you are reading.
2Unzip the skill folder. Extract it into ~/.claude/skills/ for all projects, or into .claude/skills/ inside one project.
3Or upload it in the Claude apps. Go to Settings → Capabilities → Skills and upload the ZIP if you use the apps.
4Install the Python packages. Make sure Python, qiskit 2.x, qiskit_aer, qiskit_algorithms and qiskit_machine_learning are available, plus qiskit_nature and PySCF for chemistry.
5Ask in plain language. Describe the quantum ML task and name the Qiskit package or keyword, such as VQC or feature map.
6Review and test the output. Read the generated code, run it in your own environment and check the results, since the source says it is not verified against a live install.

What is an agent skill and what does this one do?

An agent skill is a folder with a SKILL.md file that an AI agent reads to learn a specific task. This skill is a coding aid for quantum machine learning in Python. Once it is loaded, the agent knows the correct function names, data-encoding circuits, VQC training calls and chemistry simulation patterns for current Qiskit 2.x, and it is less likely to use names from older Qiskit versions.

The skill does not run quantum computations or start a service. It only shapes the code the agent writes.

Feature maps for encoding data into circuits, including angle, amplitude and ZZ encodings
Ansatz construction with EfficientSU2 and a parameter count you can check
VQC training with qiskit_machine_learning and its fit and predict methods
A VQE pattern for the H2 molecule built with PySCF and qiskit_nature
Notes on migration errors and common mistakes with fixes

How do you install the quantum-qiskit skill?

Download the ZIP for the skill from the page you are reading. Unzip it so that the skill folder, which contains SKILL.md, sits in one of two places. For a skill available in all your projects, use ~/.claude/skills/. For a skill available in one project only, use the .claude/skills/ folder inside that project.

If you use the Claude apps instead, you can upload the ZIP under Settings → Capabilities → Skills.

Personal install: ~/.claude/skills/
Project install: .claude/skills/ inside your project folder
Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Which Python packages does the skill expect?

The skill itself only contains guidance, but the code it writes imports several Python packages. You need Python and Qiskit 2.x, plus qiskit_aer, qiskit_algorithms, qiskit_machine_learning and qiskit_nature. The chemistry examples also need PySCF for the H2 driver. The skill's own examples use these imports, so the agent will expect them to be installed.

The skill file does not give install commands for these packages, so check the official Qiskit documentation for how to install them in your environment.

Python
qiskit 2.x
qiskit_aer
qiskit_algorithms
qiskit_machine_learning
qiskit_nature (chemistry examples only)
PySCF (H2 chemistry driver)

from qiskit import QuantumCircuit
from qiskit.circuit.library import ZFeatureMap, ZZFeatureMap, StatePreparation, EfficientSU2
from qiskit.primitives import StatevectorSampler, StatevectorEstimator
from qiskit_aer import AerSimulator
from qiskit_algorithms.optimizers import COBYLA
from qiskit_machine_learning.algorithms.classifiers import VQC

How do you trigger the skill with natural requests?

You do not need a special command. The skill is meant to load when you ask the agent to write Python code that uses the qiskit, qiskit_aer, qiskit_algorithms, qiskit_machine_learning or qiskit_nature packages. Mention the task in plain words, and name the package if you can.

The skill's metadata lists trigger keywords such as vqc, vqe, feature map, ansatz, aer, quantum classifier, mps, noise model and quantum kernel. Using these words in your request makes it more likely that the agent picks the skill up.

Write a VQC in qiskit 2.x that classifies my two-feature dataset with a ZZ feature map.
Port my old VQE script to the qiskit 2.x API and explain each change.
Add an angle encoding and a hardware-efficient ansatz to this qiskit_machine_learning pipeline.
Build a noisy AerSimulator run for this circuit using a noise model.

What does the skill's code look like?

The skill provides small builder functions. The encoder helper below returns a Hadamard and Z-rotation circuit per feature, which the source says is equivalent to ZFeatureMap with one repetition. The VQC helper passes a feature map, an ansatz, cross-entropy loss, COBYLA and a seeded StatevectorSampler to VQC, then calls fit.

The source also warns against writing your own optimization loop around the Sampler when VQC.fit already handles this. It lists the VQC keyword arguments that work, and any other name raises TypeError.

Supported VQC arguments: feature_map, ansatz, loss, optimizer, sampler, initial_point, callback, warm_start
Use VQC.fit(X, y) and VQC.predict(X)
Do not import qiskit_algorithms.VQE or qiskit_nature.second_q.algorithms under qiskit 2.x, since the source says they fail at import time
Check that two encoders give different states for the same input when you build several in a loop

def build_angle_encoding(num_features: int) -> QuantumCircuit:
    return ZFeatureMap(feature_dimension=num_features, reps=1)

def train_vqc(feature_map, ansatz, X_train, y_train, seed: int, maxiter: int = 200):
    algorithm_globals.random_seed = seed
    vqc = VQC(feature_map=feature_map, ansatz=ansatz, loss='cross_entropy', optimizer=COBYLA(maxiter=maxiter), sampler=StatevectorSampler(seed=seed))
    vqc.fit(X_train, y_train)
    return vqc

What are the safety notes and limits?

The skill runs no scripts and makes no network calls. It is a set of written patterns, so any risk comes from the Python code the agent writes and you run. Read that code before you execute it.

The source says the code patterns are not verified against a live Qiskit install inside the file itself. Treat the output as a draft. Also note that the skill covers only Qiskit, not other frameworks such as Cirq or PennyLane. The section on VQE is cut off in the source text, so check the final chemistry code against the official documentation.

Runs scripts: no
Uses network: no
Code is not verified against a live install, so test it
Covers Qiskit only

What people use it for

Building a variational quantum classifier on a small tabular dataset with a chosen feature map.
Porting an older Qiskit 1.x VQE or VQC script to the Qiskit 2.x API.
Learning how feature maps and ansatz circuits are structured by asking for annotated examples.
Adding a noise model to an AerSimulator run to see how results change.
Setting up an H2 chemistry Hamiltonian with PySCF and qiskit_nature as a starting point for VQE.

Frequently asked questions

Is the quantum-qiskit skill free to use?

The skill is listed under the MIT licence, which the item information states. The source does not mention pricing, so check the licence file in the original repository for the full terms.

What do I need to use the quantum-qiskit skill?

You need Python and the Qiskit 2.x packages the code imports, including qiskit_aer, qiskit_algorithms, qiskit_machine_learning and qiskit_nature. PySCF is needed for the H2 chemistry driver. The skill runs no scripts and makes no network calls.

Where do I put the quantum-qiskit skill folder?

Put the unzipped folder, which contains SKILL.md, in ~/.claude/skills/ to use it everywhere, or in .claude/skills/ inside a project to use it in that project only. In the Claude apps you can upload the ZIP under Settings → Capabilities → Skills.

Why does my VQE code fail to import under Qiskit 2.x?

The skill says that qiskit_algorithms.VQE and the qiskit_nature.second_q.algorithms submodule fail at import time under Qiskit 2.x. The guidance is to build the Hamiltonian with PySCF and qiskit_nature, then run a manual optimization loop over a StatevectorEstimator.

Can the skill replace a quantum computer or run my experiments?

No. The skill is a reference for writing code and does not run quantum computations or a service. You still need to execute the generated Python yourself.

Does this skill cover Cirq or PennyLane?

No. The skill covers only Qiskit and its ecosystem packages. For Cirq or PennyLane, you need a different skill or the documentation for those frameworks.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits researchers, developers and students who write quantum machine learning code in Python with Qiskit and want an agent that uses current 2.x function names and avoids older migration errors. It is a poor fit for anyone who wants to run quantum jobs without writing code, or who needs Cirq or PennyLane support. Review and test any code it produces before using it in production.

Download the skill