Ascend for PyTorch Agent Skills

ℹ️ 简介

Ascend for PyTorch Agent Skills 是专为 Ascend for PyTorch 社区及其核心组件 TorchNPU 的开发者打造的一站式可复用技能集合。它将 TorchNPU 方案设计、代码开发、问题定位、知识问答等流程沉淀为结构化工作流，帮助 Agent 在合适的场景下稳定执行并输出可复核的结果。

本技能集面向以下社区角色：

• 开发者：借助知识问答、问题定位和结构化开发流程，快速完成日常 TorchNPU 开发与调试任务。
• 贡献者：按照现有流程、检查清单和交付模板完成算子接入、测试、文档与问题修复，降低参与社区贡献的门槛。
• 维护者：依托方案分析、PR 审核和工程质量检查能力推进社区维护，减少遗漏关键证据、验证步骤或交付物。

每个顶层技能包都是一个独立目录，至少包含一个 SKILL.md，复杂技能包还会包含子技能、脚本、模板、参考资料和示例。下方清单按 12 个可直接选择的顶层技能包 组织；套件内部的子技能由总入口按任务自动路由，新用户通常不需要逐个调用。

✨ 能力介绍

场景	能力
算子开发	覆盖 CANN/aclnn 算子接入或修改、UT 与 FakeTensor 测试、API 文档和兼容性基线。
问题定位与修复	覆盖 API 一致性工单、PyTorch 上游 UT 失败、分布式/HCCL、图模式、内存和缺失算子等场景。
工程质量	覆盖当前改动文件的 CI 静态检查与受控修复，以及基于 whl 构建和测试的回归提交二分。
源码与变更分析	覆盖 PyTorch/TorchNPU 源码设计分析、上游 PR 影响评估和 torch-npu PR 审核。

🧩 技能总览

Skill	适用场景	典型输入	主要产出 / 依赖
api-consistency	处理 A2/A3/A5 上的 TorchNPU API 一致性问题，自动区分 ATK 与 torchrun、python、pytest、bash 等非 ATK 复现路径，也支持批量工单。	DTS/问题描述、完整复现命令、ATK xlsx 或运行日志、可选远端环境信息。	复现记录、证据分析和结单文档；按场景需要 ATK、Python xlsx 解析、SSH 和可用的 NPU 环境。
ci-static-errors-fix	检查并安全修复当前 Git 工作区改动文件中的 lintrunner、FLAKE8、空白、格式和 CODESPELL 问题。	含未提交改动的 PyTorch 风格仓库。	低风险修复、残留问题和验证摘要；依赖 lintrunner、uv，FLAKE8 修复会临时使用 autopep8。
com-auto-binary-pr	已知 good/bad 范围时，通过反复构建 whl 和运行测试定位引入问题的提交。	二分范围、测试命令、容器/构建配置，或 binary_config.json。	binary_result.json、构建与测试记录、可疑提交；依赖可用的 TorchNPU 构建和测试环境。
core-requirement-analyze	基于 PyTorch 或 TorchNPU 源码分析模块、机制、算子、commit 或 diff，形成可用于修改和扩展代码的中文材料。	目标模块、源码路径、commit/diff，可选已有分析材料和输出要求。	带源码路径、调用链、扩展点和影响范围的需求/设计与实现分析文档。
npu-graph-skill	处理 NPUGraph/ACLGraph 的知识问答、代码导航、报错诊断、日志分析、性能分析和 MCP 配置。	图模式问题、错误堆栈、TORCH_NPU_LOGS、图 dump、性能现象或概念问题。	自动路由到 5 个子技能并输出分析/诊断报告；部分诊断与性能任务需要 TorchNPU、OpPlugin、CANN/NPU 环境。
op-adaptation	将新 CANN/aclnn 算子接入 TorchNPU，或修改已有算子的接口、变体、反向和实现。	Create：算子 .md + _def.cpp；Modify：算子名 + 修改说明。	YAML、C++、Meta、Derivatives、测试、文档、兼容性基线、CHECKLIST 和集成摘要；依赖 OpPlugin/TorchNPU 构建环境，并组合使用 op-test 与 op-apidoc。
op-apidoc	为 TorchNPU 自定义算子生成或补齐中文 API 参考文档。	算子名、YAML func:、参数与约束，或 op-adaptation 生成的 CHECKLIST。	API Markdown、导航索引和 Python docstring 更新。
op-test	为 TorchNPU 自定义算子或原生算子适配生成 UT 和 FakeTensor 测试，并在条件允许时执行。	算子实现、签名、参数约束，或 op-adaptation 的 CHECKLIST。	测试文件、参数覆盖矩阵和执行报告；无 NPU 时仍可生成测试，但会跳过上板执行。
pytorch-pr-analysis	分析指定时间段内合入 PyTorch main 的 PR，评估其对 torch-npu 的兼容性影响。	起止日期。	PR 明细、图模式/分布式深度分析和 Excel 报告；依赖 GITHUB_TOKEN、requests、openpyxl，飞书与外部深度分析能力按任务选配。
torch-npu-issue-pipeline-core	端到端处理 Core 组 PyTorch 上游 UT 在 NPU 上的失败，覆盖准备、复现、诊断、修复、验证和交付。	完整参数化用例名、issue_id；首次使用还需仓库、分支范围和 GitCode 配置。	修复代码、复现/根因/验证报告、合入描述和 PR/MR；依赖 NPU、CANN、PyTorch/TorchNPU/OpPlugin 仓库及交付权限。
torch-npu-issue-pipeline-distributed	处理分布式、HCCL 或图模式相关的上游 PyTorch UT 失败，按复现 → 诊断 → 验证推进。	完整参数化用例名、错误日志和环境说明。	复现报告、根因分析、修复验证报告和 PR 描述材料；图模式问题会检查 Inductor/Triton 调试产物。
torch-npu-pr-review	审核 Ascend/pytorch 的单个或多个 GitCode PR，支持 issue 入口、关联 PR 发现和跨分支对比。	GitCode issue/PR 链接，可选目标分支和访问 token。	原始采集数据、summary.json、data_report.md 和审核报告；采集脚本仅依赖 Python 标准库，token 为可选增强项。

