面向 AI agent 的 RustSBI 与 Rust 裸机开发 skills，覆盖 Boot ROM 行为分析、
寄存器层、embedded-hal 实现层、USB device-controller 后端、芯片启动运行时
和 RustSBI 贡献规范。
每个 skill 都自包含在 skills/<skill-name>/ 中，可以独立安装和按需加载。
仓库不发布 agent 插件格式；skill 内的 agents/openai.yaml 仅提供可选的
展示元数据。
| Skill | 职责 | 典型任务 |
|---|---|---|
bootrom-analysis |
从已取得且获授权的 Boot ROM 工件或公开资料恢复分级标注的启动行为证据 | 命令行分析、入口与控制流、启动介质回退、镜像解析、信任决策、固件交接 |
embedded-registers |
裸机 PAC/手写 MMIO、寄存器布局、位域、volatile、所有权、unsafe、时钟复位和并发访问 |
从手册建立 register block、评审 W1C/RMW、验证地址与 offset |
embedded-hal-authoring |
在已核验的寄存器层之上设计、实现、迁移或评审 Rust HAL | GPIO typestate、I2C/SPI/UART/PWM、embedded-hal 1.0、async、DMA、错误与测试 |
usb-device-authoring |
从已验证寄存器层与 HAL-owned peripheral 完整实现或评审 usb-device controller backend |
UsbBus、端点分配、FIFO/PMA/DPRAM/QH-TD、EP0、poll/IRQ、reset/suspend、DMA/cache、示例与 HIL |
embedded-runtime |
实现或评审厂商/SoC 的 *-rt 启动 crate |
ROM header、entry、linker script、栈、.bss/.data、trap/interrupt、多核与特权级 |
contribute-to-rustsbi |
准备或评审符合 RustSBI 规范的原子 commit 与英文 commit message | scope/type、正文与 footer、DCO sign-off、模块 CHANGELOG、PR 前历史检查 |
原来的 embedded-hal-skills 已拆分，不再作为可安装入口。
embedded-hal-authoring 取代了含糊的 embedded-hal-impl：它既覆盖新实现，
也能正确触发设计、迁移、重构和代码评审任务。
usb-device-authoring 聚焦 usb-device 下方的设备控制器适配；CDC、HID、
MIDI、DFU、MSC 等可移植 class/protocol 以及 USB Host 不属于它的职责。
authorized Boot ROM artifact/public evidence verified datasheet / SVD
│ │
▼ ▼
bootrom-analysis ── behavior hypotheses ──► embedded-registers
│ register layout and access semantics
│ handoff hypotheses │
▼ ▼
embedded-runtime embedded-hal-authoring
reset-to-entry, linker safe peripheral APIs and ecosystem traits
│ │
│ USB peripheral ownership,
│ clocks, pins and interrupts
│ ▼
│ usb-device-authoring
│ controller backend / UsbBus
│ │
└──────── depends on or reuses HAL types ───┤
▼
USB classes / application / BSP
bootrom-analysis 负责从已取得且获授权的工件或公开资料建立带置信度的行为与交接假设，
不负责获取 ROM 或破解读取保护，也不把推断直接当成硬件合同。四个实现类硬件 skill
的边界是职责边界，不要求项目拆成四个 crate。
寄存器层可以位于 PAC、HAL 内部模块或独立 crate；厂商 runtime 可以依赖 HAL 并在
entry 处交付 Peripherals/Clocks，但 HAL 不应反向依赖 runtime。
USB controller backend 可以位于 HAL 内部或独立 crate；它消费 HAL 提供的 owned
USB structure（由后者封装外设、引脚、时钟、复位和中断所有权），并由上层
usb-device classes 使用。若该结构缺失，先交给 embedded-hal-authoring 补齐。
contribute-to-rustsbi 与代码分层正交：在整理 RustSBI 社区仓库的 commit、
commit message、sign-off、CHANGELOG 或 PR 前历史时按需加载。
列出仓库内可安装的 skills：
npx skills add https://github.com/rustsbi/skills -l安装单个 skill：
npx skills add https://github.com/rustsbi/skills --skill bootrom-analysis
npx skills add https://github.com/rustsbi/skills --skill embedded-registers
npx skills add https://github.com/rustsbi/skills --skill embedded-hal-authoring
npx skills add https://github.com/rustsbi/skills --skill usb-device-authoring
npx skills add https://github.com/rustsbi/skills --skill embedded-runtime
npx skills add https://github.com/rustsbi/skills --skill contribute-to-rustsbi也可以克隆仓库后，将对应 skills/<skill-name>/ 目录交给支持 SKILL.md
的 agent。每个目录都不依赖仓库根部或其他 skill 才能使用。
三套通用裸机实现知识库基于以下固定 revision 的源码调研，并将证据写成 仓库相对路径：
| 仓库 | Revision |
|---|---|
allwinner-hal |
411a407fd82e5c74ef73495c41c48eb4570dafe2 |
artinchip-hal |
36cab1c216c3ff15487c523a7521acdc207903c1 |
bouffalo-hal |
d012f3b007f855915f5fccc35baab30ea9344012 |
kendryte-hal |
5913401ba870e3696d1923f0d6c36cdfafc3b58d |
sophgo-hal |
9dc3af14dcb142bd37e3e25815298e9a43164eb4 |
USB skill 以 usb-device v0.3.2
（6a44a84166f2e3799a14fbb30e8f9fc0f08b54d3）为稳定合同基线，同时记录
开发分支 5d6c437e0e4b51b2c18d7f211f8f219883c3c366 的不兼容变化。控制器实现
调研固定在以下 revision：
| 仓库 | Revision | 控制器模型 |
|---|---|---|
atsam4-hal |
ccab739370d505e340b770a31d5274bfc35ea4a9 |
CSR + 片上 FIFO |
atsamd |
2fada02fee9559da464c17fecb42896a020fe821 |
RAM bank descriptor |
imxrt-usbd |
c7ec679b0091adf5607132eab7353425550c5ec4 |
QH/TD DMA |
musb |
49503a0d4c51723a66158ec1db8b2d476f6fc592 |
indexed FIFO |
rp2040-hal |
ee271c814aacd22d5b8f2802220a41b94376db76 |
4 KiB DPRAM |
stm32-usbd |
f60818e0081593298c86ea8eb0bdaae99252241c |
PMA + BTABLE |
调研覆盖 register/MMIO、HAL traits、ownership/typestate、blocking/async/DMA、 runtime/linker/entry/trap、USB 端点/EP0/事件/内存模型、测试和 CI。项目实践 不等同于官方合同；各 skill 会按任务适用范围区分以下证据层次：
- 当前 trait、ABI 或架构文档要求的 CONTRACT；
- 目标芯片手册、datasheet 或 errata 给出的 HARDWARE FACT；
- Rust Embedded 官方资料给出的 GUIDELINE；
- 固定源码快照中观察到、需要结合目标硬件重新判断的 PROJECT PRACTICE；
- 尚待文档或实测确认的 ASSUMPTION。
源码和文档不保存本地 checkout 绝对路径、shell 登录信息或私网地址。
Boot ROM 分析 skill 只保存通用方法、证据分级和公开前脱敏规则，不保存真实镜像、 反汇编、地址、密钥、目标身份、漏洞路径或任何具体逆向结论。
贡献规范 skill 依据 RustSBI 的
Contributing to RustSBI
整理，并要求使用时优先核对目标仓库中更新的本地规则与近期 commit 历史。
python3 scripts/validate_project.py
cargo fmt --manifest-path skills/embedded-hal-authoring/examples/Cargo.toml -- --check
cargo check --manifest-path skills/embedded-hal-authoring/examples/Cargo.toml --all-targets
cargo clippy --manifest-path skills/embedded-hal-authoring/examples/Cargo.toml --all-targets -- -D warnings
cargo test --manifest-path skills/embedded-hal-authoring/examples/Cargo.toml --all-targets项目校验会检查：
- 仅存在六个规范 skill；
- frontmatter、
agents/openai.yaml和本地链接合法； - 所有 reference 都能从本 skill 的
SKILL.md直接发现； - skill 不依赖仓库外或 sibling skill 的文件；
- 没有 scaffold、插件入口或隐私信息残留。
真实 HAL/runtime/USB backend 还应执行目标交叉编译、ELF/map/section 检查、 USB 枚举与硬件 smoke/HIL test。 不要从任何示例猜测寄存器地址、reset value、位定义、内存图或 ROM ABI。
本项目按使用者选择，以 MIT License 或 MulanPSL 2.0 双重许可发布。