# Triton Cpu Kernel Engineer

> Skill: `triton-cpu-kernel-engineer`

- Skill: `maxiaotiao1105/triton-cpu-kernel-engineer` (Agent Skill, multi-file: 13 files)
- Install (CLI): `npx skillmds@latest add maxiaotiao1105/triton-cpu-kernel-engineer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/maxiaotiao1105/triton-cpu-kernel-engineer/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: MaXiaoTiao1105 (https://skillmd.com/u/maxiaotiao1105)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/maxiaotiao1105/triton-cpu-kernel-engineer

---

# Skill: `triton-cpu-kernel-engineer`

## Purpose

A **pre-codegen planning skill** for Triton/Triton-CPU flavored CPU operators.

This skill does not write kernels. It produces a **structured design document** that makes every critical decision explicit before any code is written — with ARM64 readiness and backend-sensitive assumption surfacing built in.

Use this skill when you need to take an operator from "vague idea" to "implementation-ready plan" with:
- Explicit assumptions that can be verified against the actual backend
- Backend-sensitive knobs surfaced for future codegen/autotune
- Correctness and benchmark plans that survive beyond the conversation

**Target users**: Engineers building toward ARM64 CPU kernel generation, or anyone who needs rigorous planning before kernel implementation.

---

## When to use

Use this skill when:

- You have an operator (or fused op) and need a **pre-codegen design**
- You're porting a GPU kernel idea to **CPU** and need to translate concepts
- You need to surface **ARM64-specific decisions** (NEON vs SVE, vector width, alignment)
- You want a correctness + benchmark plan that can be reviewed independently
- You're building toward **automatic kernel generation** and need structured decision artifacts

---

## When not to use

Do not use this skill if:

- The operator is best served by calling an existing library (BLAS GEMM, oneDNN conv) — the answer is "call the library"
- You want GPU kernel code — use a GPU-focused skill
- You want quick Python refactoring — this is overkill
- Critical information is missing and you refuse to provide it (see Prerequisites below)

---

## Prerequisites for codegen-readiness

Before this skill can produce an implementation-ready plan, the following must be known.

### Must have

| Prerequisite | Why it matters |
|--------------|----------------|
| Operator semantics | Cannot design without knowing what the op computes |
| Shape regime | Tiling, vectorization, cache behavior all depend on actual dimensions |
| Layout/stride | Contiguous vs strided fundamentally changes access patterns |
| Target ISA | x86_64 vs ARM64, NEON vs SVE — different vector models |
| Numerical constraints | Stability requirements affect reduction strategy |

### Should have

| Prerequisite | Why it matters |
|--------------|----------------|
| Dtype + accumulation dtype | Affects numerical stability and bandwidth |
| Baseline implementation | Needed for correctness validation |
| Threading model | Affects parallel reduction strategy |
| Performance target | "Faster than baseline" needs a baseline |

### Missing prerequisite handling

- If a **must-have** prerequisite is missing, output a **Prerequisite Gap Report** and do not produce a design.
- If a **should-have** prerequisite is missing, proceed only with explicitly labeled assumptions.

Prerequisite Gap Report format:

```
## Cannot proceed — missing prerequisites

- [ ] Shape regime: what are typical N values?
- [ ] Layout: is x contiguous or strided?
- [ ] Target ISA: ARM64 with NEON, SVE, or unknown?

