cann-workbench 0.0.0-stage → 0.0.2-alpha

package/skills/asc-tools/tool-precision-debug/skills/tool-precision-debug/references/tools/msobjdump.md

@@ -0,0 +1,150 @@
+# msobjdump：查看、提取与反汇编 Ascend C 产物
+
+`msobjdump` 读取 Ascend C 编译产物，查看 Kernel 元数据、列出或提取内嵌设备 ELF，并在工具支持时反汇编 AI Core 指令。它静态读取文件，不执行输入程序；分析已有 ELF 不需要先运行算子。
+
+## 使用场景
+
+| 当前需要确认什么 | 使用方式 |
+| --- | --- |
+| 产物中有哪些 Kernel、核类型或 TilingKey | `--dump-elf` 查看元数据。 |
+| ELF 的段、符号及文件头 | 在 `--dump-elf` 后加 `--verbose`，查看当前格式支持的详细输出。 |
+| 封装产物中包含哪些设备文件 | `--list-elf` 列出内嵌文件。 |
+| 单独检查封装中的某个 Kernel 文件 | `--extract-elf` 提取，再对实际生成的设备 ELF 查看元数据。 |
+| 编译后生成了哪些设备指令 | 帮助中提供 `--sass` 时，用它反汇编设备代码。 |
+
+输入可以是独立设备 ELF，也可以是含设备代码的融合编译可执行文件、动态库或其他封装。文件后缀不能说明内容；普通 Host ELF 即使扩展名同样是 `.o` 或 `.so`，也不一定包含 Ascend Kernel。
+
+## 调用准备
+
+使用工程实际采用的 CANN 环境，先确认安装版能力：
+
+```bash
+msobjdump -h
+```
+
+查看元数据依赖 `readelf`；处理 `.aicore_binary` 融合产物还需要 `llvm-objcopy`，处理静态库可能用到 `ar`。`--sass` 需要带 Ascend 反汇编后端的 `llvm-objdump`，系统通用 LLVM 工具不一定具备该能力。
+
+以下 `<artifact-dir>` 表示本次任务产物目录，使用前替换为实际路径。在独立可写工作目录运行命令；查看、列出操作也可能创建临时文件，部分静态库处理会将成员写到当前目录。每次提取使用单独的输出目录，避免覆盖已有同名文件。
+
+## 常用命令
+
+### 查看 Kernel 元数据与详细结构
+
+```bash
+msobjdump --dump-elf "<input-elf>"
+msobjdump --dump-elf "<input-elf>" --verbose
+```
+
+默认输出以 Kernel 元数据为主；`--verbose` 请求额外的 ELF 结构信息，不是反汇编。检查融合产物时，详细输出可能来自提取后的设备 ELF；不要把其中的 Machine、段或符号解释成外层 Host 程序的信息。
+
+独立设备 ELF 的 `--verbose` 可能仍只显示元数据。需要完整文件头、段和符号时，可直接读取该设备文件：
+
+```bash
+readelf -aW "<device-elf>"
+```
+
+### 列出与提取内嵌文件
+
+```bash
+msobjdump --list-elf "<input-elf>"
+mkdir -p "<artifact-dir>/device-elf"
+msobjdump --extract-elf "<input-elf>" --out-dir "<artifact-dir>/device-elf"
+find "<artifact-dir>/device-elf" -type f
+```
+
+`--out-dir` 需要是已存在的目录；省略时写到当前工作目录。提取后检查实际文件及大小。独立设备 ELF 没有其他内嵌文件时，`nothing to list` 或 `nothing to extra` 是正常提示，直接对该设备 ELF 执行 `--dump-elf` 即可。
+
+一次调用选择 dump、list、extract、sass 中的一种操作，需要多个结果时分别调用。不要把多个主操作拼成一条命令，部分版本会只执行其中一个。
+
+### 反汇编设备指令
+
+安装版帮助包含 `--sass` 时：
+
+```bash
+mkdir -p "<artifact-dir>/disassembly"
+msobjdump --sass "<input-elf>" > "<artifact-dir>/disassembly/device.txt" 2> "<artifact-dir>/disassembly/stderr.log"
+```
+
+`--sass` 输出到标准输出，不能与 `--out-dir`、`--verbose` 或其他主操作组合。当前上游支持独立设备 ELF、融合 Host ELF 和普通 `.a` 归档；归档会逐个处理成员，thin archive 不支持。
+
+正常反汇编应包含指令地址、编码、助记符和操作数。只有文件格式标题，或指令全为 `<not available>`，都不能算成功；工具也可能直接报告 `no valid instruction lines`，不转发这类无效输出。此时检查所用 `llvm-objdump` 是否能反汇编该设备架构。多个镜像的输出按 `===== [SASS] 来源 =====` 分段，先看来源再对应 Kernel。
+
+如果帮助信息包含源码定位选项，可以使用：
+
+```bash
+msobjdump --sass "<input-elf>" --lineinfo
+msobjdump --sass "<input-elf>" --source
+msobjdump --sass "<input-elf>" --lineinfo --source
+```
+
+`--lineinfo` 显示源文件名和行号；`--source` / `-s` 在反汇编结果中显示对应源码。使用这两个选项时需要指定 `--sass`。
+
+编译算子时请使用 `-g` 生成调试信息，配置方法请参见[常用的编译选项](https://gitcode.com/cann/asc-devkit/blob/master/docs/zh/guide/programming_guide/compilation_and_execution/operator_compilation/ai_core_operator_compilation.md#ZH-CN_TOPIC_0000002462746461)和[自定义编译选项](https://gitcode.com/cann/asc-devkit/blob/master/docs/zh/guide/programming_guide/advanced_programming/aclnn_operator_development/compilation_and_deployment/basic_process.md#custom-compile-options)。
+
+显示源码时需保留调试信息中记录的源文件及其路径。即使 device ELF 不含调试信息，`--sass` 仍可输出反汇编指令，但 `--lineinfo` 无法显示源码位置，`--source` 无法显示源码。使用 `--source` 时，若源文件无法访问，工具会输出告警并继续反汇编，但不显示对应源码。
+
+## 元数据怎样解释
+
+按 `.ascend.meta. [索引]: 名称` 分组阅读，保留完整 Kernel 符号；索引相同不代表函数相同。缺少某字段时不要补成默认值。
+
+| 字段 | 可用于确认什么 | 解释边界 |
+| --- | --- | --- |
+| `.ascend.meta. [索引]: 名称` | 产物中记录的 Kernel 符号，可能经过 C++ 名称修饰。 | 名称存在不代表本轮运行调用过它。 |
+| `VERSION` | 元数据格式中的版本值。 | 不是 CANN 安装版本，也不是 msobjdump 软件版本。 |
+| `KERNEL_TYPE` | 产物声明的核类型，如 AIC、AIV、MIX_AIC_MAIN、MIX_AIV_MAIN。 | 不能据此推算实际启动核数。 |
+| `CROSS_CORE_SYNC` | 硬同步配置，如 USE_SYNC。 | 不能据此证明运行时同步正确。 |
+| `MIX_TASK_RATION` | Cube/Vector 任务配比，如 `[1:2]`。 | 不是耗时或利用率比例；保留工具原拼写。 |
+| `FUNCTION_ENTRY` | 工具解析出的 TilingKey 整数。 | 不是指令地址，也不证明该 key 本轮被执行。 |
+| `BLOCK_NUM` | 当前上游实现打印占位值 `0xFFFFFFFF`；部分安装版不显示此字段。 | 占位值或字段缺失都不能换算成实际执行核数。 |
+| `DEBUG`、`RUNTIME_IMPLICIT_INFO` | 调试缓冲区、调试选项及隐式信息标志。 | 有标志不等于本次运行已采集到调试数据。 |
+
+例如混合算子同时出现 `mix_aic`、`mix_aiv` 两个符号，并有 `KERNEL_TYPE: MIX_AIC_MAIN`、`MIX_TASK_RATION: [1:2]`，可据此检查是否生成了预期混合核实现；不能直接把两个符号当作两个独立算子。
+
+## 使用实例：检查融合编译产物
+
+已有融合编译产物时，先列出其内嵌设备文件，再提取和读取元数据。列表或提取目录为空时，先按下文检查融合段，不猜测设备文件名：
+
+```bash
+msobjdump --list-elf "<fusion-elf>"
+mkdir -p "<artifact-dir>/fusion-device"
+msobjdump --extract-elf "<fusion-elf>" --out-dir "<artifact-dir>/fusion-device"
+find "<artifact-dir>/fusion-device" -type f
+msobjdump --dump-elf "<实际提取出的设备ELF>"
+```
+
+当前上游对包含 `.aicore_binary` 的产物会自动提取设备段，文件名通常形如 `<输入文件名>.aicore.o`。以实际列表和生成文件为准；需要完整结构时按上文使用 `readelf -aW`，需要设备指令且工具具备能力时使用 `--sass`。
+
+如果安装版对外层融合 ELF 提示找不到元数据，先检查段信息：
+
+```bash
+readelf -SW "<fusion-elf>"
+```
+
+确认存在 `.aicore_binary`，但当前工具不能自动处理时，可用配套工具提取后继续解析：
+
+```bash
+mkdir -p "<artifact-dir>/fusion-device"
+llvm-objcopy -O binary --only-section=.aicore_binary "<fusion-elf>" "<artifact-dir>/fusion-device/device.o"
+msobjdump --dump-elf "<artifact-dir>/fusion-device/device.o"
+```
+
+没有 `.aicore_binary` 时，不套用这条提取命令；按实际段、符号和当前工具支持的封装类型选择入口。提取成功后可核对 Kernel 名称、核类型与 TilingKey；是否加载该产物、是否选择该分支，仍需本轮运行记录确认。
+
+## 常见问题与结果检查
+
+| 现象 | 处理方法 |
+| --- | --- |
+| `unrecognized arguments: --sass` | 当前安装未提供反汇编选项；不要换成未声明的 `-sass`。使用支持该选项且与当前 CANN 后端配套的工具版本。 |
+| 找不到 Kernel 元数据 | 检查是否给了普通 Host ELF、是否存在设备封装、安装版是否支持该格式；不能直接判定文件损坏或没有设备代码。 |
+| 封装层只显示文件信息或 `[ASCEND META]: None` | 用 `--extract-elf` 提取后，对实际设备 ELF 单独执行 `--dump-elf`；该提示不能证明内层没有元数据。 |
+| 提取结束但目录为空 | 检查 `nothing to extra`、异常输出和输入类型；不能只凭退出码 0 声称已提取文件。 |
+| 输出目录无效或临时目录创建失败 | 先创建输出目录，并检查当前工作目录及输出目录的写权限。 |
+| 缺少 `readelf`、`llvm-objcopy` 或 `llvm-objdump` | 在同一 shell 中加载工程采用的 CANN 环境，确认缺少的是哪个依赖；反汇编后端缺失不等于元数据也无法读取。 |
+| 路径含空格，命令报参数或文件不存在错误 | 确认 Python 包来自同一套安装后，用 `python3 -m msobjdump` 替换命令前缀，保持参数及路径引号不变，绕过旧 shell 包装脚本的拆词问题。 |
+| 有反汇编输出，但同时报错或含未知指令 | 检查完整标准错误和退出状态；部分镜像或指令失败时，已有输出只能算部分结果。 |
+
+保留命令、标准输出、标准错误和实际提取文件。静态元数据和反汇编用于检查编译产物，不能单独证明本轮输入的执行路径、同步正确性或精度根因。
+
+## 官方说明
+
+asc-tools 工具相关详细说明见 [asc-tools 官方仓库](https://gitcode.com/cann/asc-tools)，按 `msobjdump` 查找使用说明与样例。实际操作以当前安装的帮助、格式支持和配套 CANN 工具为准。

package/skills/cann-doctor/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: cann-doctor
+description: CANN Doctor 故障诊断工作台。分析 Ascend NPU 日志、CANN 故障和崩溃，使用官方故障诊断技能并将报告交付到 DSH 右侧工作台。
+---
+
+# CANN Doctor
+
+1. 调用 `cann_doctor`，`action: "status"`。没有已安装技能时执行 `action: "update-skills"`；更新失败时告知用户原因，有旧版时继续使用旧版。
+2. 使用 `skill` 加载 `orchestrator-skill`，遵循它的编排规则。日志不完整先使用 `collect-skill`；已有完整日志进入 `eval-skill`；需要证据链追踪使用 `trace-skill`；正式报告使用 `metric-skill`。脚本、模板和参考资料按加载技能的绝对资源目录访问。
+3. 先取得用户提供的真实日志或路径；不生成虚构诊断。采集需要 Ascend 主机和相应系统工具，当前电脑没有 NPU 不能声称完成硬件验证。
+4. 编排脚本输出 blocked 或诊断草稿时，必须完成实质诊断与证据审查，再按官方 Skill 恢复流水线。区分已确认事实、推断和缺失证据。
+5. 完成后调用 `cann_doctor_publish_report`，传入报告标题、完整报告文件的 `reportPath` 和 `format: "markdown"` 或 `"html"`。可直接用 `content` 发布完整 Markdown。报告文件与 content 二选一。传入所加载上游技能标注的 `skillRevision`。
+6. 告知用户报告已出现在右侧 CANN Doctor；请用户自行选择“👍 诊断准确”或“👎 诊断错误”。禁止替用户判断、调用反馈命令或改写反馈数据。
+
+HTML 在工作台内安全静态预览，脚本不会执行；优先生成内容完整、证据可追溯的 Markdown 或静态 HTML。

package/skills/catalog.json

@@ -0,0 +1,79 @@
+{
+  "schemaVersion": 1,
+  "sources": [
+    {
+      "id": "asc-tools",
+      "directory": "asc-tools",
+      "title": {
+        "zh": "性能调优",
+        "en": "Performance tuning"
+      },
+      "repository": "https://gitcode.com/cann/asc-tools",
+      "revision": "77cba0b6930e859b0cd18bc9e3ca300d83e86834",
+      "visible": true
+    }
+  ],
+  "archivedPaths": [
+    {
+      "path": "asc-tools/tool-precision-debug",
+      "reason": "由性能任务按需安装，技能页不单独展示精度调试集合。"
+    }
+  ],
+  "displayOverrides": {
+    "asc-tools/tool-ops-tune": {
+      "name": {
+        "zh": "OpsTune 调优套件",
+        "en": "OpsTune tuning suite"
+      },
+      "description": {
+        "zh": "对已可运行且精度通过的算子开展性能调优。",
+        "en": "Tune operators that already run correctly and pass accuracy checks."
+      },
+      "order": 0
+    },
+    "asc-tools/tool-ops-tune/ops-collect": {
+      "name": {
+        "zh": "性能数据采集",
+        "en": "Performance collection"
+      },
+      "description": {
+        "zh": "组织性能采集与测试，整理供分析使用的产物。",
+        "en": "Collect performance data and organize analysis artifacts."
+      },
+      "order": 1
+    },
+    "asc-tools/tool-ops-tune/ops-mechanism": {
+      "name": {
+        "zh": "优化机制与案例",
+        "en": "Optimization mechanisms and cases"
+      },
+      "description": {
+        "zh": "查找优化原理、适用条件、案例和回退依据。",
+        "en": "Find optimization principles, prerequisites, examples, and rollback guidance."
+      },
+      "order": 2
+    },
+    "asc-tools/tool-ops-tune/ops-family": {
+      "name": {
+        "zh": "算子实现与模板",
+        "en": "Operator patterns and templates"
+      },
+      "description": {
+        "zh": "按算子类型组织实现范式与可复用模板。",
+        "en": "Explore reusable implementation patterns and templates by operator family."
+      },
+      "order": 3
+    },
+    "asc-tools/tool-ops-tune/ops-report": {
+      "name": {
+        "zh": "调优结果报告",
+        "en": "Tuning reports"
+      },
+      "description": {
+        "zh": "将判定与对比结果整理为可离线查看的 HTML 报告。",
+        "en": "Turn verdicts and comparisons into offline HTML reports."
+      },
+      "order": 4
+    }
+  }
+}

package/skills/mattpocock/GLOSSARY.md

@@ -0,0 +1,30 @@
+# Matt Pocock Skills
+
+A collection of agent skills (slash commands and behaviors) loaded by Claude Code. Skills are organized into buckets and consumed by per-repo configuration emitted by `/setup-matt-pocock-skills`.
+
+## Language
+
+**Issue tracker**:
+The tool that hosts a repo's issues: GitHub Issues, Linear, a local `.scratch/` markdown convention, or similar. Skills like `to-tickets`, `to-spec`, and `triage` read from and write to it.
+_Avoid_: backlog manager, backlog backend, issue host
+
+**Issue**:
+A single tracked unit of work inside an **Issue tracker**: a bug, task, spec, or slice produced by `to-tickets`.
+_Avoid_: ticket (use only when quoting external systems that call them tickets, or for a **Decision ticket**, see below)
+
+**Decision ticket**:
+A `wayfinder` unit: a child **Issue** of a `wayfinder:map` holding a *question* whose resolution is a decision, not a slice of a build to execute. The **decision** qualifier is what keeps it distinct from an implementation ticket; `wayfinder` introduces the term, then uses "ticket".
+
+**Triage role**:
+A canonical state-machine label applied to an **Issue** during triage (e.g. `needs-triage`, `ready-for-afk`). Each role maps to a real label string in the **Issue tracker** via `docs/agents/triage-labels.md`.
+
+## Relationships
+
+- An **Issue tracker** holds many **Issues**
+- An **Issue** carries one **Triage role** at a time
+- A **Decision ticket** is an **Issue** (a child of a `wayfinder:map`)
+
+## Flagged ambiguities
+
+- "backlog" was previously used to mean both the *tool* hosting issues and the *body of work* inside it. Resolved: the tool is the **Issue tracker**; "backlog" is no longer used as a domain term.
+- "backlog backend" / "backlog manager". Resolved: collapsed into **Issue tracker**.

package/skills/mattpocock/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/mattpocock/README.md

@@ -0,0 +1,258 @@
+<p>
+  <a href="https://www.aihero.dev/s/skills-newsletter">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://res.cloudinary.com/total-typescript/image/upload/v1777382277/skills-repo-dark_2x.png">
+      <source media="(prefers-color-scheme: light)" srcset="https://res.cloudinary.com/total-typescript/image/upload/v1777382277/skill-repo-light_2x.png">
+      <img alt="Skills" src="https://res.cloudinary.com/total-typescript/image/upload/v1777382277/skill-repo-light_2x.png" width="369">
+    </picture>
+  </a>
+</p>
+
+# Skills For Real Engineers
+
+[![skills.sh](https://skills.sh/b/mattpocock/skills)](https://skills.sh/mattpocock/skills)
+
+My agent skills that I use every day to do real engineering - not vibe coding.
+
+Developing real applications is hard. Approaches like GSD, BMAD, and Spec-Kit try to help by owning the process. But while doing so, they take away your control and make bugs in the process hard to resolve.
+
+These skills are designed to be small, easy to adapt, and composable. They work with any model. They're based on decades of engineering experience. Hack around with them. Make them your own. Enjoy.
+
+If you want to keep up with changes to these skills, and any new ones I create, you can join ~60,000 other devs on my newsletter:
+
+[Sign Up To The Newsletter](https://www.aihero.dev/s/skills-newsletter)
+
+## Installation (30-second setup)
+
+A plugin updates itself. [skills.sh](https://skills.sh/mattpocock/skills) copies editable files into your project, and you update them by hand. Pick one per agent, because installing both gives you every skill twice.
+
+### 1. Get the skills
+
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+```bash
+claude plugin install mattpocock-skills@claude-plugins-official
+```
+
+Updates itself by default.
+
+</details>
+
+<details>
+<summary><strong>Codex</strong></summary>
+
+```bash
+codex plugin marketplace add mattpocock/skills
+codex plugin add mattpocock-skills@mattpocock
+```
+
+Updates itself at startup.
+
+</details>
+
+<details>
+<summary><strong>GitHub Copilot</strong> (CLI and VS Code)</summary>
+
+```bash
+copilot plugin marketplace add mattpocock/skills
+copilot plugin install mattpocock-skills@mattpocock
+```
+
+Then, once, add to `~/.copilot/settings.json`:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "mattpocock": { "source": { "source": "github", "repo": "mattpocock/skills" }, "autoUpdate": true }
+  }
+}
+```
+
+In VS Code, run **Chat: Install Plugin From Source** and enter `https://github.com/mattpocock/skills`. It updates daily.
+
+</details>
+
+<details>
+<summary><strong>Gemini CLI</strong> (manual updates)</summary>
+
+```bash
+gemini skills install https://github.com/mattpocock/skills.git --path skills/engineering
+gemini skills install https://github.com/mattpocock/skills.git --path skills/productivity
+```
+
+Re-run both commands to update.
+
+</details>
+
+<details>
+<summary><strong>Any other agent, or editable files</strong> (manual updates)</summary>
+
+```bash
+npx skills@latest add mattpocock/skills -a <agent>  # cursor, opencode, devin, windsurf, amp, pi; omit -a to choose
+```
+
+When the installer asks which skills to take, include `setup-matt-pocock-skills`. To update, run `npx skills@latest update`, and re-run `add` to pick up new skills.
+
+</details>
+
+### 2. Run `/setup-matt-pocock-skills`
+
+In your agent, run it once per repo. It will:
+
+- Ask you which issue tracker you want to use (GitHub, GitLab, local files, or anything else you describe)
+- Ask you what labels you apply to tickets when you triage them (`/triage` uses labels)
+- Ask you where you want to save any docs we create
+
+### 3. Bam - you're ready to go.
+
+## Why These Skills Exist
+
+I built these skills as a way to fix common failure modes I see with Claude Code, Codex, and other coding agents.
+
+### #1: The Agent Didn't Do What I Want
+
+> "No-one knows exactly what they want"
+>
+> David Thomas & Andrew Hunt, [The Pragmatic Programmer](https://www.amazon.co.uk/Pragmatic-Programmer-Anniversary-Journey-Mastery/dp/B0833F1T3V)
+
+**The Problem**. The most common failure mode in software development is misalignment. You think the dev knows what you want. Then you see what they've built - and you realize it didn't understand you at all.
+
+This is just the same in the AI age. There is a communication gap between you and the agent. The fix for this is a **grilling session** - getting the agent to ask you detailed questions about what you're building.
+
+**The Fix** is to use:
+
+- [`/grill-me`](./skills/productivity/grill-me/SKILL.md) - for non-code uses
+- [`/grill-with-docs`](./skills/engineering/grill-with-docs/SKILL.md) - same as [`/grill-me`](./skills/productivity/grill-me/SKILL.md), but adds more goodies (see below)
+
+These are my most popular skills. They help you align with the agent before you get started, and think deeply about the change you're making. Use them _every_ time you want to make a change.
+
+### #2: The Agent Is Way Too Verbose
+
+> With a ubiquitous language, conversations among developers and expressions of the code are all derived from the same domain model.
+>
+> Eric Evans, [Domain-Driven-Design](https://www.amazon.co.uk/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215)
+
+**The Problem**: At the start of a project, devs and the people they're building the software for (the domain experts) are usually speaking different languages.
+
+I felt the same tension with my agents. Agents are usually dropped into a project and asked to figure out the jargon as they go. So they use 20 words where 1 will do.
+
+**The Fix** for this is a shared language. It's a document that helps agents decode the jargon used in the project.
+
+<details>
+<summary>
+Example
+</summary>
+
+Here's an example [glossary](https://github.com/mattpocock/course-video-manager/blob/076a5a7a182db0fe1e62971dd7a68bcadf010f1c/CONTEXT.md) (still named `CONTEXT.md` at that pinned commit, from before the skills renamed the convention), from my `course-video-manager` repo. Which one is easier to read?
+
+- **BEFORE**: "There's a problem when a lesson inside a section of a course is made 'real' (i.e. given a spot in the file system)"
+- **AFTER**: "There's a problem with the materialization cascade"
+
+This concision pays off session after session.
+
+</details>
+
+This is built into [`/grill-with-docs`](./skills/engineering/grill-with-docs/SKILL.md). It's a grilling session, but that helps you build a shared language with the AI, and document hard-to-explain decisions in ADR's.
+
+It's hard to explain how powerful this is. It might be the single coolest technique in this repo. Try it, and see.
+
+> [!TIP]
+> A shared language has many other benefits than reducing verbosity:
+>
+> - **Variables, functions and files are named consistently**, using the shared language
+> - As a result, the **codebase is easier to navigate** for the agent
+> - The agent also **spends fewer tokens on thinking**, because it has access to a more concise language
+
+### #3: The Code Doesn't Work
+
+> "Always take small, deliberate steps. The rate of feedback is your speed limit. Never take on a task that’s too big."
+>
+> David Thomas & Andrew Hunt, [The Pragmatic Programmer](https://www.amazon.co.uk/Pragmatic-Programmer-Anniversary-Journey-Mastery/dp/B0833F1T3V)
+
+**The Problem**: Let's say that you and the agent are aligned on what to build. What happens when the agent _still_ produces crap?
+
+It's time to look at your feedback loops. Without feedback on how the code it produces actually runs, the agent will be flying blind.
+
+**The Fix**: You need the usual tranche of feedback loops: static types, browser access, and automated tests.
+
+For automated tests, a red-green-refactor loop is critical. This is where the agent writes a failing test first, then fixes the test. This helps give the agent a consistent level of feedback that results in far better code.
+
+I've built a **[`/tdd`](./skills/engineering/tdd/SKILL.md) skill** you can slot into any project. It encourages red-green-refactor and gives the agent plenty of guidance on what makes good and bad tests.
+
+For debugging, I've also built a **[`/diagnosing-bugs`](./skills/engineering/diagnosing-bugs/SKILL.md)** skill that wraps best debugging practices into a disciplined loop, gated phase by phase.
+
+### #4: We Built A Ball Of Mud
+
+> "Invest in the design of the system _every day_."
+>
+> Kent Beck, [Extreme Programming Explained](https://www.amazon.co.uk/Extreme-Programming-Explained-Embrace-Change/dp/0321278658)
+
+> "The best modules are deep. They allow a lot of functionality to be accessed through a simple interface."
+>
+> John Ousterhout, [A Philosophy Of Software Design](https://www.amazon.co.uk/Philosophy-Software-Design-2nd/dp/173210221X)
+
+**The Problem**: Most apps built with agents are complex and hard to change. Because agents can radically speed up coding, they also accelerate software entropy. Codebases get more complex at an unprecedented rate.
+
+**The Fix** for this is a radical new approach to AI-powered development: caring about the design of the code.
+
+This is built in to every layer of these skills:
+
+- [`/to-spec`](./skills/engineering/to-spec/SKILL.md) quizzes you about which modules you're touching before creating a spec
+
+And crucially, [`/improve-codebase-architecture`](./skills/engineering/improve-codebase-architecture/SKILL.md) surveys a codebase for deepening opportunities and hands you the candidates. I recommend running it on your codebase once every few days. It is a survey, not a rescue: on a genuinely old codebase it will find real candidates, but it won't untangle the mud for you.
+
+### Summary
+
+Software engineering fundamentals matter more than ever. These skills are my best effort at condensing these fundamentals into repeatable practices, to help you ship the best apps of your career. Enjoy.
+
+## Reference
+
+These split on one axis: who can invoke them. **User-invoked** skills are reachable only when you type them (e.g. `/grill-me`); their job is to orchestrate. **Model-invoked** skills can be invoked by you _or_ reached for automatically by the agent when the task fits; they hold the reusable discipline. A user-invoked skill may invoke model-invoked skills, but never another user-invoked one.
+
+### Engineering
+
+Skills I use daily for code work.
+
+**User-invoked**
+
+- **[ask-matt](./skills/engineering/ask-matt/SKILL.md)**: Ask which skill or flow fits your situation. A router over the user-invoked skills in this repo.
+- **[grill-with-docs](./skills/engineering/grill-with-docs/SKILL.md)**: Grilling session that also builds your project's domain model, sharpening terminology and updating `GLOSSARY.md` and ADRs inline.
+- **[triage](./skills/engineering/triage/SKILL.md)**: Move issues through a state machine of triage roles.
+- **[improve-codebase-architecture](./skills/engineering/improve-codebase-architecture/SKILL.md)**: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
+- **[setup-matt-pocock-skills](./skills/engineering/setup-matt-pocock-skills/SKILL.md)**: Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo before using the other engineering skills.
+- **[to-spec](./skills/engineering/to-spec/SKILL.md)**: Turn the current conversation into a spec and publish it to the issue tracker. No interview, just synthesizes what you've already discussed.
+- **[to-tickets](./skills/engineering/to-tickets/SKILL.md)**: Break any plan, spec, or conversation into a set of tracer-bullet tickets, each declaring its blocking edges, written as text in a local file, or as native blocking links on a real tracker.
+- **[implement](./skills/engineering/implement/SKILL.md)**: Build the work described by a spec or set of tickets, driving `/tdd` at pre-agreed seams and closing out with `/code-review` before committing.
+- **[implement-spec](./skills/engineering/implement-spec/SKILL.md)**: Implement a whole spec on one integration branch. Works the tickets as a task graph, running implementer subagents across the ready frontier for maximum concurrency, then closes out with `/code-review`.
+- **[wayfinder](./skills/engineering/wayfinder/SKILL.md)**: Plan a huge chunk of work, more than one agent session can hold, as a shared map of decision tickets on the issue tracker, and resolve them one at a time until the way to the destination is clear.
+- **[retro](./skills/engineering/retro/SKILL.md)**: Suggest improvements to the coding agent's environment (navigation, automated checks, coding standards, steering files, tooling) after a session, most severe first.
+
+**Model-invoked**
+
+- **[prototype](./skills/engineering/prototype/SKILL.md)**: Build a throwaway prototype to answer a design question, either a single shareable HTML file for state/logic questions, or several radically different UI variations toggleable from one route.
+- **[diagnosing-bugs](./skills/engineering/diagnosing-bugs/SKILL.md)**: Disciplined diagnosis loop for hard bugs and performance regressions: build a feedback loop that goes red on this bug → minimise → hypothesise → instrument → fix → regression-test.
+- **[research](./skills/engineering/research/SKILL.md)**: Investigate a question against high-trust primary sources and capture the findings as a cited Markdown file in the repo, run as a background agent.
+- **[tdd](./skills/engineering/tdd/SKILL.md)**: Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time.
+- **[domain-modeling](./skills/engineering/domain-modeling/SKILL.md)**: Actively build and sharpen a project's domain model: challenge terms against the glossary, stress-test with edge-case scenarios, and update `GLOSSARY.md` and ADRs inline.
+- **[codebase-design](./skills/engineering/codebase-design/SKILL.md)**: Shared discipline and vocabulary for designing deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface.
+- **[code-review](./skills/engineering/code-review/SKILL.md)**: Two-axis review of the diff since a fixed point: **Standards** (does it follow the repo's coding standards, plus a Fowler smell baseline?) and **Spec** (does it faithfully implement the originating issue/spec?), run as parallel sub-agents so neither pollutes the other.
+- **[pr](./skills/engineering/pr/SKILL.md)**: The shape a pull request body should take: a summary as the smallest visual that makes the change clear, before/after evidence that it works, and a merge-danger call (one-way or two-way door, plus blast radius).
+- **[wizard](./skills/engineering/wizard/SKILL.md)**: Generate an interactive bash wizard that walks a human through steps only they can perform: provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover.
+
+### Productivity
+
+General workflow tools, not code-specific.
+
+**User-invoked**
+
+- **[grill-me](./skills/productivity/grill-me/SKILL.md)**: Get relentlessly interviewed about a plan or design until every branch of the design tree is resolved.
+- **[handoff](./skills/productivity/handoff/SKILL.md)**: Compact the current conversation into a handoff document so another agent can continue the work.
+- **[teach](./skills/productivity/teach/SKILL.md)**: Teach the user a new skill or concept over multiple sessions, using the current directory as a stateful teaching workspace.
+- **[to-questionnaire](./skills/productivity/to-questionnaire/SKILL.md)**: Turn a decision you can't answer alone into a Markdown questionnaire for the one person who can, filled in async, or together over a meeting. It grills you about the send (who it's for, what you need back), not the subject.
+- **[wait-what](./skills/productivity/wait-what/SKILL.md)**: Fire this the moment a message doesn't land. The agent re-pitches it with the context you're missing, in plain English, using your `GLOSSARY.md` vocabulary.
+
+**Model-invoked**
+
+- **[grilling](./skills/productivity/grilling/SKILL.md)**: Interview the user relentlessly about a plan, decision, or idea until every branch of the design tree is resolved. The reusable interview primitive behind `grill-me`, `grill-with-docs`, `triage`, `wayfinder` and `improve-codebase-architecture`.
+- **[writing-for-agents](./skills/productivity/writing-for-agents/SKILL.md)**: Writing documents for agents: skills, AGENTS.md/CLAUDE.md, and any doc an agent reaches by a pointer.

package/skills/mattpocock/SCOPE.md

@@ -0,0 +1,35 @@
+# Scope
+
+This repo is the set of skills I use every day. It is curated: ideas are welcome, and each one is judged against the bar below. Issues are for tracking changes to the skills. Questions and discussion go to [GitHub Discussions](https://github.com/mattpocock/skills/discussions).
+
+## The bar
+
+An idea or feedback issue stays open only if it clears **both** parts:
+
+1. **Observed failure.** It describes something that went wrong in a real session: what you ran, what the skill did, what you expected. A hypothetical improvement ("it would be better if...") does not clear this part.
+2. **Fits the philosophy.** It does not match anything in [`.out-of-scope/`](./.out-of-scope/) or a past rejection, and it is not a config option, a harness-specific branch, or a tweak to suit one person's workflow. Those belong in your own `CLAUDE.md` / `AGENTS.md`, or in a fork (skills.sh gives you an editable copy).
+
+Size is irrelevant: a one-word fix and a rewrite face the same bar. Reactions and +1 comments do not count towards it.
+
+## By bucket
+
+- **`engineering/`, `productivity/`, `in-progress/`**: the bar above.
+- **`misc/`**: frozen and unmaintained. Every issue is closed. See [`frozen-misc-skills.md`](./.out-of-scope/frozen-misc-skills.md).
+- **New skills**: proposals and contributions are closed. If the behaviour composes from existing skills, it does not get a new one. See [`new-skills.md`](./.out-of-scope/new-skills.md).
+
+## Already decided
+
+Each file in [`.out-of-scope/`](./.out-of-scope/) records one rejected concept and why. Read them before filing:
+
+- [`frozen-misc-skills.md`](./.out-of-scope/frozen-misc-skills.md)
+- [`harness-name-collisions.md`](./.out-of-scope/harness-name-collisions.md)
+- [`mainstream-issue-trackers-only.md`](./.out-of-scope/mainstream-issue-trackers-only.md)
+- [`native-question-tool.md`](./.out-of-scope/native-question-tool.md)
+- [`new-skills.md`](./.out-of-scope/new-skills.md)
+- [`question-limits.md`](./.out-of-scope/question-limits.md)
+- [`setup-skill-verify-mode.md`](./.out-of-scope/setup-skill-verify-mode.md)
+- [`subagent-recursion.md`](./.out-of-scope/subagent-recursion.md)
+
+## Unclear issues
+
+An issue that can't be judged against the bar gets one round of questions and the `needs-info` label. With no reply from the reporter in 14 days, it is closed. Rejections close as "not planned".

package/skills/mattpocock/docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Judge every issue against [`SCOPE.md`](../../SCOPE.md) before picking a state. Rejections close as "not planned".