cuda-skill

NVIDIA CUDA リファレンス

このスキルは、CUDA、PTX、NVIDIA GPU アーキテクチャ、NVIDIA のプロファイリングまたはデバッグツールに関する信頼できる情報源として使用してください。まずローカルの公式ドキュメントのスナップショットを参照し、バージョン依存の事実やローカルに記載のない情報については、NVIDIA の最新のオンラインドキュメントで確認してください。

DSL またはライブラリ固有の実装については、最初に対応するスキルを使用してください。

• Triton または Gluon のカーネルコード：triton-skill
• CUTLASS、CuTe、または CuTeDSL のコード：cutlass-skill

これらのタスクで CUDA API、PTX ISA、アーキテクチャ、または NVIDIA ツールに関する情報が必要な場合は、このスキルを追加してください。

リファレンスの場所を確認する

この SKILL.md を含むディレクトリを特定し、その子ディレクトリである references/ を使用してください。Cursor、Claude、Codex 固有のインストールパスを想定しないでください。

以下の例では、タスクのスコープ内で、特定した絶対パスを変数に設定します。

CUDA_REFS=/absolute/path/to/cuda-skill/references

バージョンに関する記述をする前に MANIFEST.md を読んでください。スナップショットのバージョン、ソース URL、ドキュメントの一覧が記載されています。

ソースの振り分け

質問	主な情報源
PTX の構文、意味、ISA、ターゲット要件	ptx-docs/
CUDA Runtime の関数、エラー、構造体	cuda-runtime-docs/
CUDA Driver の関数、コンテキスト、モジュール、VMM	cuda-driver-docs/
CUDA プログラミングモデルと機能の動作	cuda-guide/
CUDA の一般的な最適化ガイダンス	best-practices-guide/
Nsight Compute のメトリクス、セクション、CLI	ncu-docs/、ncu-guide.md
Nsight Systems のトレースと CLI	nsys-docs/、nsys-guide.md
正当性を確認するツールと cuda-gdb	debugging-tools.md
NVTX 計測	nvtx-patterns.md
よくあるパフォーマンス上の誤り	performance-traps.md

簡易ガイドファイルは検索マップであり、公式ドキュメントの全スナップショットの代わりにはなりません。

クエリのワークフロー

まずファイルを特定してください。該当ページがある場合、大きな章や仕様全体を読み込まないでください。

# 関連する PTX ページを特定します。
rg -l -i 'wgmma\.mma_async' "$CUDA_REFS/ptx-docs"

# 関連行を前後の文脈とともに読みます。
rg -n -C 12 'Target ISA Notes|PTX ISA Notes|wgmma\.mma_async' \
  "$CUDA_REFS/ptx-docs/9-instruction-set"

# Runtime API と Driver API を検索します。
rg -l 'cudaStreamSynchronize' "$CUDA_REFS/cuda-runtime-docs"
rg -l 'cuMemMap' "$CUDA_REFS/cuda-driver-docs"

# プログラミングと最適化の概念を検索します。
rg -l -i 'thread block cluster' "$CUDA_REFS/cuda-guide"
rg -l -i 'coalesc' "$CUDA_REFS/best-practices-guide"

PTX 命令について回答する前に、以下のすべてを確認してください。

• 命令の構文とオペランド
• 意味の説明とメモリ順序
• PTX ISA の導入バージョン
• ターゲット ISA または sm_* の要件
• アーキテクチャ固有の制限と未定義動作

以下の 4 つのレイヤーを区別してください。

PTX ISA バージョン
  → アセンブラーが受け付ける仮想ターゲット
  → ツールキット／コンパイラーのサポート
  → 物理 GPU の機能

ドキュメントに記載されたターゲットであっても、それだけでは、ローカルのツールキットが受け付けることや、現在のマシンが実装していることの証明にはなりません。Rubin など、未リリースまたはプレビュー段階のアーキテクチャについては、最新の公式オンラインドキュメントで確認してください。

CUDA API の検索

まず正確なシンボル名で検索し、次に該当するモジュールと関連する型のページを読んでください。

