PTOAS Agent Skill

A source-grounded Codex skill pack for PTOAS, PTO-ISA, PyPTO, pypto-lib, and Ascend AI Core development.

---

Why This Exists

PTOAS work crosses too many layers for a generic coding agent to guess safely:

• CANN and Ascend AI Core architecture facts
• PTOAS MLIR dialects and transform passes
• PTO-ISA architecture-specific headers and ST tests
• PyPTO pass/codegen/runtime pipelines
• pypto-lib model kernels, debugging, tuning, and validation flows

This repository turns that terrain into a skill pack. The point is not just "more context"; it is the right context, loaded at the right time, with every architecture claim labeled by evidence quality.

flowchart LR
    U["User request"] --> N["ptoas-project-navigator"]
    N --> A["ascend-aicore-architecture"]
    N --> P["ascend-a3-a5-porting"]
    N --> B["ptoas-build-and-test"]
    N --> D["ptoas-dialect-op-development"]
    N --> T["ptoas-pass-development"]
    N --> I["pto-isa-instruction-development"]
    N --> C["pypto-codegen-debugging"]

    A --> R["shared/references"]
    P --> R
    B --> R
    D --> R
    T --> R
    I --> R
    C --> R

    R --> S1["official"]
    R --> S2["repo-confirmed"]
    R --> S3["implementation-note"]
    R --> S4["inferred / unknown"]

Loading

Skill Matrix

Skill	Use when the agent needs to...
ascend-aicore-architecture	Answer AIC/AIV, Cube/Vector, memory, sync, CANN 220x/300x, A3/A5/910B/950 architecture questions.
ascend-a3-a5-porting	Port or debug behavior across a2a3, a5, a2a3sim, a5sim, --pto-arch=a3, and --pto-arch=a5.
ptoas-project-navigator	Decide which repository owns a bug, feature, file, test, or concept.
ptoas-build-and-test	Pick the right build/test/simulator/board command for the PTOAS stack.
ptoas-dialect-op-development	Add, change, document, or debug PTO dialect operations and verifier behavior.
ptoas-pass-development	Work on PTOAS transforms, InsertSync, memory planning, lowering, and pass pipelines.
pto-isa-instruction-development	Implement or debug PTO-ISA instructions, a2a3/a5 headers, comm paths, costmodel paths, and ST tests.
pypto-codegen-debugging	Trace PyPTO pass dumps, generated PTO/PTOAS, backend handlers, and pypto-lib compile/runtime failures.

Evidence Discipline

Architecture drift is expensive. This pack keeps facts tagged:

Label	Meaning
official	CANN/HiAscend first-party documentation.
repo-confirmed	Directly observed in PTOAS, pto-isa, PyPTO, or pypto-lib code/docs.
implementation-note	Current implementation behavior that may change.
inferred	Reasoned from multiple sources, not directly stated.
unknown	Not proven. The agent should say so instead of inventing.

One important guardrail: the pack does not blindly state 300x = A5/950 as an official fact. It separates the public CANN 220x/300x documents from repository-confirmed a3/a2a3 and a5/Ascend950 target mappings.

Repository Shape

PTOAS-Agent-Skill/
├── skills/
│   ├── ascend-aicore-architecture/
│   ├── ascend-a3-a5-porting/
│   ├── ptoas-project-navigator/
│   ├── ptoas-build-and-test/
│   ├── ptoas-dialect-op-development/
│   ├── ptoas-pass-development/
│   ├── pto-isa-instruction-development/
│   └── pypto-codegen-debugging/
├── shared/references/
│   ├── ascend-architecture-map.md
│   ├── source-map.md
│   ├── ptoas-pipeline-map.md
│   └── pypto-pipeline-map.md
├── scripts/
│   └── validate_skill_pack.py
└── docs/plans/

Quick Start

git clone https://github.com/HecreReed/PTOAS-Agent-Skill.git
cd PTOAS-Agent-Skill
python scripts/validate_skill_pack.py

Expected:

OK: skill pack structure is valid

Validation

The local validator checks:

• all 8 phase-1 skills exist
• each skill has SKILL.md
• each skill has agents/openai.yaml
• frontmatter uses name and description
• descriptions start with Use when
• no generated TODO template text remains
• architecture references do not overclaim the 300x/A5 mapping

python scripts/validate_skill_pack.py

Source Anchors

The pack is built around the current PTOAS workspace:

Project	Role
hw-native-sys/PTOAS	PTO dialect, transforms, memory planning, ptoas CLI, codegen.
cann/pto-isa	PTO instructions, architecture-specific headers, comm instructions, ST tests.
hw-native-sys/pypto	Python DSL/IR, pass pipeline, backend handlers, generated PTO/PTOAS.
hw-native-sys/pypto-lib	Kernel/model workflows, golden validation, debugging, tuning.
CANN/HiAscend docs	Official architecture facts and API references.

Phase 1 design intent

Phase 1 deliberately focuses on eight high-leverage skills instead of a giant monolithic guide. The skills are small, triggerable, and backed by shared references. Future phases can add profiling, precision tuning, communication operator development, performance sweeps, and pypto-lib kernel authoring without bloating the first-load context.

---

Built for agents that should read the source before touching the machine.