SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsexternal-gitcode-ascend-catlass-operator-dev

external-gitcode-ascend-catlass-operator-dev

Design & creation

View repository

Updated 10-15 17:19

About this skill

Catlass operator end-to-end development orchestration

Skill type: process-oriented (six-phase workflow;Catlass source preparationmerged into Phase 1, sub-skills orchestrated serially)

This skill orchestrates Catlass operators on ascend-kernel from scratch to production-ready;general capabilities(engineering skeleton, compilation and debugging, interface documentation, accuracy, performance)reuse ascendc-* sub-skills,Catlass-specific(source tree, design, Device/Host implementation) use catlass-* sub-skills.

Core principles

  1. Six-phase serial: project initialization (including Catlass source) → design document → code generation and compilation testing → interface documentation → accuracy evaluation → performance evaluation, executed in strict order
  2. Sub-skill execution: each phase MUST open and follow the corresponding sub-skill; do not substitute your own implementation
  3. Phase gating: proceed to the next phase only after all checkpoints of the previous phase have passed
  4. Design-driven coding: code generation depends on catlass-operator-design the finalized design.md and catlass/examples selection
  5. No need for the user to hand-write the design document in advance: the design phase is handled by catlass-operator-design generate and write to disk
  6. Documentation closed loop: after compilation and testing pass, MUST generate PyTorch-style Chinese interface documentation (Phase 4), and display it in the chat interface
  7. Accuracy closed loop: the operator must pass ≥30 comprehensive accuracy evaluation on all cases (Phase 5) to be considered complete
  8. Performance closed loop: the operator must complete torch_npu.profiler comparative evaluation and output a performance report (Phase 6); the conclusion is based on ascendc-operator-performance-eval as authoritative
  9. Result visualization: key results of Phase 3/4/5/6 MUST are displayed directly in the chat interface in Markdown and other forms; do not output only paths
  10. Operator naming：op_name（snake_case）mustcontain the substring catlass, consistent with the conventions of existing Catlass operators in ascend-kernel
  11. Honest shutdown: when unable to continue due to environment or dependencies, explain the specific reason and the steps already completed, then stop