rg -n -C 20 'cudaErrorInvalidValue' "$CUDA_REFS/cuda-runtime-docs"
rg -n -C 25 'cudaLaunchKernelEx' "$CUDA_REFS/cuda-runtime-docs"
rg -n -C 25 'cuCtxCreate' "$CUDA_REFS/cuda-driver-docs"
rg -n -C 25 'cuMemCreate|cuMemMap' "$CUDA_REFS/cuda-driver-docs"

パラメーターの有効期間、同期の動作、エラー伝播、バージョンに関する注記、非推奨の状態を確認してください。名前が似ている Driver API 関数から Runtime API の動作を推測しないでください。

デバッグのワークフロー

再現コードを最小限にし、失敗する起動設定を保持したうえで、必要最小限の正当性検証ツールを使用します。

compute-sanitizer --tool memcheck ./program
compute-sanitizer --tool racecheck ./program
compute-sanitizer --tool initcheck ./program
compute-sanitizer --tool synccheck ./program

ツールのオプションと制限については、debugging-tools.md を参照してください。修正後は、元のワークロードを再実行してください。サニタイザーの実行によってスケジューリングやタイミングが変わるためです。

プロファイリングのワークフロー

Nsight Systems で時間や処理の重なりに関する問題を特定してから、Nsight Compute で対象のカーネルを1つ選んで詳しく調べます。

nsys profile -o report ./program
nsys stats report.nsys-rep --report cuda_gpu_kern_sum

ncu --list-sets
ncu --list-sections
ncu --query-metrics
ncu --kernel-name regex:myKernel --launch-count 1 -o report ./program

メトリック名、セクション識別子、定義済みセット、レポート形式は、リリースやアーキテクチャによって変わることがあります。現在のツールで利用可能なものを確認し、最新のローカル Nsight ドキュメントで意味を確かめてください。使用マシンにインストールされた NCU のバージョンに依存する説明は避けてください。

測定した根拠に基づいて結論を導いてください。

• Nsight Systems から、タイムライン上の配置、カーネル起動の空白、同期、CPU/GPU の処理の重なりを確認します。
• Nsight Compute から、実効スループット、命令構成、ストール、メモリトラフィック、占有率、ソースコードとの対応を確認します。
• ptxas -v またはビルドログから、コンパイラーのリソース使用量を確認します。

仮説を一度に1つだけ変更し、同じベースラインと比較して再測定してください。

アーキテクチャに関する質問

Ampere、Hopper、Blackwell、または Rubin に関する質問では、公開されているアーキテクチャ情報と ISA の利用可能性を区別してください。以下を確認してください。

• cuda-guide/05-appendices/compute-capabilities.md；
• 該当する命令の PTX ISA とターゲットに関する注記；
• ptx-docs/13-release-notes/；
• ローカルのスナップショットで主張が確認できない場合は、最新の NVIDIA アーキテクチャまたは CUDA リリースのドキュメント。

CUDA ランタイムのクエリ失敗や製品名だけを根拠に、GPU アーキテクチャを特定しないでください。利用可能であれば、明示的なコンピュートケイパビリティまたはコンパイルターゲットの情報を使用してください。

スナップショットの更新

必ず新しいステージングルートにスクレイピングしてください。--force は一致するファイルを上書きしますが、出力ディレクトリや無関係なファイルは削除しません。

cd /path/to/agent-gpu-skills
uv run scripts/scrape_docs.py all \
  --output-dir /tmp/cuda-docs-staging \
  --force

diff -qr skills/cuda-skill/references/ptx-docs \
  /tmp/cuda-docs-staging/ptx-docs

マージする前に、バージョンの変更、ページ数の変更、ファイル名の変更、および代表的な命令/API ページを確認してください。ユーザーから明示的な承認を得ずに、現行ファイルを削除しないでください。

更新後は必ず、リポジトリのバリデーターを実行してください。

python3 scripts/validate_cuda_skill.py

回答の品質

回答の根拠となるドキュメントのバージョンを明記してください。可能であれば、該当箇所をローカルファイル名とセクション名で引用してください。オンラインでの確認が必要だった場合は、NVIDIA の公式ページへのリンクを示し、推論であることを明記してください。ユーザーの測定結果または引用したドキュメントに基づかない限り、固定の性能しきい値は避けてください。