ascendc
End-to-end AscendC custom operator development for Ascend NPU in an ascend-kernel (csrc/ops + build.sh + torch_npu PyTorch custom op) project. Use to design, generate, build, test, document, and tune a new AscendC operator from a name and a math/functional spec. Covers project init, two-level tiling design, op_host/op_kernel code generation, framework registration, compile/install/debug, PyTorch-style API docs, precision evaluation and root-cause debugging, torch_npu.profiler performance benchmarking, performance optimization, and security code review.
How do I install this agent skill?
npx skills add https://github.com/ascend-ai-coding/awesome-ascend-skills --skill ascendcIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a structured environment for developing, building, and benchmarking custom AscendC operators on Huawei Ascend NPUs. It utilizes standard development tools like CMake, shell scripts, and PyTorch extensions. No malicious behaviors, obfuscation, or data exfiltration patterns were detected.
- Socketwarn
3 alerts: gptAnomaly
- Snykpass
Risk: LOW · No issues
- Runlayerpass
5 files scanned · No issues
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
AscendC Operator Development (All-in-One)
This skill drives a new AscendC custom operator from a spec to a production-ready,
benchmarked operator inside an ascend-kernel project (a PyTorch custom-op project
that exposes operators as torch.ops.npu.<op> via csrc/ops/, csrc/register.cpp,
and build.sh). It is self-contained: every phase, template, and reference lives
under this skill directory.
Scope note: this skill targets the ascend-kernel /
csrc/opsPyTorch custom-op workflow (vector / row / index / sort / pool operators, FP16/BF16 up-cast, two-level tiling). It is not for theops-transformeraclnn/genop flow.
How to use this skill
- Read this
SKILL.mdfully first (lifecycle, gates, anti-patterns). - For each phase, MUST open the matching
references/NN-*.mdbefore acting. - Reuse the bundled
templates/,examples/, andscripts/; do not invent project structure or APIs. - Honor the stage gates: never start a phase until the previous phase's checklist passes. Never skip the in-chat result display rules.
When to use
- "Develop / implement / create a new AscendC operator
<name>" (e.g.acosh,rms_norm). - "Continue operator development" → detect the current phase from artifacts and resume.
- Any single phase on an existing operator: design only, code-gen only, precision eval only, performance benchmark only, optimization only, or code review only.
Lifecycle overview
Phase 0 Environment + requirements
Phase 1 Project init -> references/01-project-init.md
Phase 2 Design (design.md) -> references/02-design.md
Phase 3 Test cases -> references/03-testcase-gen.md
Phase 4 Code generation -> references/04-code-gen.md (+ 04a-kernel-api.md)
Phase 5 Compile / debug -> references/05-compile-debug.md
Phase 6 Interface docs -> references/06-doc-gen.md
Phase 7 Precision eval -> references/07-precision-eval.md (fail -> 07b-precision-debug.md)
Phase 8 Performance eval -> references/08-performance-eval.md
Phase 9 Performance optim -> references/09-performance-optim.md
Phase 10 Code review -> references/10-code-review.md
(opt) Memory check -> references/11-mssanitizer.md
Input: operator name (snake_case) + functional/math spec.
Output: built & installed operator, design.md, unified test-case doc, PyTorch-style
README, precision report, performance report (and optimization/review reports if run).
Phase 0 — Environment and requirements
Confirm the build/run environment before any development action.
- CANN:
echo $ASCEND_HOME_PATH. If set, use it asCANN_PATH. If unset, MUST ask the user for the CANN install path. Activate per shell withsource ${CANN_PATH}/*/set_env.sh. - Conda:
echo $CONDA_DEFAULT_ENV. If non-empty and notbase, use it. Otherwise MUST ask the user for the conda env name; activate withconda activate <env>. - Requirements: operator name (snake_case, required), functional spec / math formula
(required), supported dtypes (optional, default
float16, float32, may addbfloat16), SoC (optional, defaultascend910b, obtained via platform API at runtime).
Details and the decision tree: references/00-environment.md.
Gate: CANN path resolved and activatable; conda env resolved and activatable; operator name and functional spec confirmed.
Phase 1 — Project init
Locate or create the ascend-kernel project, then scaffold csrc/ops/<op>/.
- Detect with
scripts/detect_ascend_kernel_project.sh. If none, copy the bundled templatetemplates/ascend-kernel/andchmod +x build.sh. - Create
csrc/ops/<op>/{op_host/<op>.cpp, op_kernel/<op>.cpp, CMakeLists.txt, design.md}(placeholders). - Flag the three registration update points for later phases:
csrc/ops.h,csrc/register.cpp,csrc/CMakeLists.txt.
Read references/01-project-init.md.
Gate: project exists (build.sh, CMakeLists.txt, csrc/); csrc/ops/<op>/ skeleton
created with the four files.
Phase 2 — Design (design.md)
Produce a complete design document; it is the direct input for code generation.
- Pick an implementation path (default AscendC Kernel; CATLASS only for matmul/cube).
- Map the math to an AscendC API call sequence; design two-level tiling (block-level
inter-core + UB-level intra-core); fill the UB allocation table and derive
bufferCoefficientper dtype; describe the FP16/BF16 → FP32 up-cast path. - Fill
templates/design-template.md→ write tocsrc/ops/<op>/design.md.
Read references/02-design.md (tiling-by-op-type, UB allocation, API map, hardware constraints).
Gate: design.md has function signature, supported dtypes, API pseudocode, UB allocation
table with bufferCoefficient per dtype, tiling struct, and up-cast path.
Phase 3 — Test cases
Generate one unified test-case document reused by precision and performance later.
- Read
design.md; produceSUPPORTED_DTYPES,TEST_SHAPES,GENERAL_SHAPES,BOUNDARY_VALUES, and the operator baseline (CPU reference + NPU call). - Total cases
(TEST_SHAPES + GENERAL_SHAPES) x SUPPORTED_DTYPES >= 30; keep single-shape element count reasonable (<= ~200K for regular cases). - Fill
templates/test-cases-template.md→ writecsrc/ops/<op>/test/<op>-test-cases.md.
Read references/03-testcase-gen.md.
Gate: test-case doc exists with dtypes, shapes, boundary values, and baseline; values
respect design.md constraints.
Phase 4 — Code generation + framework adaptation
Generate op_host and op_kernel, then wire them into the framework.
- Select a template pair from
templates/code-gen/by operator type (elementwise / row / index / index-per-elem / sort / pool); copy intocsrc/ops/<op>/and adapt. - op_host: signature, input checks, platform API for
coreNum/ubSize(never hardcode),bufferCoefficient, left-valueEXEC_KERNEL_CMDargs. - op_kernel:
BUFFER_NUM=2, Init core offsets,InitBuffersizes, Compute logic, tail-tile alignment, FP16/BF16 up-cast to FP32,DataCopyPadfor GM↔UB, backup before Reduce. - Framework: add declaration to
csrc/ops.h,m.def+m.impltocsrc/register.cpp, host+kernel sources tocsrc/CMakeLists.txt.
Read references/04-code-gen.md and the API essentials in references/04a-kernel-api.md.
Gate: both sources generated; three registration points updated; checklist in the reference satisfied.
Phase 5 — Compile, install, test, debug
Build the project, install the wheel, generate a basic test, run it, and debug.
chmod +x build.sh && bash build.sh; confirmoutput/ascend_kernel*.whl.pip install output/ascend_kernel*.whl --force-reinstall --no-deps.- Generate
tests/test_<op>.py; run functional test (python ...) then precision test (pytest -v). Source the environment before every shell command. - On failure, run the debug loop (max 3 attempts) using the error decision trees.
Read references/05-compile-debug.md.
Gate: wheel built and installed; functional test exits 0; precision pytest green.
Phase 6 — Interface docs
Extract interface facts from source and emit a PyTorch-style README.
- Pull schema from
register.cpp(m.def), C++ signature fromops.h, algorithm/dtype/ constraints fromdesign.md,TORCH_CHECKfrom op_host, example from the test file. - Assemble the fixed sections and write
csrc/ops/<op>/README.md. Default language is English; switch to Chinese on request. - MUST display the full README content in chat, not just the path.
Read references/06-doc-gen.md.
Gate: README has signature, params, dtypes, shape, constraints, example, returns; matches
register.cpp schema; displayed in chat.
Phase 7 — Precision evaluation
Run a comprehensive precision suite and produce a report.
- Load the Phase 3 test-case doc; adapt
(shapes + boundary) x dtypes >= 30. - Generate
test_<op>_precision.pyandrun_<op>_precision_report.pyfromtemplates/precision/; run pytest then the report generator. - Pass rule (MERE/MARE, ecosystem open-source standard):
MERE < ThresholdandMARE < 10 x Threshold. Standards table in references/07a-precision-standards.md. - On precision failure that thresholds cannot fix, run root-cause debugging per references/07b-precision-debug.md.
- MUST display in chat: overview (totals + pass rate), any failures, and >=3 key findings — then the report path.
Read references/07-precision-eval.md.
Gate: pytest green; JSON + Markdown report written; results displayed in chat.
Phase 8 — Performance evaluation
Benchmark the custom operator against a baseline with torch_npu.profiler.
- Build a JSONL case file (
>= 8cases) from the test-case doc +design.md; always run a dual-path comparison (custom vs baseline; baseline must run on NPU — use a small-op composition when no equivalent API exists). - Fixed schedule
warmup=5, active=5; aggregateTotal Time(us)fromASCEND_PROFILER_OUTPUT/op_statistic.csv. Copyexamples/layer_norm_profiler_reference/as the starting point. - MUST display in chat: the unified comparison table (with DType column), the summary, and >=3 short conclusions — then the report path.
Read references/08-performance-eval.md, references/08a-profiler-and-metrics.md, and references/08b-perf-case-jsonl.md.
Gate: dual-path report written; displayed in chat with table + summary + conclusions.
Phase 9 — Performance optimization (optional, closed loop)
Investigate, modify, and verify — at most 3 rounds.
- Investigate across 5 dimensions (tiling, data copy, API usage, memory, pipeline) and emit a ranked report; snapshot a baseline.
- Apply changes obeying the anti-pattern list; re-run precision (must pass) then the same performance cases; compare to baseline; iterate.
Read references/09-performance-optim.md.
Gate: precision still passes; performance compared to baseline; results displayed in chat.
Phase 10 — Code review (optional)
Hypothesis-testing security review against the coding red lines (numeric, memory/pointer, resource, input validation, concurrency, operator interface, ABI compatibility).
Read references/10-code-review.md.
Optional — Memory check
Run mssanitizer to detect illegal access / leaks / UB out-of-bounds. Read references/11-mssanitizer.md.
Unified anti-patterns (NEVER)
- NEVER skip design and write code directly; code-gen consumes
design.md. - NEVER let FP16/BF16 go through complex math directly — up-cast to FP32 first.
- NEVER use
DataCopyfor GM↔UB — useDataCopyPad. - NEVER pass r-values (temporaries/literals/expressions) into
EXEC_KERNEL_CMD. - NEVER hardcode core count or UB size — query the platform API.
- NEVER modify files under
cmake/orcsrc/utils/. - NEVER reuse a source tensor right after
ReduceSum/ReduceMax(reduction may modify it). - NEVER use
std::min/max/abs/sqrt/expetc. inside a kernel. - NEVER pass
repeatTime > 255to high-dim split APIs (silent uint8 truncation). - NEVER use a non-profiler timing method as a performance conclusion.
- NEVER report only a file path for precision/performance/optimization — show the tables and conclusions in chat.
Resume from interruption
| Detected state | Phase not done | Resume at |
|---|---|---|
csrc/ops/<op>/ missing | 1 | Phase 1 |
design.md placeholder/empty | 2 | Phase 2 |
<op>-test-cases.md missing | 3 | Phase 3 |
| op_host still skeleton | 4 | Phase 4 |
| wheel not built / basic test failing | 5 | Phase 5 |
README.md missing | 6 | Phase 6 |
| no precision report / precision failing | 7 | Phase 7 |
| precision report present, no perf report | 8 | Phase 8 |
Status tracker
| Phase | Precondition | Reference | Key artifact |
|---|---|---|---|
| 0 Env + req | — | 00-environment | CANN + conda + name + spec |
| 1 Init | 0 | 01-project-init | csrc/ops/<op>/ skeleton |
| 2 Design | 1 | 02-design | design.md |
| 3 Test cases | 2 | 03-testcase-gen | <op>-test-cases.md |
| 4 Code-gen | 3 | 04-code-gen | op_host + op_kernel + registration |
| 5 Compile/debug | 4 | 05-compile-debug | installed wheel + green tests |
| 6 Docs | 5 | 06-doc-gen | README.md |
| 7 Precision | 6 | 07-precision-eval | precision report |
| 8 Performance | 7 | 08-performance-eval | performance report |
| 9 Optimize | 8 | 09-performance-optim | optim summary |
| 10 Review | 4+ | 10-code-review | review report |
Dependencies
This skill is self-contained (templates, references, examples, and scripts are bundled).
It only needs a working CANN toolkit and a PyTorch + torch_npu conda environment on a
host with Ascend NPUs to compile and run the operator.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/ascend-ai-coding/awesome-ascend-skills/ascendc">View ascendc on skillZs</a>