Skill Add Component
Developmentskill-add-componentSkill Add Component is an Agent Skill for development published in the microsoft/azurelinux repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
[Skill] Add a new component to Azure Linux. Use when importing packages from Fedora, creating comp.toml files, choosing inline vs dedicated definitions, or setting up a new component with overlays. Triggers: add component, new package, import from fedora, create comp.toml.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/microsoft/azurelinux/blob/HEAD/.github/skills/skill-add-component/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/skill-add-component, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Add a Component
Before You Start
# Check if it already exists
azldev comp list -p <name> -q -O json
Inspect the upstream spec first
The fastest way to see what you're working with:
- Add a bare inline entry in
components.toml:[components.<name>] - Pull the spec:
azldev comp prep-sources -p <name> --skip-overlays --force -o base/build/work/scratch/<name> -q - Read the spec, plan your overlays
- Decide if overlays are required, if so: Remove the inline entry, create a dedicated
<name>/<name>.comp.toml
Fedora dist-git is behind bot detection — direct web fetches often fail. Use prep-sources to pull specs reliably.
Note:
prep-sources -owrites to the directory you specify — this is ad-hoc output, separate from the project's configured build output dirs inbase/project.toml.
Decision: Inline vs Dedicated File
Inline (in components.toml) — simple upstream import, no modifications:
[components.jq]
Dedicated file (<name>/<name>.comp.toml) — needs overlays, build config, or local spec:
# <name>/<name>.comp.toml
[components.<name>]
[[components.<name>.overlays]]
description = "Why this change is needed"
type = "spec-add-tag"
tag = "BuildRequires"
value = "some-dependency"
Rule of thumb: if it's more than [components.<name>], give it a dedicated file. The includes = ["**/*.comp.toml"] in components.toml picks it up automatically.
Spec Sources & Overlays
For spec source types, overlay syntax, overlay types, and pitfalls, see comp-toml.instructions.md.
Key points for adding components:
- Every overlay MUST have a
descriptionexplaining why - Test incrementally — apply one overlay at a time, verify with
prep-sources - Prefer targeted overlay types (
spec-add-tag,spec-set-tag) over regex (spec-search-replace) - Keep
%checkenabled — do not disable tests unless there is a documented, unavoidable reason (upstream bug, missing test infra, etc.). If you must disable, provide a clearskip_reason. - Release calculation: If
renderfails with "non-standard Release tag value", or if%autoreleaseis incorrectly expanded (e.g., conditional%autoreleasespecs), see Release Configuration.
Overlays vs. Dedicated spec
Overlays are vastly preferable to maintaining a forked spec, they get automatic updates from upstream and are more resilient to changes. Only fork the spec as a last resort when the required changes are so extensive that overlays become unmanageable. Even then, try to minimize the delta from upstream as much as possible to reduce maintenance burden:
- Clearly document the rationale for each change.
- Add comments to the spec itself for EVERY change (so future maintainers can differentiate local changes vs. upstream drift when version bumps happen).
- Recommend to the user contributing necessary changes upstream to reduce divergence over time, where possible.
Using a forked spec is a commitment to maintain it indefinitely, coordinate with the user to decide if it's truly necessary. Get explicit sign-off from the user before proceeding with a forked spec.
Validate
After adding overlays or customizations, render the spec to verify:
azldev comp render -p <name>
# Inspect the result
cat specs/<first-char>/<name>/<name>.spec
For deeper debugging (diffing pre/post overlay output with full sources):
Use a temp dir for
prep-sourcesoutput. Use--forceto overwrite an existing output dir.
prep-sources -o <dir> writes to a user-specified directory (NOT base/out/ — that's for comp build output).
azldev comp prep-sources -p <name> --skip-overlays --force -o base/build/work/scratch/<name>-pre -q
azldev comp prep-sources -p <name> --force -o base/build/work/scratch/<name>-post -q
diff -r base/build/work/scratch/<name>-pre base/build/work/scratch/<name>-post
# Test build (RPMs land in base/out/ per project.toml output-dir)
azldev comp build -p <name> -q
For testing the built RPMs, see the skill-mock skill. New components always need a smoke-test. For the full inner loop cycle (investigate → modify → render → build → test → inspect), see skill-build-component.