SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsascendc-operator-dev

ascendc-operator-dev

Coding & development

View repository

Updated 10-16 05:00

About this skill

AscendC Operator End-to-End Development Orchestration

Skill Type: Process-oriented (seven-phase workflow, serial orchestration of sub-skills)

This skill orchestrates seven sub-skills to drive an ascend-kernel operator from zero to production-ready.

Core Principles

  1. Seven-Phase Serial: Project initialization → Design document → Test case generation → Code generation & testing → Interface documentation → Accuracy evaluation → Performance evaluation, executed in strict order
  2. Sub-skill Execution: Each phase MUST calls the corresponding sub-skill and must not implement it on its own
  3. Phase Gating: Only after all checkpoints of the previous phase pass does the next phase begin
  4. Design-Driven Coding: Code generation depends on the Tiling strategy and UB allocation table in the design document
  5. Automated Design: No need for the user to provide a design document in advance; the design phase generates it automatically
  6. Unified Test Case Generation: Immediately after design is complete, generate the test case document for reuse by subsequent accuracy evaluation and performance evaluation
  7. Documentation Closed Loop: After compilation and testing pass, MUST generate PyTorch-style Chinese interface documentation and display it in the chat interface
  8. Accuracy Closed Loop: The operator is considered complete only after passing a comprehensive accuracy evaluation of >=30 cases
  9. Performance Closed Loop: The operator must pass the msprof performance comparison evaluation and output a performance report
  10. Result Visualization: The results of Phase 4/5/6/7 MUST are displayed directly in the chat interface in Markdown form; do not output only paths

List of Available Sub-Skills

Skill Path Responsibility
ascendc-operator-project-init ascendc-operator-project-init/SKILL.md Detect/create an ascend-kernel project and generate the operator skeleton directory
ascendc-operator-design ascendc-operator-design/SKILL.md Analyze operator requirements and generate a design document (including Tiling strategy and UB allocation table)
ascendc-operator-testcase-gen ascendc-operator-testcase-gen/SKILL.md Generate a unified test case document based on the design document, for reuse by accuracy evaluation and performance evaluation
ascendc-operator-code-gen ascendc-operator-code-gen/SKILL.md Generate op_host/op_kernel code, framework adaptation, and compilation testing based on the design document
ascendc-operator-compile-debug ascendc-operator-compile-debug/SKILL.md Compile, install the whl, generate test files, and run accuracy tests (called internally by code-gen)
ascendc-operator-doc-gen ascendc-operator-doc-gen/SKILL.md Extract interface information from the source code and generate PyTorch-style Chinese API documentation (mandatory phase)
ascendc-operator-precision-eval ascendc-operator-precision-eval/SKILL.md Generate >=30 accuracy test cases, run them, and output an accuracy verification report (mandatory phase)
ascendc-operator-performance-eval ascendc-operator-performance-eval/SKILL.md Use msprof to compare the performance of the project operator and the native operator, and output a performance evaluation report (mandatory phase)

Workflow Overview

Phase 1        Phase 2        Phase 3        Phase 4                      Phase 5        Phase 6         Phase 7
工程初始化  ──▶ 设计文档  ──▶ 用例生成  ──▶ 代码生成+框架适配+编译测试  ──▶ 接口文档  ──▶ 精度评估报告  ──▶ 性能评测报告
project-init   design         testcase-gen   code-gen → compile-debug      doc-gen        precision-eval  performance-eval

输入: 算子名称 + 功能描述                              输出: 生产可用算子 + 用例文档 + 接口文档 + 精度报告 + 性能报告

Anti-Pattern List (NEVER DO THESE)

  • ❌ Do not skip the design phase and write code directly
  • ❌ Do not skip the test case generation phase; after Phase 2 passes, Phase 3 (testcase-gen) must be executed
  • ❌ Do not implement any operator code yourself; you must call the sub-skill
  • ❌ Do not modify framework files (ops.h / register.cpp / CMakeLists.txt) before code generation
  • ❌ Do not manually execute compilation and testing; this is handled uniformly by the compile-debug skill
  • ❌ Do not reference skills that do not exist
  • ❌ Do not skip checkpoint verification
  • ❌ Do not skip the interface documentation phase; after Phase 4 passes, Phase 5 must be executed
  • ❌ Do not skip the accuracy evaluation phase; after Phase 5 passes, Phase 6 must be executed
  • ❌ Do not skip the performance evaluation phase; after Phase 6 passes, Phase 7 must be executed
  • ❌ Do not use non-msprof timing methods as performance conclusions
  • ❌ Do not design test cases yourself for accuracy evaluation and performance evaluation; you must first read the test case document generated by testcase-gen

