← Back to docs

Start

Getting started

Preview and install Oh My QEMU skills locally, then prepare an auditable QEMU workspace.

Oh My QEMU provides 19 independently installable skills for local QEMU research, modeling, build, boot, debug, qtest, and documentation work.

Run this command from the QEMU repository root. It downloads the skill source through npx and installs all 19 skills into project-local Codex and Claude Code without a selection prompt or a manual Oh My QEMU clone:

curl -fsSL https://raw.githubusercontent.com/processmission/oh-my-qemu/main/install.sh | bash

The installer is always project-local and rejects global flags. After the skill install succeeds, it idempotently adds .agents/, .claude/skills/, .oh-my-qemu/, builds/, and the generated skills-lock.json to the repository-local Git exclude, preserving existing entries and deduplicating slash variants. It does not modify the shared .gitignore. Linked worktrees that use one Git common directory share the exclude file.

The installer stops before making changes if the target already tracks .agents/skills/, .claude/skills/, or skills-lock.json, because local Git exclude rules cannot hide modifications to tracked files.

The lockfile remains available locally for updates but does not appear in git status.

Optional contributor installation

Skill developers and contributors can clone Oh My QEMU and install their local working tree into a specific QEMU checkout:

git clone https://github.com/processmission/oh-my-qemu.git
cd oh-my-qemu
./install.sh --target /path/to/qemu

This installs all 19 skills from the cloned working tree, including local changes. To install only one skill:

./install.sh --target /path/to/qemu --skill qemu-build

Preview the catalog without installing anything:

npx skills add https://github.com/processmission/oh-my-qemu -l

Direct npx skills add remains available as a lower-level path, but it does not perform the repository-local Git exclude setup.

Verify the installation

From the target repository root:

ls .agents/skills | grep '^qemu-'
ls .claude/skills | grep '^qemu-'

Then confirm the agent lists the qemu-* skills in the current session. If a skill is missing, record the gap in audit.md instead of substituting memory for its rules, and reinstall. If an older oh-my-qemu plugin or user-level symlinks are still present, disable the plugin and remove the dangling links before installing project-locally; the installer does not delete them.

Start a task

For a non-trivial task that writes to a QEMU workspace, create only the entries you need under:

.oh-my-qemu/<task-slug>/
├── audit.md
├── commands.md
├── logs/
├── scripts/
└── output/

Use scripts/ for temporary probes, parsers, and harnesses. Use output/ for generated deliverables, downloaded dependency artifacts, and non-QEMU build binaries. Record scope, sources, decisions, and verification in audit.md, and reproducible commands and results in commands.md.

Run workspace gates

When qemu-workflow is installed, its gate library checks the hard rules and prints PASS/FAIL lines:

bash .agents/skills/qemu-workflow/scripts/gates.sh --help
bash .agents/skills/qemu-workflow/scripts/gates.sh exclude
bash .agents/skills/qemu-workflow/scripts/gates.sh workspace .oh-my-qemu/<task-slug>
bash .agents/skills/qemu-workflow/scripts/gates.sh audit .oh-my-qemu/<task-slug>/audit.md
bash .agents/skills/qemu-workflow/scripts/gates.sh round-result .oh-my-qemu/<task-slug>/output/round-result.md
bash .agents/skills/qemu-workflow/scripts/gates.sh handoff .oh-my-qemu/<task-slug>/audit.md

Use the gate output as evidence in audit.md; a failing gate is a blocker, not a warning. The script is self-contained, so it runs even when the other skills are unavailable.

Register extraction ships a text semantic IR. Validate it, dump the canonical form for the audit record, or list the allowed vocabulary:

python3 .agents/skills/qemu-register-extraction/scripts/validate_register_ir.py     .oh-my-qemu/<task-slug>/output/register-semantics.ir
python3 .../validate_register_ir.py --dump     .oh-my-qemu/<task-slug>/output/register-semantics.ir
python3 .../validate_register_ir.py --translate .oh-my-qemu/<task-slug>/output/register-semantics.ir
python3 .../validate_register_ir.py --list-ops

The translation worklist maps each rule to its QEMU mechanism (RegisterInfo, manual MMIO, or an unimplemented-device placeholder) plus trace/log/error and qtest requirements. The modeling skills expand it into implementation.

Build QEMU by target

QEMU’s own build output belongs in the source-root builds/ directory:

mkdir -p builds/build-aarch64
cd builds/build-aarch64
../../configure --target-list=aarch64-softmmu
ninja

Use a distinct name such as builds/build-riscv64/ or builds/build-aarch64-debug/ for every target or configuration. Never place a QEMU build in build/ or the task’s output/ directory.