Please provide the above before design proceeds.
```

---

## Workflow (must follow)

### Step 0 — Prerequisite check

Before any analysis, verify prerequisites are met. If not, output a Prerequisite Gap Report and stop.

### Step 1 — Operator classification

**Library-first check**: Before proposing a custom kernel path, check whether the operator is already well served by a library or compiler-generated path. If yes, document why a custom kernel is still justified.

Classify the operator into one or more categories:

| Category | Examples | Key considerations |
|----------|----------|-------------------|
| Elementwise | relu, add, mul | Memory-bound; vectorize over contiguous axis |
| Reduction | sum, max, mean | Axis choice, numerical stability, parallel strategy |
| Matmul-like | GEMM, attention QK^T | Often best served by library; tiling for cache |
| Stencil-like | convolution, sliding window | Reuse, boundary handling |
| Normalization | layernorm, RMSNorm | Multi-stage reduction, numerics |
| Attention subroutine | softmax, masked attention | Stability, masking strategy |
| Fused op | bias+gelu+residual | Fusion decision, register pressure |

Output:
- Category assignment
- Memory-bound vs compute-bound hypothesis
- Suitability for Triton/Triton-CPU vs alternatives (C++/SIMD, OpenMP, library call)

### Step 2 — Data layout analysis

Produce a layout table:

| Tensor | Shape | Dtype | Strides | Contiguous? | Notes |
|--------|-------|-------|---------|-------------|-------|
| x | [B, N] | bf16 | (N, 1) | Yes | row-major |
| y | [B, N] | bf16 | (N, 1) | Yes | row-major |

Also identify:
- Which dimensions are contiguous → candidates for vectorization
- Which dimensions have broadcast → affects access pattern
- Tail cases → how often do we have remainder elements

### Step 3 — Vectorizable axis identification

Explicitly state:
- Which axis is contiguous and suitable for vectorization
- Expected vector width (state as assumption, verify against backend)
- Tail handling strategy (scalar tail, masked ops, or padding)

### Step 4 — Backend-sensitive assumption surfacing

This is critical. Every design must explicitly state assumptions that depend on the backend:

| Assumption | Typical value | How to verify |
|------------|---------------|---------------|
| Vector width | NEON: 128-bit (4 × fp32); SVE: variable | Check CPU features or backend docs |
| Alignment | 16-byte or 64-byte | Check allocation or add padding path |
| Cache line size | 64 bytes typical | Architecture-specific |
| Prefetch behavior | Backend-dependent | Profile on target hardware |
| Reduction stability | fp32 accumulation for bf16 inputs | Numerical analysis or test |

**Rule**: If you cannot verify an assumption, mark it as "ASSUME" and provide a verification step.

### Step 5 — ARM64 readiness knobs

Surface decisions that should be parameterized for future codegen:

| Knob | Description | Typical range |
|------|-------------|---------------|
| TILE_SIZE | Elements per tile | 64, 128, 256 |
| VECTOR_WIDTH | Vector lanes | 4 (NEON), 8 (SVE-256), variable |
| UNROLL_FACTOR | Loop unroll | 1, 2, 4 |
| ACCUMULATION_DTYPE | For reductions | fp32, fp64 |

These knobs should be **exposed as parameters** in the design, not hardcoded.

### Step 6 — Performance hypothesis

State a falsifiable hypothesis:

- **Bottleneck hypothesis**: What is the primary limiter? (bandwidth, compute, latency, TLB, cache misses)
- **Expected win mechanism**: Why should this design be faster? (fusion, better locality, fewer passes)
- **Confirmation metric**: What measurement will confirm or refute? (cache miss rate, IPC, bandwidth utilization)

### Step 7 — Correctness plan

Define:
- Reference implementation (even if slow)
- Invariants (shape rules, dtype rules, numerical constraints)
- Test matrix (shapes, dtypes, layouts, edge cases)
- Tolerances (absolute, relative) with justification

### Step 8 — Benchmark plan

Define:
- Baselines (what to compare against, fairness rules)
- Shape matrix (what sizes to test)
- Warmup/repeats methodology
- Variance reporting (median, p95)
- Environment capture (what to record)

### Step 9 — Profiling plan

Define:
- Which profiler to use (perf, VTune, etc.)
- What signals to capture (cache misses, IPC, SIMD utilization)
- How results inform next optimization step

### Step 10 — Implementation readiness check

Before code is written, verify:

- [ ] All prerequisites met
- [ ] Backend-sensitive assumptions stated
- [ ] ARM64 knobs surfaced
- [ ] Correctness plan defined
- [ ] Benchmark plan defined
- [ ] Falsifiable hypothesis stated

Only after this check should implementation begin.

---

## Output contract

Every output must follow this structure:

```
## Prerequisite Check
[PASSED or GAP REPORT]

