SkillAgentSearch skills...

cudaq-importing

Use when porting circuits from another framework (e.g. Qiskit) into CUDA-Q kernels while preserving the source algorithm and validation fidelity.

Install / Use

npx skills add NVIDIA/skills --skill cudaq-importing

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

87/100

Supported Platforms

Universal

Our assessment of cudaq-importing

cudaq-importing scores 87/100 on our quality scale, 2120th of 4,698 Development & Engineering skills we index (top 46%).

Its SKILL.md is 7.3 KB long, well organised into 9 sections and no code examples: a thorough specification that gives an agent plenty to work with.

With 3,421 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
29/30
Structure
13/20
Description
15/15
Adoption
15/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so cudaq-importing is actively maintained.
  • Our last check on 2026-11-02 found the source still online.
  • It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-09-29. Automated pattern scan on 2026-09-29. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

cudaq-importing compared with similar skills

All 4 of these similar skills score higher than cudaq-importing; compare them before choosing.

SkillScoreStarsUpdatedFormat
cudaq-importing (this skill)by NVIDIA873.4k54d agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
headroomby headroomlabs-ai10079.8ktodayCLAUDE.md
ai-job-searchby ai-job-search-dev10072.1ktodayCLAUDE.md

Frequently asked questions

How do I install cudaq-importing?
Run npx skills add NVIDIA/skills --skill cudaq-importing. The install tabs above show the steps for each supported agent.
Which AI agents does cudaq-importing work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is cudaq-importing safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is cudaq-importing still maintained?
The repository was last updated about 2 months ago, so cudaq-importing is actively maintained.

name: "cudaq-importing" title: "CUDA-Q Importing" description: "Use when porting circuits from another framework (e.g. Qiskit) into CUDA-Q kernels while preserving the source algorithm and validation fidelity." version: "1.0.2" author: "CUDA-Q Team cuda-quantum@nvidia.com" tags: [cuda-quantum, quantum-computing, importing, porting, migration, qiskit, kernels, nvidia] tools: [Read, Glob, Grep] license: "Apache-2.0" compatibility: "Python 3.10+" metadata: author: "CUDA-Q Team cuda-quantum@nvidia.com" short-description: "Port circuits from other frameworks into CUDA-Q" tags: - cuda-quantum - quantum-computing - importing - porting - migration - qiskit - nvidia languages: - python domain: "quantum"

CUDA-Q Importing

Purpose

Use this skill to port quantum circuits from another framework into CUDA-Q Python kernels. This includes Qiskit code and Qiskit-style circuit construction, as well as other framework-driven circuit builders. The goal is a framework-free CUDA-Q port that preserves the source quantum algorithm, matches source behavior at small test sizes, and documents any unavoidable CUDA-Q limitations.

For authoring new CUDA-Q kernels from scratch, and for CUDA-Q installation, simulation targets, QPU access, and parallelization, use the cudaq-guide skill (/cudaq-guide author for kernel authoring).

Prerequisites

  • Python 3.10+.
  • CUDA-Q installed in the target environment. Check the runtime with: python -c "import cudaq; print(getattr(cudaq, '__version__', 'unknown'))".
  • Access to the source implementation and a way to run or inspect its expected behavior.
  • To validate against the source framework (e.g. Qiskit/Aer), it must be installed in the validation environment only. The final CUDA-Q port itself must not require the source framework.
  • When using CUDA-Q documentation or repository MCP connectors, verify the connector is available before relying on it; otherwise use local docs or the source tree.
  • When debugging and the installed CUDA-Q version differs from the latest documentation, review relevant documentation or source changes before treating a behavior difference as a porting bug.

Workflow

  1. Read the source circuit construction and identify the exact algorithm, qubit/register layout, measurement behavior, and any framework helpers.
  2. Preserve the high-level quantum algorithm. Do not replace mid-circuit measurement, QPE structure, oracle definitions, or decomposition strategy without explicit user permission.
  3. Select the CUDA-Q execution pattern:
    • Use cudaq.sample for final-measurement sampling.
    • Use cudaq.run when mid-circuit measurement values must be returned or used per shot.
    • Use runtime-argument kernels instead of generated per-size kernels unless CUDA-Q requires a fixed-length return shape.
  4. Translate gates and subcircuits. For detailed gate mappings, ordering rules, precision guidance, and helper-extraction patterns, read references/porting-reference.md.
  5. Remove runtime source-framework dependencies from the CUDA-Q port. Extract pure helpers into framework-free modules.
  6. Validate with small deterministic inputs before scaling. Compare raw count keys and distributions, not just aggregate fidelity.
  7. Re-run any previously failing configurations after every fix.

