Guides users through CUDA-Q installation, GPU simulation targets, QPU access, and Python @cudaq.kernel authoring.
- GitHub stars
- 3,934
- Files
- 9
- Last commit
- Nov 11, 2026
- License
- Apache-2.0
- Allowed tools
- —
What does the cudaq-guide skill do?
cudaq-guide guides users through CUDA-Q installation, GPU simulation targets, QPU access, and Python @cudaq.kernel authoring.
Summary generated from the skill's SKILL.md.
About the cudaq-guide skill
Navigating the setup and development of NVIDIA's quantum-classical programming model is what this skill enables for developers. It provides structured guidance for installing CUDA-Q in Python or C++ environments and helps users transition from basic installation to writing complex kernels. An agent should load this skill when a user needs to configure simulation targets, manage QPU credentials, or troubleshoot compiler issues within the @cudaq.kernel framework.
The skill utilizes tools like Read, Glob, and Grep to access local documentation files such as onboarding.md and authoring.md. It assists with selecting appropriate execution targets, including multi-GPU setups, tensor-network simulations, or CPU-only modes via qpp-cpu. While it covers a wide range of quantum workflows, it is specifically designed for CUDA-Q native development and does not handle Qiskit porting tasks.
What an agent can do with it
- 1Set up CUDA-Q environmentsHelp a developer install and validate CUDA-Q for either Python or C++ workflows.
- 2Configure GPU simulation targetsGuide a user in selecting between single GPU, multi-GPU, or CPU-only simulation modes.
- 3Author Python quantum kernelsAssist in writing and debugging Python code using the @cudaq.kernel decorator.
- 4Connect to QPU hardwareProvide instructions for selecting a provider and setting up credentials for real quantum hardware.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the cudaq-guide skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the cudaq-guide skill in Claude Code
~/.claude/skills/cudaq-guide/SKILL.md
$ npx degit NVIDIA/skills/skills/cudaq-guide ~/.claude/skills/cudaq-guideInstall the cudaq-guide skill in Claude Code (project)
.claude/skills/cudaq-guide/SKILL.md
$ npx degit NVIDIA/skills/skills/cudaq-guide .claude/skills/cudaq-guideInstall the cudaq-guide skill in Codex
~/.agents/skills/cudaq-guide/SKILL.md
$ npx degit NVIDIA/skills/skills/cudaq-guide ~/.agents/skills/cudaq-guideInstall the cudaq-guide skill in Gemini CLI
~/.gemini/skills/cudaq-guide/SKILL.md
$ npx degit NVIDIA/skills/skills/cudaq-guide ~/.gemini/skills/cudaq-guideInstall the cudaq-guide skill in Claude.ai
npx degit NVIDIA/skills/skills/cudaq-guide cudaq-guide && zip -r cudaq-guide.zip cudaq-guide # claude.ai → Customize → Skills → + → Create skill → Upload a skill → cudaq-guide.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablenvidia/skills/skills/cudaq-guide is public and reachablegithub.com/nvidia/skills/tree/HEAD/skills/cudaq-guide ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-11github.com/nvidia/skills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/nvidia/skills/blob/HEAD/skills/cudaq-guide/SKILL. ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/nvidia/skills/blob/HEAD/skills/cudaq-guide/SKILL. ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 117 linesgithub.com/nvidia/skills/blob/HEAD/skills/cudaq-guide/SKILL. ↗Pass
SKILL.md
View on GitHubCUDA-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 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 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 in this skill
9cudaq-guide skill questions
How do I install the cudaq-guide skill in Claude Code?
Run npx degit NVIDIA/skills/skills/cudaq-guide ~/.claude/skills/cudaq-guide. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the cudaq-guide skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What are the prerequisites for using CUDA-Q?
Python 3.10+ is required for Python workflows, and C++20 is needed for C++ workflows. GPU acceleration requires the CUDA Toolkit and an NVIDIA GPU on Linux, while macOS is limited to CPU-only simulation.
How do I handle a situation where no GPU is detected?
You should verify your CUDA Toolkit installation and run nvidia-smi. If the GPU is still not detected, you can fall back to using qpp-cpu.
Can this skill help me port Qiskit code to CUDA-Q?
No, this skill is not for Qiskit porting; you should use the cudaq-importing skill for those questions.