Catlass compilation and running (error-prone summary)

  • Build：BUILD_CATLASS_MODULE=ON; CMake uses a Python containing torch_npu (e.g. -DPYTHON_EXECUTABLE / ASCEND_BUILD_PYTHON）；CATLASS_ARCH consistent with the chip (see catlass-operator-code-gen/references/compile-catlass.md); CANN can be bundle root + cann-*/set_env.sh。
  • pytest / torch_npu: if it reports ASCEND_RUNTIME_PATH：export ASCEND_RUNTIME_PATH="${ASCEND_TOOLKIT_HOME}/runtime"。
  • Design/code: consistent with catlass/include、catlass/examples examples that can be aligned and compiled, see details in compile-catlass.md。

List of available sub-skills

Skill Path Responsibility
ascendc-operator-project-init ascendc-operator-project-init/SKILL.md Detect/create ascend-kernel, in csrc/ops/<op_name>/ generate operator skeleton
— (step within Phase 1) in ASCEND_KERNEL_ROOT clone catlass/(same level as csrc/ ), so that include/、examples/ is available
catlass-operator-design catlass-operator-design/SKILL.md Convert Catlass requirements into a finalized design document (recommended csrc/ops/<op_name>/design.md）
catlass-operator-code-gen catlass-operator-code-gen/SKILL.md According to design.md and catlass/examples implement op_host / op_kernel, framework adaptation, andinternal callcompile & test skill
ascendc-operator-compile-debug ascendc-operator-compile-debug/SKILL.md Compile, install whl, generate/run tests/test_<op_name>.py(called by catlass-operator-code-gen phase 5; do not skip code-gen and directly claim completion)
ascendc-operator-doc-gen ascendc-operator-doc-gen/SKILL.md Generate PyTorch-style Chinese API documentation README.md(mandatory phase)
ascendc-operator-precision-eval ascendc-operator-precision-eval/SKILL.md ≥30 precision test cases and precision verification report (mandatory phase)
ascendc-operator-performance-eval ascendc-operator-performance-eval/SKILL.md JSONL cases + torch_npu.profiler（warmup/active=5）+ op_statistic.csv summary, output custom vs benchmark Markdown report (mandatory phase)
catlass-operator-performance-optim catlass-operator-performance-optim/SKILL.md Optional after delivery: perform tiling/performance iteration per Catlass documentation; after code changes, must return to Phase 3 and re-run the closed loop

Engineering directory terminology (aligned with AscendC)

Term Meaning
ASCEND_KERNEL_ROOT ascend-kernel root directory: contains build.sh、CMakeLists.txt、csrc/
operator directory <ASCEND_KERNEL_ROOT>/csrc/ops/<op_name>/
Catlass source code <ASCEND_KERNEL_ROOT>/catlass/（Forbiddenin csrc/ops/<op>/ cloning inside)

Workflow overview

┌─────────────────────────────┐   ┌──────────────┐   ┌───────────────────────────┐   ┌──────────────────┐   ┌──────────────────┐   ┌──────────────────┐
│  Phase 1                    │   │  Phase 2     │   │  Phase 3                  │   │  Phase 4         │   │  Phase 5         │   │  Phase 6         │
│  工程初始化 + Catlass 源码   │──▶│  Catlass 设计 │──▶│  代码生成+框架适配+编译测试 │──▶│  接口文档生成     │──▶│  精度评估报告     │──▶│  性能评测报告     │
│  project-init + clone      │   │  catlass-    │   │  catlass-code-gen →       │   │  doc-gen         │   │  precision-eval  │   │  performance-eval│
│  catlass                   │   │  design      │   │  compile-debug            │   │                  │   │                  │   │  (profiler)      │
└─────────────────────────────┘   └──────────────┘   └───────────────────────────┘   └──────────────────┘   └──────────────────┘   └──────────────────┘

输入: 算子名(含 catlass) + 功能描述 + 环境确认          输出: 可交付算子 + README + 精度报告 + profiler 性能报告

Anti-pattern checklist (NEVER DO THESE)

  • ❌ Do not skip Catlass source code preparation(without catlass/include、catlass/examples doing design or code generation)
  • ❌ Do not clone Catlass inside csrc/ops/<op_name>/ ; it must be under the engineering root under catlass/
  • ❌ Do not skip the design phase and directly write kernel/host
  • ❌ Do not implement the entire operator delivery by yourself without following the catlass-operator-code-gen process
  • ❌ Do not modify framework registration without authorization before code generation (follow project-init / code-gen conventions)
  • ❌ Do not manually replace the compile-install and basic test closed loop handled by compile-debug (it should be triggered through code-gen phase 5)
  • ❌ Do not skip the interface documentation phase (after Phase 3 passes, Phase 4 is mandatory)
  • ❌ Do not skip the precision evaluation phase (after Phase 4 passes, Phase 5 is mandatory)
  • ❌ Do not skip the performance evaluation phase (after Phase 5 passes, Phase 6 is mandatory)
  • ❌ Do not use a collection method inconsistent with ascendc-operator-performance-eval as the final performance conclusion
  • ❌ Do not reference non-existent skills

Phase 0: Requirements collection

Goal: confirm the minimum information set and runtime environment for Catlass operator development (aligned with ascendc-operator-dev Phase 0, with Catlass naming constraints added).

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

CANN environment

  1. Check ASCEND_HOME_PATH（echo $ASCEND_HOME_PATH）
  2. is set: as CANN_PATH, no need to ask again
  3. is not set：MUST ask the user for the CANN path (e.g. /usr/local/Ascend/ascend-toolkit）
source ${CANN_PATH}/*/set_env.sh

Conda environment

  1. Check CONDA_DEFAULT_ENV
  2. is activated and is not base: use directly
  3. not activated or is base：MUST ask for the conda environment name
conda activate <env_name>

Environment confirmation checkpoint

  • CANN path is determined and set_env.sh is executable
  • Conda environment is determined and can be activated

Step 0.2: Operator requirements collection

Information Format requirement Required Description
CANN path Absolute path Yes Same as ascendc, can be auto-detected
Conda environment String Yes Same as ascendc, can be auto-detected
Operator name snake_case，Contains catlass Yes Such as catlass_matmul_basic
Function description Text/formula/benchmark example Yes Consistent with the Catlass capability scope

Optional: Supports dtype, SoC — default values being consistent with catlass-operator-design / platform API is sufficient.

Decision tree

User request Handling method
"Develop/generate a certain Catlass operator" Complete Step 0.1 → verify the name contains catlass → confirm the function → execute the full process
"Continue Catlass operator development" Complete Step 0.1 → follow error recovery to detect the current phase and continue running

Acceptance criteria

  • CANN + Conda confirmed
  • op_name Confirmed and contains catlass
  • Function description clear

Phase 1: Project initialization + Catlass source preparation

Step 1.1: Project skeleton

Call Skill：ascendc-operator-project-init

MANDATORY: 按 ascendc-operator-project-init 执行：
1. 检测或创建 ascend-kernel
2. 在 csrc/ops/<op_name>/ 创建算子骨架
3. 提示注册更新点（后续由 catlass-operator-code-gen 落实）

Checkpoint (Step 1.1)

  • ASCEND_KERNEL_ROOT Contains build.sh、CMakeLists.txt、csrc/
  • csrc/ops/<op_name>/ Created, containing placeholder design.md、op_host/、op_kernel/、CMakeLists.txt etc. (subject to that skill)

Step 1.2: Catlass source

This step does not correspond to an independent skill file, but must be executed according to the following requirements.

Prerequisite: Step 1.1 completed

Execution content

  1. Under ASCEND_KERNEL_ROOT , ensure that catlass/exists, and contains catlass/include、catlass/examples
  2. If it does not exist:MUST execute in the project root (Prohibitedto clone inside csrc/ops/<op_name>/ )
    git clone https://gitcode.com/cann/catlass.git catlass

Checkpoint (Step 1.2)

  • <ASCEND_KERNEL_ROOT>/catlass/include exists
  • <ASCEND_KERNEL_ROOT>/catlass/examples exists

All of Phase 1 passed → enter Phase 2

Phase 2: Catlass design document

Call Skill：catlass-operator-design

Execution content

MANDATORY: 按 catlass-operator-design 执行：
1. 分析需求与 Catlass 组件边界
2. 对齐 catlass/examples 与 catlass/include 的可实现路径
3. 定稿并落盘推荐路径：csrc/ops/<op_name>/design.md（与 doc-gen / precision-eval / performance-eval 读取一致）

Checkpoint

  • csrc/ops/<op_name>/design.md Finalized (not empty placeholder)
  • Clearly state the reference example path, Kernel/Host contract, dtype/shape constraints, etc. (subject to catlass-operator-design)

All passed → enter Phase 3

Phase 3: Code generation + framework adaptation + compilation test

Call Skill：catlass-operator-code-gen(Phase 5 MUST call ascendc-operator-compile-debug）

Execution content

MANDATORY: 按 catlass-operator-code-gen 执行（与 ascendc-operator-code-gen 阶段结构对齐）：

阶段 1: 加载 GUIDE / references（含 compile-catlass、与 ascendc code-gen 对齐章节）
阶段 2: 读取 design.md，锁定 catlass/examples 路径与类型系统
阶段 3: 生成 op_kernel + op_host，CMake 登记 Catlass 编译选项（BUILD_CATLASS_MODULE、CATLASS_ARCH 等见 compile-catlass.md）
阶段 4: 框架适配 — ops.h、register.cpp、csrc/CMakeLists.txt
阶段 5: 编译安装与测试 — 调用 ascendc-operator-compile-debug（build.sh、pip install、tests/test_<op_name>.py，失败排错以该 skill 为准）

Checkpoint

  • op_host、op_kernel Consistent with design.mdand the selected example
  • Framework registration consistent with the repository template (namespace ascend_kernel etc.)
  • Compilation succeeded, whl can be installed
  • tests/test_<op_name>.py Exists and passed (exit code 0)
  • Key compilation/test results are summarized and displayed in the chat

All passed → enter Phase 4

Phase 4: Interface document generation

Call Skill：ascendc-operator-doc-gen

Execution Content

MANDATORY: 按 ascendc-operator-doc-gen 执行：
- 从 register.cpp、ops.h、design.md、op_host、tests 提取接口信息
- 生成 csrc/ops/<op_name>/README.md（PyTorch 风格中文）
- 在聊天界面展示文档要点或全文

Checkpoints

  • README.md written to operator directory
  • and m.def / matches actual Python invocation
  • displayed in chat interface

All passed → enter Phase 5

Phase 5: Accuracy Evaluation Report

Invoke Skill：ascendc-operator-precision-eval

Execution Content

MANDATORY: 按 ascendc-operator-precision-eval 执行：
- 用例数 ≥ 30，覆盖 shapes × dtypes × 边界
- 输出到 csrc/ops/<op_name>/test/，生成 Markdown 精度报告
- 在聊天界面展示总览、失败摘要与关键发现（不得仅给路径）

Checkpoints

  • All pytest accuracy cases passed
  • <op_name>_precision_report.md(or the report name specified by the skill) has been generated
  • accuracy result summary displayed in chat

FAIL closed loop: root cause analysis → fix design (Phase 2) or code (Phase 3) → re-test via Phase 4, Phase 5

All passed → enter Phase 6

Phase 6: Performance Evaluation Report

Invoke Skill：ascendc-operator-performance-eval

Execution Content

MANDATORY: 以 ascendc-operator-performance-eval SKILL.md 为唯一细则：
- 在 csrc/ops/<op_name>/test/ 维护 JSONL 用例；生成前先读 design.md
- 使用 torch_npu.profiler，warmup=5、active=5
- 汇总 ASCEND_PROFILER_OUTPUT/op_statistic.csv 等指标，输出自定义算子 vs 标杆的 Markdown 报告
- 在聊天界面展示对比表与简要结论

Checkpoints

  • cases and report format conform to the skill (including DType, dual-path comparison, etc.)
  • report file has been written to operator test/ directory
  • performance summary displayed in chat

All passed → Catlass operator main flow complete

Optional after delivery: performance optimization

Invoke Skill：catlass-operator-performance-optim

Must ask the userwhether to proceed with tuning;must notskip the inquiry by default.

  • User agrees → modify tiling/implementation per catlass-operator-performance-optim ;any code change → re-run from Phase 3 (Phase 3→4→5→6) until it meets the standard again
  • User declines → end

Inter-phase data flow

Phase 1 输出                         Phase 2 输入
  ascend-kernel + ops/<op>/骨架       算子名、catlass/ 可引用
  + catlass/include、examples   ────▶

Phase 2 输出                         Phase 3 输入
  design.md（定稿）            ────▶  example 路径、类型与 Host 契约

Phase 3 输出                         Phase 4 输入
  已安装 whl + test_<op>.py     ────▶  register.cpp / ops.h / design.md / op_host

Phase 4 输出                         Phase 5 输入
  README.md                    ────▶  接口、dtype、约束、调用方式

Phase 5 输出                         Phase 6 输入
  精度通过 + 报告                ────▶  算子名、标杆 API、JSONL 与 profiler 流程

Phase 6 输出
  性能报告（profiler）           ────▶  可选：用户确认后进入 catlass-operator-performance-optim

Status tracking table

Phase Preconditions Invoke Skill / Action Key Deliverables
0. Requirements collection None — CANN + Conda + op_name(including catlass) + functional description
1. Project + Catlass Phase 0 ascendc-operator-project-init + root directory catlass/ skeleton + Catlass source tree
2. Design Phase 1 catlass-operator-design design.md
3. Code and testing Phase 2 catlass-operator-code-gen → compile-debug Runnable operator + basic tests passed
4. Interface documentation Phase 3 ascendc-operator-doc-gen README.md
5. Accuracy evaluation Phase 4 ascendc-operator-precision-eval ≥30 cases + accuracy report
6. Performance evaluation Phase 5 ascendc-operator-performance-eval JSONL + profiler report
(Optional) tuning Phase 6 + user confirmation catlass-operator-performance-optim Iterated implementation and report

Error recovery

Resume from interruption point

When the user says "continue Catlass operator development":

Detection condition Determined phase Recovery action
csrc/ops/<op_name>/ does not exist Phase 1 not completed Start from Phase 1 Step 1.1
catlass/examples does not exist Phase 1 not completed Complete Step 1.2 clone
design.md is empty or placeholder Phase 2 not completed Start from Phase 2
op_host/op_kernel is still skeleton or does not match design Phase 3 not completed Start from Phase 3
whl not installed or tests/test_<op_name>.py Failed Phase 3 not completed Resume within the compile-debug flow
None README.md Phase 4 not completed Start from Phase 4
test/ No accuracy report or accuracy not fully passed Phase 5 not completed Resume from Phase 5
No performance report or does not meet performance-eval requirements Phase 6 not completed Resume from Phase 6

Compilation/test failed

By ascendc-operator-compile-debug(via catlass-operator-code-gen triggered) processing; retry and troubleshooting limits are subject to the compile-debug skill.