Core Rules

  • Keep the source algorithm intact unless the user approves a change.
  • Do not introduce fixed qubit caps, fixed control arities, or source-framework imports unless they are genuinely unavoidable and documented.
  • Prefer native CUDA-Q gates (r1.ctrl, x.ctrl, swap.ctrl, etc.) over transpiling through the source framework.
  • Keep bit-order conversion at the port boundary: allocation order, measurement return list, or final count-key formatting.
  • Match floating-point precision when comparing CUDA-Q and source results if fidelity differences matter (CUDA-Q defaults to fp32, Qiskit to fp64).
  • Accept source flags that become no-ops in CUDA-Q when doing so preserves source-compatible behavior.

When to Read the Reference

Read references/porting-reference.md when you need any of the following:

  • Qiskit-to-CUDA-Q gate translation table.
  • Bit-ordering and count-key conventions.
  • CUDA-Q fp32 vs Qiskit fp64 precision implications.
  • Pure-Python helper extraction and import-blocker validation.
  • Recursive-constructor emitters or gate-recorder patterns.
  • Detailed port validation checklist and external CUDA-Q references.

Limitations

  • Guidance targets CUDA-Q 0.14/0.15 decorator-mode Python APIs. Re-check behavior against the installed CUDA-Q version for version-sensitive features.
  • Some CUDA-Q kernel-language constructs are constrained compared with normal Python; use the companion cudaq-guide skill (/cudaq-guide author) for core CUDA-Q authoring constraints and shared kernel patterns.
  • CUDA-Q and source frameworks differ in default precision and count-key display order. Apparent fidelity or bitstring mismatches may be convention differences.
  • Hardware-target behavior, available backends, and target options depend on the local CUDA-Q installation.
  • This skill does not guarantee equivalent performance; it focuses on correctness-preserving ports.

Troubleshooting

Use this format when diagnosing failures:

  • Error: ModuleNotFoundError: qiskit (or another source framework) from a CUDA-Q path. Cause: The port still imports the source framework. Solution: Move pure helpers into a framework-free module and verify with the import-blocker pattern in the reference.

  • Error: Fidelity looks plausible but raw keys are reversed. Cause: The source framework and CUDA-Q count-key ordering differ. Solution: Fix allocation, return-list order, or formatting at the port boundary. Do not alter the algorithm.

  • Error: Deep-circuit fidelity differs between frameworks. Cause: CUDA-Q and the source framework may be using different floating-point precision. Solution: Match precision before comparing, then rerun the smallest failing deterministic case.

  • Error: A multi-controlled operation works for small controls but fails or silently changes behavior at higher arity. Cause: The port used a fixed-arity dispatcher. Solution: Use CUDA-Q control-list patterns for arbitrary arity.

  • Error: MCP documentation or repository lookup fails. Cause: Connector unavailable, stale, or transiently failing. Solution: Verify the connector/resource list, retry transient failures once, then fall back to local docs/source or official CUDA-Q docs. Do not change the port based on unverified MCP results.

  • Error: CUDA-Q behavior conflicts with documentation while debugging. Cause: The installed CUDA-Q version may differ from the latest documentation. Solution: Check cudaq.__version__, then review relevant documentation or source changes between the installed version and latest before changing the port.

References

  • Detailed porting reference
  • Companion skill: cudaq-guide (/cudaq-guide author) for CUDA-Q authoring patterns, kernel-language constraints, execution APIs, and debugging workflow.

Related Skills

View on GitHub
GitHub Stars3.4k
CategoryDevelopment
Updated1mo ago
Forks412

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions
cudaq-importing — Universal Skill: Install & Safety Check | SkillAgent