mcpField
C
cuda-skill

cuda-skill

github.com/slowlyc开发172171 次安装12 周前更新
代码仓库

关于 cuda-skill

面向 CUDA 开发者的参考技能，汇集 CUDA、PTX、NVIDIA GPU 架构及分析和调试工具的文档查询流程。它引导使用本地官方文档快照，并在版本敏感或缺少资料时核对 NVIDIA 当前文档。

主要功能

  1. 01按主题定位官方文档
  2. 02查询 PTX 指令与限制
  3. 03查阅 CUDA Runtime 和 Driver API
  4. 04指导正确性调试与性能分析
  5. 05区分架构和工具版本信息

适用场景

  1. 01核实 PTX 指令要求
  2. 02查找 CUDA API 参数行为
  3. 03用 Compute Sanitizer 排查错误
  4. 04通过 Nsight 工具分析性能

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/slowlyc/agent-gpu-skills --skill cuda-skill

安装后在 Claude Code 中输入/cuda-skill确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/best-practices-guide/
1-overview.md
10-memory-optimizations.md
10.1-data-transfer-between-host-and-device.md
10.2-device-memory-spaces.md
10.3-allocation.md
10.4-numa-best-practices.md
11-execution-configuration-optimizations.md
11.1-occupancy.md
11.2-hiding-register-dependencies.md
11.3-thread-and-block-heuristics.md
11.4-effects-of-shared-memory.md
11.5-concurrent-kernel-execution.md
11.6-multiple-contexts.md
12-instruction-optimization.md
12.1-arithmetic-instructions.md
12.2-memory-instructions.md
13-control-flow.md
13.1-branching-and-divergence.md
13.2-branch-predication.md
14-deploying-cuda-applications.md
15-understanding-the-programming-environment.md
15.1-cuda-compute-capability.md
15.2-additional-hardware-data.md
15.3-which-compute-capability-target.md
15.4-cuda-runtime.md
16-cuda-compatibility-developers-guide.md
16.1-cuda-toolkit-versioning.md
16.2-source-compatibility.md
16.3-binary-compatibility.md
16.4-cuda-compatibility-across-minor-releases.md

详细介绍

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 函数、上下文、模块、VMMcuda-driver-docs/
CUDA 编程模型和功能行为cuda-guide/
CUDA 通用优化指南best-practices-guide/
Nsight Compute 指标、章节和 CLIncu-docs/、ncu-guide.md
Nsight Systems 跟踪和 CLInsys-docs/、nsys-guide.md
正确性工具和 cuda-gdbdebugging-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 和 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_* 要求；
  • 特定架构的限制和未定义行为。

请将以下四个层次分开：

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 分析选定的一个内核。

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 或构建日志查看编译器资源用量。

一次只检验一个假设，并针对同一基线重新测量。

架构问题

对于 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

合并前，请检查版本变化、页面数量变化、重命名的文件，以及有代表性的指令/API 页面。未经用户明确批准，不要删除现有文件中的过时内容。

每次更新后运行仓库验证器：

python3 scripts/validate_cuda_skill.py

答案质量

说明答案依据的文档版本。尽可能引用具体的本地文件和章节。如果需要在线验证，请链接 NVIDIA 官方页面，并标明推断内容。除非性能阈值来自用户的测量结果或引用的文档，否则避免使用硬编码的性能阈值。

评论

支持 Markdown