Cudaq Guide
NVIDIAOfficialCreated by CUDA-Q TeamDistributed by NVIDIA
- Skill
- Tool integration
- Software development
- Apache-2.0
- Medium risk
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
The CUDA-Q Guide provides comprehensive support for developers working with NVIDIA's CUDA-Q programming model. It covers the full lifecycle of quantum development, including environment setup for Python and C++, selection of simulation targets (GPU-accelerated or CPU-only), and integration with real QPU hardware. The skill also offers deep-dive assistance for authoring @cudaq.kernel code, including execution API selection, kernel-language constraints, and debugging common compilation or runtime issues.
What it does
- Walks users through CUDA-Q installation and validation on various platforms.
- Assists in selecting appropriate simulation backends, including multi-GPU and tensor-network targets.
- Provides best practices for authoring and debugging Python @cudaq.kernel code.
- Guides users through connecting to and executing jobs on real QPU hardware providers.
- Explains how to parallelize quantum workloads across GPUs or QPUs.
- Offers troubleshooting steps for common import, compilation, and execution errors.
When to use it
- When setting up a new CUDA-Q development environment on Linux, macOS, or WSL.
- When you need to write or debug a quantum kernel using the @cudaq.kernel decorator.
- When choosing between simulation backends like qpp-cpu or NVIDIA GPU-accelerated targets.
- When preparing to submit quantum circuits to external QPU hardware providers.
- When optimizing quantum workloads for multi-GPU or distributed execution.
Advantages
- Provides version-aware guidance for CUDA-Q 0.14 and 0.15 APIs.
- Centralizes documentation for both onboarding and advanced kernel authoring.
- Helps avoid common pitfalls like incorrect execution API selection or kernel-language violations.
- Streamlines the process of configuring provider-specific QPU access.
Usage examples
- “/cudaq-guide install”
- The agent provides step-by-step installation instructions for Python or C++, followed by a validation test using a Bell-state kernel.
- “/cudaq-guide author”
- The agent explains how to structure a kernel, select the correct execution API (e.g., sample vs. observe), and debug common compiler issues.
- “/cudaq-guide qpu”
- The agent initiates a dialogue to identify the target QPU technology and guides the user through secure credential configuration.
- “/cudaq-guide gpu-sim”
- The agent helps the user select the optimal simulation backend based on their hardware availability and performance requirements.
Install
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/nvidia/cudaq-guide/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip cudaq-guide.zip -d .agents/skills
Documentation by CUDA-Q Team
CUDA-Q Guide
Purpose
Guide users through CUDA-Q installation, basic kernels, GPU simulation targets,
QPU access, built-in applications, multi-GPU execution, and Python
@cudaq.kernel authoring. For Qiskit-to-CUDA-Q ports, route to the
cudaq-importing skill instead.
Prerequisites
Python 3.10+ for Python CUDA-Q workflows.
CUDA Toolkit and an NVIDIA GPU for GPU-accelerated targets on Linux.
CPU-only simulation is available through
qpp-cpu; macOS is CPU-only.C++ workflows require Linux or WSL and C++20.
QPU workflows require provider-specific credentials and accounts.
Instructions
Invoke with
/cudaq-guide [argument].If no argument is given, display the onboarding menu and ask which topic the user wants.
Use the routing table below to choose the relevant reference file.
Read local CUDA-Q documentation files when the answer depends on a specific CUDA-Q version or backend behavior.
Do not answer Qiskit porting questions from this skill; use
cudaq-importing.
Routing by Argument
| Argument | Action | Reference |
|---|---|---|
install | Walk through Python or C++ installation and validation. | references/onboarding.md |
test-program | Build and run a Bell-state kernel. | references/onboarding.md |
gpu-sim | Select GPU, multi-GPU, tensor-network, or CPU targets. | references/onboarding.md |
qpu | Guide provider selection and credential-safe QPU setup. | references/onboarding.md |
applications | Summarize CUDA-Q application areas and notebooks. | references/onboarding.md |
parallelize | Choose mgpu, mqpu, async dispatch, or distributed observe. | references/onboarding.md |
author | Author CUDA-Q Python kernels, select execution APIs, and debug compiler issues. | references/authoring.md |
| (none) | Print the menu below and ask which topic to explore. | This file |
Menu
CUDA-Q Getting Started
CUDA-Q is NVIDIA's unified quantum-classical programming model for CPUs, GPUs, and QPUs.
Supports Python and C++. Docs: https://nvidia.github.io/cuda-quantum/latest/
Choose a topic:
/cudaq-guide install Install CUDA-Q
/cudaq-guide test-program Write and run a Bell-state kernel
/cudaq-guide gpu-sim Accelerate simulation on NVIDIA GPUs
/cudaq-guide qpu Connect to real QPU hardware
/cudaq-guide applications Explore what you can build
/cudaq-guide parallelize Run across GPUs or QPUs
/cudaq-guide author Author @cudaq.kernel Python codeReference Files
references/onboarding.md: installation, test program, GPU targets, QPU providers, application areas, parallelization modes, examples, and platform troubleshooting.
references/authoring.md: execution APIs, kernel-language constraints, silent-failure pitfalls, recurring coding patterns, resource metrics, debugging, and validation.
Limitations
Guidance targets CUDA-Q Python/C++ workflows, with authoring details focused on decorator-mode Python APIs used in CUDA-Q 0.14 and 0.15.
GPU and multi-GPU support depends on local CUDA-Q, CUDA Toolkit, driver, MPI, and hardware availability.
QPU access and target options are provider-specific and may change; verify against local docs before giving operational steps.
Troubleshooting
Import error after
pip install cudaq: check Python 3.10+ and supported OS.No GPU detected: verify CUDA Toolkit and
nvidia-smi; fall back toqpp-cpu.Kernel compile error: read references/authoring.md and check the restricted kernel-language subset.
Version-specific behavior differs: compare
cudaq.__version__with the latest documentation, then review relevant documentation or source changes when debugging an installed version that is not the latest release.QPU submission fails: verify provider credentials are set as environment variables or through a secrets manager, never hardcoded.
Documentation lookup fails: retry transient MCP or repository lookup once, then fall back to local docs or official CUDA-Q documentation.
Files
- ATTRIBUTION.mdAdded by AutoGineer896 B
- BENCHMARK.md9.2 KiB
- LICENSELicence file added by AutoGineer11.2 KiB
- SKILL.md4.9 KiB
- evals/EVAL.md1.9 KiB
- evals/config.yml962 B
- evals/evals.json9.2 KiB
- references/authoring.md19.6 KiB
- references/onboarding.md8.0 KiB
- skill-card.md3.9 KiB
- skill.oms.sig5.4 KiB
BENCHMARK.md
Skill Benchmark: cudaq-guide
✅ Overall verdict: PASS — Recommended for publication
Publication Recommendation
Recommended for publication based on the completed evaluation evidence in this report.
Evaluation Metadata
Skill:
cudaq-guideEvaluation date: 2026-09-11
Evaluator version:
1.5.6Agents: Claude Code (
aws/anthropic/bedrock-claude-opus-4-8), Codex (openai/openai/gpt-5.5)Tasks: 13 evaluation tasks (10 positive, 3 negative)
Dataset digest:
sha256:7884d2878ed008a3969a7668a02fb2f9fda8e70495368a69ca8bf4ce1f6071dd(skill-evaluator-dataset-snapshot/1)Attempts per task: 3
Environment:
k8s-sandboxTier 2 evidence: required for publication
Tier 3 evidence: required for publication
Each task attempt ran in its own isolated sandbox pod.
What This Report Answers
The three-tier evaluation checks whether the skill:
is safe to use;
produces correct answers;
is discovered and activated when needed;
helps the agent complete the user's goal and expected workflow; and
avoids wasted skill and tool usage.
Results at a Glance
| Measure | Claude Code (Baseline → Skill Uplift) | Codex (Baseline → Skill Uplift) |
|---|---|---|
| Overall | 93.6% — baseline ran, but no comparable score was available; uplift unavailable | 89.2% — baseline ran, but no comparable score was available; uplift unavailable |
| Security | 100.0% → 100.0% (±0.0 points) | 85.7% → 92.3% (+6.6 points) |
| Correctness | 92.3% → 98.5% (+6.2 points) | 90.0% → 98.5% (+8.5 points) |
| Discoverability | 97.5% — baseline ran, but no comparable score was available; uplift unavailable | 92.0% — baseline ran, but no comparable score was available; uplift unavailable |
| Effectiveness | 69.2% → 79.9% (+10.7 points) | 66.0% → 86.1% (+20.1 points) |
| Efficiency | 91.9% — baseline ran, but no comparable score was available; uplift unavailable | 77.1% — baseline ran, but no comparable score was available; uplift unavailable |
How to read this table: baseline is the same task attempted without the target skill. Scores are rounded to one decimal; threshold-adjacent values use additional precision so their displayed band matches the verdict. Uplift is derived from those displayed scores and shown in percentage points.
Example: 47.0% → 92.0% (+45.0 points) means the skill-assisted run scored 92.0%, 45.0 percentage points above its 47.0% no-skill baseline.
A partial dimension was calculated from only the available configured signals; review the detailed report before relying on it.
Token Usage
Actual Tier 3 execution usage is reported for every observed agent/case pair and both conditions.
| Agent | Dataset case | With skill | Without skill | Delta | Change | Coverage |
|---|---|---|---|---|---|---|
| claude-code | All cases | 1,666,118 | 1,251,598 | +414,520 | +33.12% | skill 13/13; base 13/13 |
| claude-code | cudaq-guide-applications-001 | 96,575 | 30,095 | +66,480 | +220.90% | skill 1/1; base 1/1 |
| claude-code | cudaq-guide-author-adjoint-001 | 103,562 | 65,498 | +38,064 | +58.11% | skill 1/1; base 1/1 |
| claude-code | cudaq-guide-author-api-001 | 102,254 | 30,416 | +71,838 | +236.18% | skill 1/1; base 1/1 |
| claude-code | cudaq-guide-author-constraint-001 | 102,286 | 133,926 | -31,640 | -23.62% | skill 1/1; base 1/1 |
| claude-code | cudaq-guide-gpu-sim-001 | 96,542 | 31,244 | +65,298 | +208.99% | skill 1/1; base 1/1 |
| claude-code | cudaq-guide-install-001 | 96,783 | 31,099 | +65,684 | +211.21% | skill 1/1; base 1/1 |
| claude-code | cudaq-guide-neg-001 | 29,099 | 29,092 | +7 | +0.02% | skill 1/1; base 1/1 |
| claude-code | cudaq-guide-neg-002 | 29,417 | 29,600 | -183 | -0.62% | skill 1/1; base 1/1 |
| claude-code | cudaq-guide-neg-003 | 155,890 | 191,018 | -35,128 | -18.39% | skill 1/1; base 1/1 |
| claude-code | cudaq-guide-parallelize-001 | 96,696 | 31,451 | +65,245 | +207.45% | skill 1/1; base 1/1 |
| claude-code | cudaq-guide-qpu-001 | 171,868 | 162,627 | +9,241 | +5.68% | skill 1/1; base 1/1 |
| claude-code | cudaq-guide-route-qiskit-001 | 137,822 | 124,365 | +13,457 | +10.82% | skill 1/1; base 1/1 |
| claude-code | cudaq-guide-test-program-001 | 447,324 | 361,167 | +86,157 | +23.86% | skill 1/1; base 1/1 |
| codex | All cases | 1,861,622 | 1,290,210 | N/A | N/A | skill 13/13; base 14/14 |
| codex | cudaq-guide-applications-001 | 59,610 | 32,305 | +27,305 | +84.52% | skill 1/1; base 1/1 |
| codex | cudaq-guide-author-adjoint-001 | 64,364 | 94,709 | N/A | N/A | skill 1/1; base 2/2 |
| codex | cudaq-guide-author-api-001 | 45,999 | 24,417 | +21,582 | +88.39% | skill 1/1; base 1/1 |
| codex | cudaq-guide-author-constraint-001 | 46,233 | 44,952 | +1,281 | +2.85% | skill 1/1; base 1/1 |
| codex | cudaq-guide-gpu-sim-001 | 78,984 | 17,935 | +61,049 | +340.39% | skill 1/1; base 1/1 |
| codex | cudaq-guide-install-001 | 75,783 | 37,171 | +38,612 | +103.88% | skill 1/1; base 1/1 |
| codex | cudaq-guide-neg-001 | 13,272 | 13,234 | +38 | +0.29% | skill 1/1; base 1/1 |
| codex | cudaq-guide-neg-002 | 13,380 | 13,308 | +72 | +0.54% | skill 1/1; base 1/1 |
| codex | cudaq-guide-neg-003 | 532,599 | 598,297 | -65,698 | -10.98% | skill 1/1; base 1/1 |
| codex | cudaq-guide-parallelize-001 | 50,307 | 25,488 | +24,819 | +97.38% | skill 1/1; base 1/1 |
| codex | cudaq-guide-qpu-001 | 87,178 | 46,231 | +40,947 | +88.57% | skill 1/1; base 1/1 |
| codex | cudaq-guide-route-qiskit-001 | 46,712 | 44,623 | +2,089 | +4.68% | skill 1/1; base 1/1 |
| codex | cudaq-guide-test-program-001 | 747,201 | 297,540 | +449,661 | +151.13% | skill 1/1; base 1/1 |
| ALL AGENTS | Dataset aggregate | 3,527,740 | 2,541,808 | N/A | N/A | skill 26/26; base 27/27 |
Prompt tokens include cached reads, so total tokens are prompt + completion (cached is not added twice). The Efficiency score uses (prompt - cached) + completion. N/A means the relevant trajectory counters were not available; coverage is never estimated.
Tier Status
| Tier | Purpose | Status | Evidence |
|---|---|---|---|
| Tier 1 | Static validation | PASSED WITH OBSERVATIONS | 11 validator(s); 4 finding(s) |
| Tier 2 | Semantic deduplication | PASSED | 2 validator(s); 0 finding(s) |
| Tier 3 | Live agent evaluation | PASS | 2 agent(s); 13 task(s) |
Findings and Observations
<details> <summary>Show detailed findings and successful checks</summary>
MEDIUM SCHEMA/frontmatter_field_placement: Root field 'author' is ignored; use 'metadata.author' (
skills/cudaq-guide/SKILL.md)MEDIUM SCHEMA/frontmatter_field_placement: Root field 'tags' is ignored; use 'metadata.tags' (
skills/cudaq-guide/SKILL.md)MEDIUM SCHEMA/frontmatter_field_placement: Root field 'version' is ignored; use 'metadata.version' (
skills/cudaq-guide/SKILL.md)MEDIUM SCHEMA/body_recommended_section: Missing recommended section: '## Examples' (
skills/cudaq-guide/SKILL.md)
</details>
Scoring Methodology
<details> <summary>Show dimension definitions, source signals, and thresholds</summary>
| Dimension | Question | Scored signals |
|---|---|---|
| Security | Is it safe to use? | security (100%) |
| Correctness | Is the answer correct? | accuracy (100%) |
| Discoverability | Was the right skill loaded when needed? | skill_execution (100%) |
| Effectiveness | Did the skill help complete the task? | goal_accuracy (50%) + behavior_check (50%) |
| Efficiency | Did it avoid wasted tool calls and token usage? | skill_efficiency (50%) + token_efficiency (50%) |
Dimension bands: PASS at 50% or above; NEUTRAL from 40% to below 50%; FAIL below 40%.
Overall Tier 3 lift: PASS at +5 points or more; FAIL at -10 points or less; values between those bands are NEUTRAL.
Overall verdict: PASS only when every configured dimension passes for at least one supported agent. Lift is reported as diagnostic evidence and does not override this gate.
The 50% attempt pass threshold is a separate per-task gate; it is not the dimension pass threshold.
Effectiveness is the equal-weight mean of goal completion (
goal_accuracy) and expected workflow adherence (behavior_check).Efficiency is 50% tool-call productivity (the backward-compatible
skill_efficiencywire id) and 50%token_efficiency. Positive-case skill routing is scored under Discoverability, not Efficiency; a negative case without a routing target is N/A. N/A sources are omitted, remaining weights are renormalized, and the dimension is marked partial.
Signals present in this run:
security(Security): unsafe operations, secret leakage, and unauthorized access.skill_execution(Skill Execution): whether the expected skill was selected, decoys were avoided, and the workflow executed.skill_efficiency(Tool Productivity): tool-call productivity (legacy wire id; routing is scored under Discoverability).accuracy(Accuracy): final-answer correctness against the reference answer.goal_accuracy(Goal Accuracy): whether the user's goal was achieved.behavior_check(Behavior Check): whether the expected workflow behavior was followed.token_efficiency(Token Efficiency): actual uncached prompt plus completion usage (50% of Efficiency).
</details>
Freshness
Regenerate this benchmark when the skill, evaluation dataset, target agent/model, evaluator version, environment, or scoring policy changes.
Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Needs: Needs Python
The author says: Python 3.10+, C++ 20
Security
What our scanner noticed· Medium risk
- Large base64-encoded blobs
- Instructions that use the network
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Created by
- CUDA-Q Team
- Publisher
- NVIDIA (Official)
- Distributed by
- NVIDIA
- Source
- NVIDIA/skills · skills/cudaq-guide · commit fce3cca
- Licence
- Apache License 2.0 (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE-APACHE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by CUDA-Q Team or NVIDIA.
Related skills
Implement
Matt Pocock· Community
A structured workflow for implementing software tasks from specifications or tickets.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository317.5k
Source Driven Development
Addy Osmani· Community
A rigorous process for grounding code implementation in official, version-specific documentation to ensure accuracy and avoid outdated patterns.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository113.9k
Write Swift
Emil Kowalski· Community
A comprehensive guide to writing modern, safe, and performant Swift code following the language's latest idioms and concurrency models.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository54.3k
Cardputer Buddy
AnthropicOfficial
Iterate on the Cardputer-Adv MicroPython app bundle (Claude Buddy, Snake, Hello) after the device is already provisioned via m5-onboard. Use when the user wants to add a new app, push a single changed .py without re-flashing, watch device serial logs, or run a one-shot REPL command. Trigger on "add an app", "push to the cardputer", "tail the device", "run on the device", or follow-up work after /maker-setup.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreApache-2.0GitHub stars of the source repository46.3k
Typescript Pro
Seth Hobson· Community
An expert TypeScript persona focused on advanced typing, enterprise architecture, and strict type safety.
Software developmentClaude CodeMITGitHub stars of the source repository42.3k
Scala Pro
Seth Hobson· Community
An expert Scala engineer persona specializing in functional programming, distributed systems, and enterprise-grade architecture.
Software developmentClaude CodeMITGitHub stars of the source repository42.3k
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download cudaq-guide.zip