## Operator Classification
[Category + library-first check + suitability analysis]

## Data Layout Analysis
[Table + vectorizable axis]

## Backend-Sensitive Assumptions
[Table with assumption, value, verification method]

## ARM64 Readiness Knobs
[Table of exposed parameters]

## Performance Hypothesis
[Bottleneck + mechanism + confirmation metric]

## Correctness Plan
[Reference + invariants + test matrix + tolerances]

## Benchmark Plan
[Baselines + shapes + methodology + reporting]

## Profiling Plan
[Tool + signals + interpretation guide]

## Codegen Readiness Decision
- Status: Ready / Not Ready
- Blocking gaps: [list if Not Ready]
- Assumptions to verify before implementation: [list]
- Exposed tuning knobs: [list]
```

---

## Quality bar

Output is acceptable only if:

- All prerequisites are met or explicitly stated as gaps
- Backend-sensitive assumptions are stated with verification methods
- ARM64 knobs are surfaced as parameters, not hardcoded
- Performance hypothesis is falsifiable
- No unverified backend claims ("Triton-CPU supports X" without evidence)

---

## Failure modes

Avoid these common mistakes:

| Mistake | Why it's wrong |
|---------|---------------|
| Proposing tiling without identifying vectorizable axis | May tile the wrong dimension |
| Discussing performance without shape regime | Optimal tiling depends on actual sizes |
| Assuming backend support not yet verified | May produce code that doesn't compile or runs slowly |
| Ignoring pathological stride cases | Strided inputs can dominate runtime |
| Treating ARM SIMD width as fixed | NEON is 128-bit; SVE is variable |
| Hardcoding tile sizes | Should be exposed for autotune |
| Skipping correctness plan | Bugs will be discovered late |
| Unfair baseline comparison | Results won't be meaningful |

---

## ARM64-specific considerations

### NEON vs SVE

| Aspect | NEON | SVE |
|--------|------|-----|
| Vector width | Fixed 128-bit | Variable (128–2048 bit) |
| Code portability | Straightforward | Requires vector-length-agnostic code |
| Availability | All ARM64 | Optional (server CPUs) |

**Design rule**: Do not assume SVE exists unless the target is known. Design for NEON first, expose vector width as a knob.

### Alignment

- NEON prefers 16-byte alignment for vector loads
- SVE can handle unaligned but aligned is faster
- **Design rule**: Assume alignment, provide fallback for misaligned cases

### Cache behavior

- ARM64 cache hierarchies vary by micro-arch (Neoverse N1/V1/V2, Cortex families)
- **Design rule**: Expose tile size as a tunable, do not hardcode for one micro-arch

---

## Supporting docs

- `docs/SCOPE_AND_ASSUMPTIONS.md` — What this skill does and does not cover
- `docs/OP_CLASSIFICATION_GUIDE.md` — Operator taxonomy and suitability cues
- `docs/CPU_MEMORY_AND_CACHE_NOTES.md` — Cache locality reasoning
- `docs/ARM64_READINESS_NOTES.md` — ARM64-specific design considerations

## Templates

- `templates/KERNEL_DESIGN_DOC.md` — Pre-codegen design document
- `templates/CORRECTNESS_PLAN.md` — Test matrix and tolerances
- `templates/BENCHMARK_PLAN.md` — Methodology and reporting

## Examples

- `examples/prompts.md` — 9+ example prompts
- `examples/worked-example-layernorm.md` — Full worked example
- `examples/worked-example-softmax.md` — Numerically sensitive op example