Phase 0: Requirements Collection

Objective: Confirm the minimum information set required for operator development, including the development environment and operator requirements

Step 0.1: Environment Confirmation (MUST be completed before any development action)

The development environment is a prerequisite dependency for all subsequent phases,must be confirmed first。

CANN Environment

Automatic Detection Process：

  1. Check whether the environment variable ASCEND_HOME_PATH is set (echo $ASCEND_HOME_PATH）
  2. If set: use it directly without asking the user, and use it as CANN_PATH
  3. If not set：MUST ask the user for the CANN installation path (e.g., /usr/local/Ascend/ascend-toolkit）

Activation Method：

source ${CANN_PATH}/*/set_env.sh

In every Shell session that needs to compile or run the operator, this activation command must be executed first.

Conda Environment

Automatic Detection Process：

  1. Check whether a conda environment is currently activated (echo $CONDA_DEFAULT_ENV）
  2. If activated(value is not base and not empty): use the current environment directly without asking the user
  3. If not activated or is base：MUST ask the user for the name of the conda environment to use

Activation Method：

conda activate <env_name>

In every Shell session that needs to compile or run the operator, the conda environment must be activated first.

Environment Confirmation Checkpoint

  • CANN path has been determined (automatically detected or provided by the user)
  • source ${CANN_PATH}/*/set_env.sh can be executed normally
  • Conda environment has been determined (automatically detected or provided by the user)
  • conda activate <env_name> can be executed normally

Step 0.2: Operator Requirements Collection

Information That Must Be Confirmed

Information Format Requirement Required Description
CANN environment path Absolute path Yes Automatically detect $ASCEND_HOME_PATH; if not set, ask the user
Conda environment name String Yes Automatically detect $CONDA_DEFAULT_ENV; if not activated, ask the user
Operator name snake_case Yes e.g., acosh, rms_norm, flash_attn
Function description Text/mathematical formula Yes e.g., "inverse hyperbolic cosine acosh(x) = ln(x + sqrt(x²-1))"

Optional Information(with default values):

Information Default Value Description
Supported data types float16, float32 Extensible bfloat16
SoC platform ascend910b Automatically obtained through the platform API

Decision Tree

User request Handling method
"Generate X operator" / "Develop X operator" First complete environment confirmation (Step 0.1), then infer functionality from the operator name, and after confirmation execute the entire workflow directly
"Help me develop a new operator" (no specific name) First complete environment confirmation (Step 0.1), then ask for the operator name and function description
"Continue operator development" First complete environment confirmation (Step 0.1), then check existing files to determine the stage and continue from the interruption point

Acceptance criteria

  • CANN environment path has been determined and can be activated
  • Conda environment name has been determined and can be activated
  • Operator name has been confirmed (snake_case format)
  • Function description has been clarified (including mathematical formula or computation logic)

Phase 1: Project initialization

Invoke Skill：ascendc-operator-project-init

Execution content

MANDATORY: 按 ascendc-operator-project-init skill 流程执行：
1. 检测 ascend-kernel 项目是否存在
2. 不存在则从模板复制
3. 在 csrc/ops/<op_name>/ 下创建算子骨架
4. 提示三处注册更新点

Checkpoint

  • ascend-kernel project exists (build.sh, CMakeLists.txt, csrc/)
  • csrc/ops/<op_name>/ directory has been created
  • contains op_host/<op_name>.cpp、op_kernel/<op_name>.cpp、CMakeLists.txt、design.md

All pass → proceed to Phase 2

Phase 2: Design document generation

Invoke Skill：ascendc-operator-design

Execution content

MANDATORY: 按 ascendc-operator-design skill 流程执行：
1. 分析算子需求（名称、功能、数据类型）
2. 确定实现路径（AscendC Kernel / CATLASS / ACLNN）
3. 设计 Tiling 策略（Block级 + UB级）
4. 填写 UB 分配表，推导 bufferCoefficient
5. 生成完整设计文档到 csrc/ops/<op_name>/design.md

Checkpoint

  • csrc/ops/<op_name>/design.md content is complete
  • includes function signature and supported data types
  • includes computation logic pseudocode (AscendC API call sequence)
  • includes UB allocation table (listing all buffers and total coefficients)
  • includes bufferCoefficient (values for each dtype)

All pass → proceed to Phase 3

Phase 3: Test case generation

Invoke Skill：ascendc-operator-testcase-gen

Execution content

MANDATORY: 按 ascendc-operator-testcase-gen skill 流程执行：
1. 读取 csrc/ops/<op_name>/design.md，提取参数约束、支持的 dtype、典型 shape
2. 生成 TEST_SHAPES（常规 shape）、GENERAL_SHAPES（泛化 shape）、BOUNDARY_VALUES（边界值）
3. 生成算子标杆（CPU 参考实现、NPU 调用方式）
4. 输出用例文档到 csrc/ops/<op_name>/test/<op_name>-test-cases.md

Checkpoint

  • csrc/ops/<op_name>/test/<op_name>-test-cases.md has been generated
  • includes SUPPORTED_DTYPES, TEST_SHAPES, GENERAL_SHAPES, BOUNDARY_VALUES
  • includes operator benchmark (NPU invocation method + CPU reference implementation)
  • shape and parameter values are within the constraints of design.md

All pass → proceed to Phase 4

Phase 4: Code generation + framework adaptation + compilation test

Invoke Skill：ascendc-operator-code-gen(automatically invokes internally ascendc-operator-compile-debug）

Execution content

MANDATORY: 按 ascendc-operator-code-gen skill 流程执行：

阶段 1: 加载参考文档
  - 读取 references/GUIDE.md
  - 按算子类型加载对应 reference

阶段 2: 读取设计文档
  - 提取函数签名、UB 分配表、计算伪代码

阶段 3: 选择模板并生成代码
  - 选择 elementwise / row 模板
  - 生成 op_host/<op_name>.cpp（含 Tiling 计算逻辑）
  - 生成 op_kernel/<op_name>.cpp（含 Compute 计算逻辑）

阶段 4: 框架适配
  - 更新 csrc/ops.h（函数声明）
  - 更新 csrc/register.cpp（m.def + m.impl）
  - 更新 csrc/CMakeLists.txt（OP_SRCS + ascendc_library）

阶段 5: 编译安装与测试（调用 compile-debug skill）
  - ./build.sh 编译
  - pip install whl 安装
  - 生成 tests/test_<op_name>.py
  - 运行功能测试和精度测试
  - 编译/测试失败最多排错 3 次

Checkpoint

  • op_host/<op_name>.cpp uses platform API to obtain hardware parameters
  • op_kernel/<op_name>.cpp includes the complete CopyIn → Compute → CopyOut pipeline
  • ops.h function declaration has been added
  • register.cpp has been added m.def and m.impl
  • csrc/CMakeLists.txt host and kernel source files have been added
  • compilation succeeded (whl package has been generated)
  • functional test passed (exit code 0)
  • precision tests all passed (pytest all green)

All pass → proceed to Phase 5

Phase 5: Interface document generation

Invoke Skill：ascendc-operator-doc-gen

Execution content

MANDATORY: 按 ascendc-operator-doc-gen skill 流程执行：

阶段 1: 信息提取
  - 从 register.cpp 提取 Python 调用签名（m.def schema）
  - 从 ops.h 提取 C++ 函数声明和返回类型
  - 从 design.md 提取算法描述、参数说明、dtype 支持、约束条件
  - 从 op_host 提取 TORCH_CHECK 约束
  - 从 tests/test_<op_name>.py 提取使用示例

阶段 2: 文档结构组装
  - 按 PyTorch 官方文档风格组装中文接口文档
  - 包含：标题签名 + 功能描述 + 参数说明 + 支持的数据类型 + Shape + 约束条件 + 使用示例 + 返回值

阶段 3: 文件生成
  - 生成 csrc/ops/<op_name>/README.md

阶段 4: 在交互界面展示完整文档内容

Checkpoint

  • complete interface information has been extracted from the source code (signature, parameters, dtype, shape, constraints)
  • README.md includes the complete 7 sections (title signature + function description + parameter description + supported data types + Shape + constraints + usage example + return value)
  • Python call signature matches register.cpp of m.def consistently
  • parameter description uses PyTorch documentation style, description uses Chinese
  • The code in the usage example runs
  • README.md has been written csrc/ops/<op_name>/README.md
  • API documentation has been fully displayed in the chat interface

All passed → Proceed to Phase 6

Phase 6: Accuracy Evaluation Report

Invoke Skill：ascendc-operator-precision-eval

Execution Content

MANDATORY: 按 ascendc-operator-precision-eval skill 流程执行：

阶段 1: 加载用例文档 + 信息收集
  - 读取 csrc/ops/<op_name>/test/<op_name>-test-cases.md（testcase-gen 产出）
  - 提取 SUPPORTED_DTYPES、TEST_SHAPES、GENERAL_SHAPES、BOUNDARY_VALUES、算子标杆
  - 从已有代码补充提取精度阈值等信息

阶段 2: 用例适配（(shapes + boundary) × dtypes ≥ 30 例）
  - 直接复用 testcase-gen 的 TEST_SHAPES 和 BOUNDARY_VALUES
  - 每个 shape / 边界值遍历算子支持的全部 dtype

阶段 3: 测试脚本生成（输出到算子目录 csrc/ops/<op_name>/test/）
  - 基于模板生成 test_<op_name>_precision.py（pytest 格式）
  - 基于模板生成 run_<op_name>_precision_report.py（报告生成器）

阶段 4: 执行
  - 运行 pytest 全部通过
  - 运行报告生成器输出 JSON

阶段 5: 报告生成
  - 生成 <op_name>_precision_report.md（含常规 shape + 边界值表格 + 汇总 + 关键发现）
  - 向用户提示报告路径

Checkpoints

  • Number of test cases = (shapes + boundary) × dtypes ≥ 30
  • Every dtype supported by the operator has been tested
  • All pytest accuracy tests pass
  • JSON report generated (including 5 accuracy metrics: MaxAbsErr / MeanAbsErr / MaxRelErr / MeanRelErr / CosineSim)
  • Markdown report generated at csrc/ops/<op_name>/test/<op_name>_precision_report.md
  • Accuracy test results have been displayed as a Markdown table in the chat interface
  • The user has been notified of the accuracy report path

All passed → Proceed to Phase 7

Phase 7: Performance Evaluation Report

Invoke Skill：ascendc-operator-performance-eval

Execution Content

MANDATORY: 按 ascendc-operator-performance-eval skill 流程执行：

阶段 1: 加载用例文档 + 信息收集
  - 读取 csrc/ops/<op_name>/test/<op_name>-test-cases.md（testcase-gen 产出）
  - 提取 SUPPORTED_DTYPES、TEST_SHAPES、GENERAL_SHAPES、算子标杆
  - 从已有代码补充提取 OP Type 关键字等信息

阶段 2: 用例适配（JSONL 格式，≥8 case）
  - 从 testcase-gen 的 TEST_SHAPES + GENERAL_SHAPES 中选取代表性 shape
  - 覆盖算子支持的全部 dtype
  - 转换为 JSONL 格式

阶段 3: 脚本生成（输出到算子目录 csrc/ops/<op_name>/test/）
  - 基于模板生成 run_<op_name>_case.py（单 case msprof 执行器）
  - 基于模板生成 benchmark_<op_name>_msprof.py（总控脚本）
  - 生成 <op_name>_cases.jsonl

阶段 4: 执行采集
  - 运行总控脚本，每 case 20 次迭代（前 10 次预热）
  - 按 OP Type 从 op_summary_*.csv 提取 Task Duration(us) 和硬件指标
  - 输出 JSON 结果

阶段 5: 报告生成
  - 生成 <op_name>_perf_report.md（含结果表格 + 汇总 + 简短分析）
  - 向用户提示报告路径

Checkpoints

  • JSONL test cases cover multiple shapes × dtypes (≥ 8 cases)
  • Use msprof for collection, not other timing methods
  • Filter by OP Type to target the operator (not Op Name)
  • 20/10 warmup/measurement strategy
  • JSON report generated (including Task Duration + hardware metrics)
  • Markdown report generated at csrc/ops/<op_name>/test/<op_name>_perf_report.md
  • The report includes a brief analysis (≥ 3 conclusions)
  • Performance test results have been displayed as a Markdown table in the chat interface
  • The user has been notified of the performance report path

All passed → Operator development complete

Inter-phase Data Flow

Phase 1 输出                    Phase 2 输入
  csrc/ops/<op_name>/    ────▶    算子名称、目录结构
  design.md (占位)

Phase 2 输出                    Phase 3 输入
  design.md (完整)       ────▶    参数约束、支持的 dtype、典型 shape
                                  → 生成统一测试用例文档

Phase 3 输出                    Phase 4 输入
  <op_name>-test-cases.md ────▶    design.md (完整)
  （用例文档，供后续复用）          函数签名、UB 分配表 → bufferCoefficient
                                  计算伪代码 → Compute 逻辑
                                  Tiling 策略 → Block/UB 切分参数

Phase 4 输出                    Phase 5 输入
  已安装的算子 whl        ────▶    register.cpp / ops.h / design.md /
  tests/test_<op_name>.py        op_host / test 文件
                                  → 提取接口信息生成文档

Phase 5 输出                    Phase 6 输入
  csrc/ops/<op>/README.md ────▶    <op_name>-test-cases.md（来自 Phase 3）
  接口文档完成                     算子名、调用方式、输入域约束
                                  支持的全部 dtype、精度阈值
                                  → 输出到 csrc/ops/<op_name>/test/

Phase 6 输出                    Phase 7 输入
  精度报告通过             ────▶    <op_name>-test-cases.md（来自 Phase 3）
  csrc/ops/<op>/test/            算子名、工程/原生调用方式
                                  支持的全部 dtype、OP Type 关键字
                                  → 输出到 csrc/ops/<op_name>/test/

Status Tracking Table

Phase Prerequisites Invoke Skill Key Deliverables
0. Requirements Collection None — CANN path + Conda environment + operator name + function description
1. Project Initialization Phase 0 ascendc-operator-project-init Operator skeleton directory
2. Design Document Phase 1 ascendc-operator-design design.md (including Tiling + UB allocation table)
3. Test Case Generation Phase 2 ascendc-operator-testcase-gen <op_name>-test-cases.md(Unified test case document)
4. Code & Testing Phase 3 ascendc-operator-code-gen → compile-debug Runnable operator + basic tests passed
5. API Documentation Phase 4 ascendc-operator-doc-gen PyTorch-style Chinese API documentation (README.md)
6. Accuracy Evaluation Phase 5 ascendc-operator-precision-eval ≥30 accuracy test cases + accuracy report
7. Performance Evaluation Phase 6 ascendc-operator-performance-eval msprof performance comparison + performance report

Error Recovery

Resume from Breakpoint

When the user says "continue operator development":

Detection Condition Determined Phase Recovery Action
csrc/ops/<op_name>/ does not exist Phase 1 not completed Start from Phase 1
design.md is a placeholder or empty Phase 2 not completed Start from Phase 2
csrc/ops/<op_name>/test/<op_name>-test-cases.md does not exist Phase 3 not completed Start from Phase 3
op_host/ is still skeleton code Phase 4 not completed Start from Phase 4
whl not generated Phase 4 compilation not completed Resume from compilation step
Basic tests not passed Phase 4 testing not completed Resume from testing step
csrc/ops/<op_name>/README.md does not exist Phase 5 not completed Start from Phase 5
csrc/ops/<op_name>/test/ no precision report Phase 6 not started Start from Phase 6
Precision report does not exist or precision tests not all passed Phase 6 not completed Resume from Phase 6
Precision report exists but performance report does not exist Phase 7 not started Start from Phase 7
<op_name>_perf_report.md does not exist or is incomplete Phase 7 not completed Resume from Phase 7

Compilation/testing failed

Handled internally by ascendc-operator-compile-debug skill, with a maximum of 3 troubleshooting attempts. If it still fails after 3 attempts, stop and report the detailed error to the user.