常见选择

• 接入或修改一个算子：从 op-adaptation 开始，它会在流程中组合 op-test 和 op-apidoc。
• 只补测试或文档：分别直接使用 op-test 或 op-apidoc。
• 处理 API 一致性问题：使用 api-consistency；没有 ATK 时也可以提供可执行脚本和完整日志。
• 修复 PyTorch 上游 UT：普通 Core 交付流程使用 torch-npu-issue-pipeline-core；分布式、HCCL 或专项图模式问题使用 torch-npu-issue-pipeline-distributed。
• 咨询或排查 NPUGraph/ACLGraph：使用 npu-graph-skill，由总入口选择知识、诊断、日志或性能子技能。
• 分析上游变更：批量评估某个时间段的 PyTorch PR 使用 pytorch-pr-analysis；审核具体 torch-npu PR 使用 torch-npu-pr-review。

🚀 快速入门

1. 选择技能

先根据上方表格选择最接近任务的顶层技能。描述比较明确时，可以直接用自然语言交代任务，Agent 会根据 SKILL.md 中的触发条件匹配；存在多个相近技能时，建议明确写出技能名。

2. 确保运行环境可用

请根据所选 Skill 的 README 准备运行环境和依赖。

3. 提供最小必要上下文

为了让 Agent 能够直接开始工作，建议至少提供：

• 任务目标：希望分析、修改、测试还是生成文档。
• 工作目录或仓库：例如 TorchNPU、OpPlugin 或 PyTorch 源码路径。
• 问题输入：算子资料、完整用例名、复现命令、日志、PR 链接或时间范围。
• 环境信息：目标分支、Python/PyTorch/TorchNPU/CANN 版本，以及 NPU 是否可用。
• 交付要求：仅分析，还是需要修改代码、运行验证或准备 PR 材料。

4. 用任务语言触发

请使用 op-adaptation，把 ./aclnn_input/DynamicQuant 下的
aclnnDynamicQuant.md 和 dynamic_quant_def.cpp 接入当前 OpPlugin 仓库，
完成签名校验、测试、API 文档和集成摘要。

请使用 torch-npu-issue-pipeline-distributed 处理这个 HCCL 社区用例失败：
case_name=<完整参数化用例名>
错误日志=<粘贴完整日志>

请使用 torch-npu-pr-review 审核以下 PR，并比较它们在不同目标分支的差异：
<PR 链接 1> <目标分支>
<PR 链接 2> <目标分支>

📦 安装指南

方式一：使用 Skills 管理工具

本仓托管在 GitCode，请使用完整仓库 URL：

# 查看仓库中可安装的 skills
npx skills add https://gitcode.com/Ascend/agent-skills --list

# 安装一个技能包
npx skills add https://gitcode.com/Ascend/agent-skills --skill npu-graph-skill

# 算子接入建议同时安装三个协作技能
npx skills add https://gitcode.com/Ascend/agent-skills \
  --skill op-adaptation \
  --skill op-test \
  --skill op-apidoc

如需指定 Agent，可按管理工具支持的名称增加 -a <agent>；在 CI/CD 中可结合 -g -y 使用非交互安装。

方式二：克隆后从本地安装

git clone https://gitcode.com/Ascend/agent-skills.git
cd agent-skills

npx skills add ./official/PyTorch --list
npx skills add ./official/PyTorch --skill ci-static-errors-fix

方式三：手动复制

Skills 本质上是包含 SKILL.md 及配套资源的目录。也可以把所需的整个顶层技能目录复制到目标 Agent 的 skills 搜索路径，不要只复制 SKILL.md，否则脚本、模板、参考资料和子技能会缺失。

Agent	常见项目级目录
OpenCode	.opencode/skills/
Claude Code	.claude/skills/
TRAE	.trae/skills/
Cursor	.cursor/skills/

以 op-adaptation 为例：

cp -r official/PyTorch/op-adaptation .claude/skills/
cp -r official/PyTorch/op-test .claude/skills/
cp -r official/PyTorch/op-apidoc .claude/skills/

📘 使用说明

运行原则

• 先阅读并调用顶层 SKILL.md。复杂套件会自行加载阶段技能、工具和参考资料。
• 保留完整目录结构；references/、scripts/、templates/、examples/ 往往是工作流的一部分。
• 优先提供原始、完整、可追溯的输入，例如完整命令、日志、diff 和报告文件，不要只提供截图中的局部结论。
• 代码修改后应按技能要求执行最小必要验证；没有 NPU 或依赖缺失时，应明确记录跳过项和阻塞原因。
• Token、密码和私有凭证只通过安全的环境变量或本地配置提供，不要写入提示词、日志、报告或 Git 仓库。
• 涉及提交、推送、创建 PR/MR 等外部变更时，先确认目标仓库、分支和交付范围。

📂 目录结构

official/PyTorch/
├── README.md
├── api-consistency/
├── ci-static-errors-fix/
├── com-auto-binary-pr/
├── core-requirement-analyze/
├── npu-graph-skill/
├── op-adaptation/
├── op-apidoc/
├── op-test/
├── pytorch-pr-analysis/
├── torch-npu-issue-pipeline-core/
├── torch-npu-issue-pipeline-distributed/
└── torch-npu-pr-review/

具体触发条件、输入约束、执行步骤和输出格式，请以各技能目录中的 SKILL.md 为准。