AutoGineer
Generated banner for Cudaq Guide
Generated logo for Cudaq Guide

Cudaq Guide

NVIDIAOfficialCreated by CUDA-Q TeamDistributed by NVIDIA

  • Skill
  • Tool integration
  • Software development
  • Apache-2.0
  • Medium risk
Download ZIP

From the author

Use for CUDA-Q setup, simulation targets, QPU access, and @cudaq.kernel authoring guidance.
— the description by CUDA-Q Team

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

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/nvidia/cudaq-guide/download

  2. Unzip 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

ArgumentActionReference
installWalk through Python or C++ installation and validation.references/onboarding.md
test-programBuild and run a Bell-state kernel.references/onboarding.md
gpu-simSelect GPU, multi-GPU, tensor-network, or CPU targets.references/onboarding.md
qpuGuide provider selection and credential-safe QPU setup.references/onboarding.md
applicationsSummarize CUDA-Q application areas and notebooks.references/onboarding.md
parallelizeChoose mgpu, mqpu, async dispatch, or distributed observe.references/onboarding.md
authorAuthor 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 code

Reference 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 to qpp-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

skill.oms.sig

{"mediaType":"application/vnd.dev.sigstore.bundle.v0.3+json","verificationMaterial":{"x509CertificateChain":{"certificates":[{"rawBytes":"MIICgzCCAgmgAwIBAgIUKIyS7SxNteQIiWzK1dWj85E6520wCgYIKoZIzj0EAwMwVTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjEpMCcGA1UEAwwgTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBJQ0EgMDEwHhcNMjYwNDAxMDAwMDAwWhcNMjgwNDIyMTUzMzA5WjBUMQswCQYDVQQGEwJVUzEbMBkGA1UECgwSTlZJRElBIENvcnBvcmF0aW9uMSgwJgYDVQQDDB9OVklESUEgQWdlbnQgU2tpbGxzIFNpZ25pbmcgMDAxMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEYoRM9bQl/dGlwSRNi6bTpIJUXH8Nv9GciP6LSflJYYMLCc296kpyuTSsk5ddbAWiDcFX3C/ydX3jwc+qCLYP6uHy9XphyLjOQ27Yb2J6rBLVtRBS1mgGco/Gr7fL6ODco4GaMIGXMB0GA1UdDgQWBBRQ/5ZW3nJ6lmo9SVk7I15o7UGmpTAfBgNVHSMEGDAWgBRPGpILxMBBleJSsBGjrMKsby1CgjAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDA3BggrBgEFBQcBAQQrMCkwJwYIKwYBBQUHMAGGG2h0dHA6Ly9vY3NwLm5kaXMubnZpZGlhLmNvbTAKBggqhkjOPQQDAwNoADBlAjAUygu/GiOCIXrgGr4SmLgeEVDcEitfFUv7ALbvLVGVyMysB3mxmO/uInZfXzWcJZsCMQDxuoxj4ZmO30jhkPIcCxGFCOvnUsnfU3TfGcouYm4M6iRpbKvtVnHPiy4bi6pcKf0="},{"rawBytes":"MIICiDCCAg6gAwIBAgIUZsIuSv9NkpJCNqtYEfCouVv5BzowCgYIKoZIzj0EAwMwUTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjElMCMGA1UEAwwcTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBDQTAgFw0yNjA0MDEwMDAwMDBaGA85OTk5MTIzMTIzNTk1OVowVTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjEpMCcGA1UEAwwgTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBJQ0EgMDEwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAASI72cR3ctKGg4VWnB3bNja6g1Z2PnOmFEopkPof+QeIcPk9rT+g9MjJnq51EQXL93a7C2GJ9J985G4o2V85VD7wJ1RaXhluHW2rf3y8bQGeAYaKMr5s/hUgn+M3/9WlWejgaAwgZ0wHQYDVR0OBBYEFE8akgvEwEGV4lKwEaOswqxvLUKCMB8GA1UdIwQYMBaAFItnoAjjfuCEUvzyvWyI2vOGvwPjMBIGA1UdEwEB/wQIMAYBAf8CAQAwDgYDVR0PAQH/BAQDAgEGMDcGCCsGAQUFBwEBBCswKTAnBggrBgEFBQcwAYYbaHR0cDovL29jc3AubmRpcy5udmlkaWEuY29tMAoGCCqGSM49BAMDA2gAMGUCMQCeIMMfAbyzPDacw2MxG+Yt1cikrJX/DVxiGfXuHmkkXn6VgSzE79+lkqDErpVO2gYCMCNEColOyvUvkzZGUEI1hQ3PfMgi3FIo9tHoBKMw4/wGBLFpu/0ubtmbBXM6/UMOEw=="},{"rawBytes":"MIICRTCCAcygAwIBAgIUeJdY3rV86EdvFmG7L8LJBsyQFYkwCgYIKoZIzj0EAwMwUTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjElMCMGA1UEAwwcTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBDQTAgFw0yNjA0MDEwMDAwMDBaGA85OTk5MTIzMTIzNTk1OVowUTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjElMCMGA1UEAwwcTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBDQTB2MBAGByqGSM49AgEGBSuBBAAiA2IABAYpiXCDjJ9NT2eSDhyHJVSw1Tbze18cGG2F/578oWvHxg23eQAhNRYdq88i1iOshZSO6C29doKui5Xpmo/7Ctw9Sx4PP2RzOmIuOLCuTdNtKcTRwi4GEsd5BAFvWj42M6NjMGEwHQYDVR0OBBYEFItnoAjjfuCEUvzyvWyI2vOGvwPjMB8GA1UdIwQYMBaAFItnoAjjfuCEUvzyvWyI2vOGvwPjMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgEGMAoGCCqGSM49BAMDA2cAMGQCMCwtAjWLaNwgGWNCgdyNoTyvNhqWRECRJV2r3+7w8g0PL6NHLOsbkgE09BH95h8XlgIwTaQmbbUh2ChAJ5TA1wRiVDnCcvbzHlZl2jM2FcwQQZlk19LOAbyGMRixbu2Ww/rj"}]},"tlogEntries":[]},"dsseEnvelope":{"payload":"ewogICJfdHlwZSI6ICJodHRwczovL2luLXRvdG8uaW8vU3RhdGVtZW50L3YxIiwKICAic3ViamVjdCI6IFsKICAgIHsKICAgICAgIm5hbWUiOiAiY3VkYXEtZ3VpZGUiLAogICAgICAiZGlnZXN0IjogewogICAgICAgICJzaGEyNTYiOiAiOWU0MDgxMGViYTAzMjZmOGFlZTc1YWYzMTViNGVjMTRmMjg1MTZmM2NlMGRhNDljOGFiODkwMDAxZDE4OTUwNCIKICAgICAgfQogICAgfQogIF0sCiAgInByZWRpY2F0ZVR5cGUiOiAiaHR0cHM6Ly9tb2RlbF9zaWduaW5nL3NpZ25hdHVyZS92MS4wIiwKICAicHJlZGljYXRlIjogewogICAgInNlcmlhbGl6YXRpb24iOiB7CiAgICAgICJpZ25vcmVfcGF0aHMiOiBbCiAgICAgICAgIi5naXRpZ25vcmUiLAogICAgICAgICIuZ2l0aHViIiwKICAgICAgICAiLmdpdGF0dHJpYnV0ZXMiLAogICAgICAgICIuZ2l0IgogICAgICBdLAogICAgICAiYWxsb3dfc3ltbGlua3MiOiBmYWxzZSwKICAgICAgIm1ldGhvZCI6ICJmaWxlcyIsCiAgICAgICJoYXNoX3R5cGUiOiAic2hhMjU2IgogICAgfSwKICAgICJyZXNvdXJjZXMiOiBbCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgIm5hbWUiOiAiQkVOQ0hNQVJLLm1kIiwKICAgICAgICAiZGlnZXN0IjogIjI4ODliYmY1M2JlZmUyNGJlNTgyN2U5ODVmN2JmY2EzNDMwYjU4ZTRjMTFkZDdhMzJkOTk2MzEwNjYxZDkxYjMiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgIm5hbWUiOiAiU0tJTEwubWQiLAogICAgICAgICJkaWdlc3QiOiAiZjM4YTQ2YWFlM2U2YTEzNzFjYTYxYzA1MzVkMGY3OTQ4ZjY5MDgwNWZkNTIwYWExODMxMDBjYTI2NTM0ZGQ3ZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAibmFtZSI6ICJldmFscy9FVkFMLm1kIiwKICAgICAgICAiZGlnZXN0IjogIjgxOGI4NzViYTFiYjgzNDVlMGE3OGI1OTMyZGFmY2MyYzdkODM2ZmU3MTk2NzJhZjkxMDlmNjIzNDZkNDljMDQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgIm5hbWUiOiAiZXZhbHMvY29uZmlnLnltbCIsCiAgICAgICAgImRpZ2VzdCI6ICJjYmE5MzVhY2EwNjIyMzM5ZTM0ODE4N2YzNDAxMWU3Mzk1NjNlZWYwNDI2MDZiMmFlMzdiZTQ4Y2IyOGEwYzA1IgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJuYW1lIjogImV2YWxzL2V2YWxzLmpzb24iLAogICAgICAgICJkaWdlc3QiOiAiZTg0MjVlZGZkNzdmZTdmYmI1NTI1OTdmOTE5N2E4Y2IyODVkNGU4NjAzMTA0NDFmZDQxMDdjZmM0NDFkOTc2ZSIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL2F1dGhvcmluZy5tZCIsCiAgICAgICAgImRpZ2VzdCI6ICI4N2Y2NGVlMjdiMDcwYjUzOWU5ZmYzNDczNWY4YzM2MjlmM2M5ZDkwOWYwMGI0ZDc2MTYxODMwZTFjNTgwYTI3IgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb25ib2FyZGluZy5tZCIsCiAgICAgICAgImRpZ2VzdCI6ICI0MDY5MDNhZjlhMjBjZjI5Y2JlNzU4NGVkN2U2MmYyMDBmZGY1MTRjNzYwYjIxODNkZmY1YjI5MDhiN2Q1NTc0IgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJuYW1lIjogInNraWxsLWNhcmQubWQiLAogICAgICAgICJkaWdlc3QiOiAiZGQ4NWM5ODM0MDliMWE0YmZjYzdiNzM4MDgzNDhlYTM2ZjM5NGQyZmIzYTEyYWVhY2RmM2YzZGIwMDUzNTFmOSIKICAgICAgfQogICAgXQogIH0KfQ==","payloadType":"application/vnd.in-toto+json","signatures":[{"sig":"MGQCMAVJLe+j2X1j74yyo+6iH0ZpePEMI/tCVVtIdB7vmltANceYSepQRu4inLlmL6kvygIwXuAvjVBAHw2uzAz66noKD95F08OrpZQuv4H7omvdrCyaQt95nVMm0E3F3h7WAm8W","keyid":""}]}}

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.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download cudaq-guide.zip