add-expert-skill-to-geak

name	add-expert-skill-to-geak
description	Contribute a human-authored, e2e-validated optimization recipe (an "expert skill") to GEAK — scaffold, fill, validate by scope, and open a PR.

Skill: add an expert skill to GEAK

Use this when a human expert has a reusable optimization recipe worth capturing so the e2e_workflow / kernel_workflow can reproduce it automatically — e.g. "port MLA decode from TileLang to Triton on gfx942", or "the FlyDSL fp8 a8w8 blockscale down-proj playbook (+67% e2e)".

Read the contract first: ../README.md. Key rule: a skill is an advisory prior, never a mandate; it must pass a validation gate (efficacy + do-no-harm) before it lands as validated, and the consuming workflow always decides the winner by on-box measurement.

Steps (works for a human or an agent)

1. Scaffold

python _contribute/scaffold.py --id <slug> --operator <op> --scope <kernel|e2e> \
  --title "..." --author <you> --gens gfx942 --dtypes fp8_e4m3_fnuz --regimes prefill,decode \
  [--from-backend tilelang --to-backend triton]   # migration skills

• --operator MUST be a name that exists in ../index/capability_index.yaml (the selector matches on it). The scaffolder rejects unknown operators.
• --scope kernel → validated by kernel_workflow (isolated A/B vs the oracle), consumed by the kernel layer. --scope e2e → validated by e2e_workflow (Director same-session A/B), consumed by routing.
• This writes skills/<slug>/skill.md (status: draft) and regenerates index.yaml.

2. Fill the recipe

Edit skills/<slug>/skill.md. The body sections are required and must be non-empty:

• When to use — the exact bottleneck/shape/arch.
• Mechanism — why it works (hardware/numerics/scheduling) so it transfers.
• Procedure — the regulated steps an author-agent reproduces: entrypoints, kernel structure, the named lever (e.g. "fuse the dequant into one fp8 MFMA").
• Knobs & pitfalls, Do-no-harm notes (where it must stay OFF), Sources (every claim pointed).

3. Validate (two-sided gate)

python _contribute/validate_skill.py <slug> --static          # schema/operator/sections (no GPU)
python _contribute/validate_skill.py <slug> --emit-plan --model <MODEL>   # prints the on-box command
# ... run that Workflow command on a box; it produces an eval dir with the measured delta ...
python _contribute/validate_skill.py <slug> --record --artifact <eval_dir> \
  --gpu gfx942/MI300X --model <name> --date 2026-06-17 \
  --e2e-pct 2.1 --parity pass            # (kernel scope: --isolated 1.27 instead of --e2e-pct)

• Efficacy: the measured delta must meet the skill's expects (isolated_speedup_min or e2e_delta_min_pct) with parity. Otherwise --record stamps status: failed and exits non-zero.
• Do-no-harm: also run the control scenario from _emit-plan (a model/shape that does NOT match the selector) with use_expert_skills=true and confirm |e2e delta| stays within the noise band — i.e. the skill is inert when not triggered. Record that eval dir in the skill's Sources.
• --record writes the validation: block and reindexes; only validated skills are auto-applied.

4. Open a PR

bash _contribute/make_pr.sh <slug>          # refuses unless status==validated (use --allow-draft for WIP)

Branches expert-skill/<slug>, commits the skill + regenerated index.yaml, pushes, and opens a PR (via gh if present, else prints the compare URL).

Notes

• Skills are opt-in. The workflows ignore expert_skills/ unless a run passes use_expert_skills=true (default OFF). So: validation runs (--emit-plan above) already pass it, and to benefit from a landed skill in a normal optimization run you must enable it explicitly. With the flag OFF the workflow behaves byte-identically to a build without this feature.
• Maintain skills ONLY in the canonical geak_v4/GEAK tree; other snapshots sync from here.
• A skill that later regresses (aiter/triton upgrade, box drift) should be re-validated; staleness demotes it to a plain reference until refreshed.