Index of every page on this site: llms.txt
All skills
nvidia avatar

/cudaq-guide

@6b75e9e
by NVIDIA Corporationnvidia/skills4.1k stars
547
Run it yourself

Use for CUDA-Q setup, simulation targets, QPU access, and @cudaq.kernel authoring guidance.

Use this Skill: https://skilld.dev/gh/nvidia/skills/cudaq-guide

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈26 tokens for metadata: the name and description. ≈1.1k when used: this file. ≈15k more on demand in 7 files.

Description uses 1.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈105 characters, or 1.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alertstoday3 checks · Risk SAFE
  • Gen Agent Trust Hubtoday

    The CUDA-Q Guide skill provides comprehensive documentation and onboarding for NVIDIA's CUDA-Q platform. It covers installation, quantum kernel authoring, and simulation targets. The skill emphasizes security best practices, particularly regarding the safe handling of provider credentials.

  • Socket1d

    No alerts

  • Snyktoday

    Risk: LOW · No issues

Signed by skilld at 6b75e9e. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 months ago
title
CUDA-Q Guide
version
1.1.2
author
CUDA-Q Team <cuda-quantum@nvidia.com>
Other metadata
tags
[
  "cuda-quantum",
  "quantum-computing",
  "onboarding",
  "getting-started",
  "authoring",
  "kernels",
  "nvidia"
]
tools
[
  "Read",
  "Glob",
  "Grep"
]
compatibility
Python 3.10+, C++ 20
metadata
{
  "author": "CUDA-Q Team <cuda-quantum@nvidia.com>",
  "tags": [
    "cuda-quantum",
    "quantum-computing",
    "onboarding",
    "getting-started",
    "nvidia"
  ],
  "languages": [
    "python",
    "c++"
  ],
  "domain": "quantum"
}

README badge

README badge for nvidia/skills/cudaq-guide