Azldev Agent Skill

Using azldev

azldev builds a Linux distribution from TOML configuration. It imports RPM specs

from an upstream distro and customizes them with an overlay system — no spec

forking. Components render to specs and sidecar build inputs, then build into RPMs;

images assemble RPMs into bootable artifacts.

Orient yourself

• Run azldev from the repo root (where azldev.toml lives), or pass -C <dir>.
• Global, agent-friendly flags: -q (quiet) and -O json (machine-readable

output). They work on every command.

• Config is a stitched TOML hierarchy: azldev.toml includes the distro and project

config, which include the component files (**/*.comp.toml) into one namespace.

Core concepts

• Component — a unit of packaging that renders to a spec and sidecar build inputs,

then builds into one or more RPMs. Its spec source is upstream (default), a pinned

upstream distro/version, or a local spec.

• Overlay — a semantic patch applied to a spec or source file at render time, so

you customize upstream without forking it.

• Distro — a named build target (*.distro.toml) with upstream URIs, release

versions, and build inputs.

• Rendered spec — the generated .spec after overlays; a build input, never

hand-edited.

• Lock — a per-component file pinning the resolved upstream commit and an input

fingerprint.

Common commands

Top-level commands in this build:

• azldev completion — Generate the autocompletion script for the specified shell
• azldev component — Manage components
• azldev config — Manage tool configuration
• azldev docs — Documentation commands
• azldev image — Manage Azure Linux images
• azldev package — Manage binary package configuration
• azldev project — Manage Azure Linux projects
• azldev repo — Inspect and manage RPM repositories
• azldev version — Print the CLI version

Everyday tasks (add -q -O json when scripting):

| Task | Command |

| --- | --- |

| List components | azldev comp list -a |

| Inspect one component | azldev comp list -p <name> |

| Add a component | azldev comp add |

| Build a component | azldev comp build -p <name> |

| Render specs | azldev comp render -p <name> (or -a) |

| Refresh a lock | azldev comp update -p <name> |

| List / build images | azldev image list / azldev image build |

comp is an alias for component. Always confirm current syntax with

azldev <command> --help.

The hidden advanced group (adv) contains specialist integrations such as MCP and

mock helpers; it is intentionally omitted from normal help.

Where to go next

• Add a new component — read the azldev-add-component skill.
• Edit or review a component's TOML — read the azldev-comp-toml skill.
• Add or change overlays — read the azldev-overlays skill.
• Build, iterate, and debug a component — read the azldev-build-component skill.
• Build, boot, and register images — read the azldev-image skill.
• Refresh a lock and finalize for a PR — read the azldev-update-component skill.
• Remove a component — read the azldev-remove-component skill.
• Test built RPMs in a chroot — read the azldev-mock skill.

Golden rules

• Never edit generated output — rendered specs and the output/work/log dirs are

produced by azldev. Change the source config and re-render.

• Re-run azldev comp update before opening a PR — the lock fingerprint covers

the whole component config, and lock / rendered-spec CI checks run on committed state.

• Every overlay needs a description explaining why the change is needed.

Generated by azldev docs agent; do not hand-edit. Generated for azldev version v0.1.0.