Official agent skill

Azldev Overlay Metadata

by microsoft in microsoft/azurelinux

Read this before adding or reviewing an overlay metadata table; do not guess the category or upstream status from memory.

OfficialMITAuto-check passed

Install Azldev Overlay Metadata

skills CLI
$ npx skills add microsoft/azurelinux --skill azldev-overlay-metadata -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install microsoft/azurelinux azldev-overlay-metadata --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/microsoft/azurelinux.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/azldev-overlay-metadata .claude/skills/azldev-overlay-metadata && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
azldev-overlay-metadata
GitHub stars
5.3k
Token cost
~2.6k tokens
SKILL.md length
1,120 words
Files
1
Skills in repo
10
Repo updated
First seen
Licence
MIT

At a glance

Read this before adding or reviewing an overlay metadata table; do not guess the category or upstream status from memory.

  • Works in 5 steps: Pick the category → Set upstream-status → Add provenance (commits, bugs) → …
  • Include overlay metadata
  • SKILL.md covers One [metadata] block = one…, When to add metadata, Step 1 — Pick the category and Step 2 — Set upstream-status, plus 3 more sections
  • Calls git; reaches src.fedoraproject.org

What it does

Azldev Overlay Metadata is an agent skill from microsoft/azurelinux, published by the product's own GitHub organization. Read this before adding or reviewing an overlay metadata table; do not guess the category or upstream status from memory. Explains the overlay metadata schema that documents why an overlay exists and when it can be dropped, covering the required category and upstream-status values, commit/bug URL references, and the per-file overlay metadata block. Triggers include overlay metadata, category, upstream-status, upstream-backport, azl-pruning, azl-branding-policy, needs-upstream-hook, why overlay.

Its SKILL.md is about 2.6k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

The repository describes itself as: General purpose Linux OS for Azure. The licence is MIT.

When your agent uses it

  • Include overlay metadata
  • Upstream-status
  • Upstream-backport
  • Azl-branding-policy

Example prompts

  • “/azldev-overlay-metadata”

Workflow steps

5 steps, taken from the step headings in SKILL.md.

  1. Pick the category
  2. Set upstream-status
  3. Add provenance (commits, bugs)
  4. Write the metadata (TOML forms)
  5. Verify

What it can do on your machine

Read from SKILL.md and the folder at commit f019108. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Hosts in commands or code, which the agent is likely to contact:

    • src.fedoraproject.org

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Azldev Overlay Metadata loads about 2.6k tokens when it runs. Until then it costs about 131 tokens; SKILL.md has 1,120 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~131
When it runs · the whole SKILL.md, loaded when a task matches
~2.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from microsoft/azurelinux at commit f019108, republished under its MIT licence (© microsoft). 1,120 words, ~2,560 tokens.

Download SKILL.mdSave it as .claude/skills/azldev-overlay-metadata/SKILL.md (or your agent's skills folder).
name
azldev-overlay-metadata
description
Read this before adding or reviewing an overlay `metadata` table; do not guess the category or upstream status from memory. Explains the overlay metadata schema that documents why an overlay exists and when it can be dropped, covering the required category and upstream-status values, commit/bug URL references, and the per-file overlay metadata block. Triggers include overlay metadata, category, upstream-status, upstream-backport, azl-pruning, azl-branding-policy, needs-upstream-hook, why overlay.

Overlay metadata — pick a category and annotate

Every overlay documents why it exists (description, required) and what class of change it is (metadata). When a [metadata] block is present it requires both a category and an upstream-status. This skill covers how to pick the right values, attach provenance, and write the TOML at the moment you author or review an overlay.

Metadata is pure documentation — it never changes the rendered spec and is excluded from component fingerprints, so adding or editing it never invalidates build caches or locks. For overlay types and the render-and-inspect loop, read the azldev-overlays skill; this skill is only about the metadata table.

One [metadata] block = one logical change

A single logical change (a CVE backport, a feature disablement, a Fedora cherry-pick) may need several overlays — e.g. remove a sub-package and drop the configure flags that went with it. The per-file overlay format (overlay-files) captures exactly this: one top-level [metadata] table and one or more [[overlays]] entries it applies to. Per-overlay metadata inside an overlay file is rejected — the file-level block is the single source of truth.

So: if you find yourself stamping the same metadata on several inline overlays, that is a signal they are one logical change — move them into a single overlay file with one [metadata] block.

When to add metadata

  • New overlay (any inline [[components.<name>.overlays]] block or [[overlays]] entry in an overlay file): add metadata with both a category and an upstream-status.
  • An overlay's intent changed (e.g. a prune becomes a backport): update the category and upstream-status to match the new intent.

Step 1 — Pick the category

Choose exactly one category from this closed set (authoritative — matches metadata.category in the schema):

categoryUse when the overlay…Extra required/expected fields
upstream-backportBackports a fix from an upstream source (Fedora dist-git or the component's OSS project) that AZL will inherit once it bumps past the fix. Self-resolves on version bump.commits (≥1 upstream commit URL) — required. upstream-status must be upstreamed or upstreamable.
azl-pruningRemoves content for AZL: unshipped deps, unneeded features, sub-packages, or files.—
azl-compatibilityAdapts a component to how Azure Linux is built and shipped — build tooling, buildroot, infrastructure, runtime ecosystem — when upstream builds/behaves incorrectly for AZL-specific reasons that are not branding, a missing dependency, architecture, or tests (e.g. azldev downloader quirks, rpmdiff reproducibility, buildroot gaps, Fedora version-skew).—
azl-temp-workaroundTemporary workaround explicitly intended to be dropped once an upstream or environmental fix lands. Covers a dependency not yet imported into AZL (or unavailable on a target) and any other transient workaround waiting on an external change.—
azl-branding-policyFedora→Azure Linux identity differences: intentional name/path/vendor conventions and spec fixes for upstream code that hard-codes Fedora identity strings (e.g. _vendor=redhat, <cpu>-redhat-linux[-gnu] triples, redhat-linux-build dirs). Also covers repointing a Source/URL tag from a Fedora mirror to an Azure Linux one (e.g. azurelinux-rpm-config, golang).—
azl-disable-flaky-testsSkips tests that fail intermittently / due to environmental flakiness, not a real component bug.—
azl-disable-unsupported-testsSkips tests that cannot meaningfully run in AZL's build/runtime env (need network, root, or unavailable hardware in mock).—
azl-security-complianceMakes FIPS or crypto-policy changes.—
azl-release-managementAdjusts release-tag / changelog mechanics.—
azl-platform-adaptationMakes architecture-specific adjustments.—
Disambiguation tips
  • Backport vs. compatibility/pruning: if the exact change exists as a commit in Fedora dist-git or the upstream project, it is upstream-backport (supply commits, with upstream-status of upstreamed or upstreamable). Use an azl-* category only when the change is AZL-specific with no upstream equivalent.
  • Pruning vs. temp-workaround: removing a dependency we deliberately don't ship is azl-pruning; temporarily working around a dep that should exist but hasn't been imported yet (or any transient workaround waiting on an external fix) is azl-temp-workaround.
  • Flaky vs. unsupported tests: flaky = the test could pass but is intermittent; unsupported = the test cannot run in mock (network/root/hardware). Require evidence of the limitation before choosing azl-disable-unsupported-tests; investigate or ask when the failure mode is unclear.
  • Compatibility vs. platform-adaptation: reserve azl-platform-adaptation for architecture-specific (%ifarch-style) changes; general toolchain/mock/build-env fixes are azl-compatibility.
Show full SKILL.md (473 more words)Show less

Step 2 — Set upstream-status

Required whenever [metadata] is present. It classifies the overlay's relationship to upstream — "why are we carrying this?" and "what would it take to drop it?" Pick exactly one:

ValueMeaning
upstreamedAlready in Fedora; carried only until AZL bumps past it.
upstreamableThe patch we carry is itself upstream-shaped (or already in the OSS project but not in Fedora yet); the same diff could be sent upstream and plausibly accepted. Link the upstream PR when you can.
needs-upstream-hookAZL-specific change that upstream wouldn't take as-is, but upstream could add a bcond/%if/config knob so we could drop the overlay.
inapplicablePermanent AZL-only deviation with no upstream story (branding, deliberate pruning, enterprise policy).
unknownNot yet assessed. Prefer a definite value; reviewers should push back on unknown before approving.

On an upstream-backport overlay only upstreamed and upstreamable are allowed — any other value is a validation error.

upstreamable vs. needs-upstream-hook: upstreamable means the patch we carry is itself upstream-shaped (send the same diff upstream); needs-upstream-hook means the change is AZL-specific and would not be accepted as-is, but upstream could add a hook that makes patching unnecessary.

Step 3 — Add provenance (commits, bugs)

  • commits — list of { url = "..." } tables pointing at upstream commits (absolute http(s) URLs). Required for upstream-backport; optional elsewhere but valuable whenever a change traces to a specific commit. For one logical change spanning several commits, list them all. Verify each SHA actually exists upstream before recording it — a discovered-and-verified URL is not "inventing" metadata; an unverified guess is.
  • bugs — list of { url = "..." } tables referencing tracker entries. Never fabricate one.

Step 4 — Write the metadata (TOML forms)

Prefer the per-file layout (an overlay file loaded via overlay-files) for all new work — even a component with a single overlay. It keeps category/commits/bugs on their own lines (no inline-table one-line limit) and means a change never has to be reshuffled when it grows a second overlay. One top-level [metadata] table applies to every [[overlays]] entry in the file.

Multi-overlay change (one logical change, several overlays):

toml
# One logical change: drop the devel sub-package AZL does not ship.
[metadata]
category = "azl-pruning"
upstream-status = "inapplicable"

[[overlays]]
description = "Remove the devel sub-package — AZL ships no -devel for this component"
type = "spec-remove-subpackage"
package = "devel"

[[overlays]]
description = "Drop the BuildRequires only the devel sub-package needed"
type = "spec-remove-tag"
tag = "BuildRequires"
value = "some-devel-only-dep"
Inline forms

Use inline metadata only when the component is already inline and you are not restructuring it. A single-line inline table must fit on one line (no lists), so it is limited to one or two scalar fields:

toml
[[components.rpm.overlays]]
description = "Customize RPM vendor to Azure Linux"
type = "spec-search-replace"
regex = "RPM_VENDOR=redhat"
replacement = "RPM_VENDOR=azurelinux"
metadata = { category = "azl-branding-policy", upstream-status = "inapplicable" }

Use the sub-table form whenever you need a list (commits, bugs) or more than a couple of fields:

toml
[[components.xclock.overlays]]
description = "Pass --force to autoreconf so the build survives newer autotools"
type = "spec-search-replace"
regex = "autoreconf -i"
replacement = "autoreconf -fi"

[components.xclock.overlays.metadata]
category = "upstream-backport"
upstream-status = "upstreamed"
commits = [{ url = "https://src.fedoraproject.org/rpms/xclock/c/1e407488" }]

Step 5 — Verify

Adding or editing metadata must be a no-op on the rendered spec. Re-render and confirm there is no diff:

sh
azldev comp render -p <name>
git diff specs/

If you also moved overlays into files, prove the apply order was preserved with azldev comp diff-sources -p <name> before and after — any difference means an overlay changed or the sequence shifted. Metadata-only edits need no rebuild or lock refresh; if you also changed an overlay's behavior, finalize with the azldev-update-component skill.

Generated by azldev docs agent; do not hand-edit.

© microsoft, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/azldev-overlay-metadata of microsoft/azurelinux.

Open the folder on GitHubat commit f019108

Compare with similar skills

Azldev Overlay Metadata next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Azldev Overlay Metadata compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Azldev Overlay Metadata this skillmicrosoft/azurelinux5.3k—~2.6kAutomated safety check: PassMIT
Captions Overlay Rulesheygen-com/hyperframes59k1 repos~1.5kAutomated safety check: PassApache-2.0
Chat Motion Overlay Generatornexu-io/open-design100k—~1.1kAutomated safety check: PassApache-2.0
Manage Openapi Overlaystrycompai/comp2k—~2.8kAutomated safety check: PassApache-2.0
PR Review Community Overlaytractorjuice/arc-kit2.3k—~3.9kAutomated safety check: PassCustom licence
Maestro Overlaycatlog22/maestro-flow564—~4.2kAutomated safety check: NotesNone

Similar skills

  • Captions Overlay Rules

    heygen-com/hyperframes

    Rules for captioning talking-head and launch videos: classify each phrase as drop, rail or embed, and composite captions over the film instead of reserving space.

    59k GitHub starsUsed in 1 repo~1.5k tokens
    Media & CreativeAuto-check passed
  • Turns a chat transcript or screenshot into a configurable animated chat clip, rendered as a Remotion bundle with optional transparency.

    100k GitHub stars~1.1k tokensUpdated today
    Media & CreativeAuto-check passed
  • A skill your agent uses when creating, applying, or validating overlay files including x-speakeasy extensions.

    2k GitHub stars~2.8k tokensUpdated today
    Backend & APIsAuto-check passed
  • PR Review Community Overlay

    tractorjuice/arc-kit

    A skill your agent uses when reviewing a PR to tractorjuice/arc-kit that adds or extends a community jurisdictional overlay (e.g.

    2.3k GitHub stars~3.9k tokensUpdated today
    DevelopmentAuto-check passed
  • Maestro Overlay

    catlog22/maestro-flow

    Create or edit command overlays from natural language, or auto-generate them from workflow deficiency signals

    564 GitHub stars~4.2k tokensUpdated yesterday
    MobileAuto-check: notes
  • Figure Ground Overlays And Modals

    hashgraph-online/awesome-codex-plugins

    Apply figure-ground separation specifically for overlays — modals, dialogs, drawers, popovers, dropdowns, toasts.

    1.2k GitHub stars~2.5k tokensUpdated today
    Auto-check passed

More from microsoft/azurelinux

All 10 skills in this repo
  • Azldev Add Component

    microsoft/azurelinux

    Official

    Read this before adding or importing a component; follow the workflow instead of guessing.

    5.3k GitHub stars~987 tokensUpdated today
    Auto-check passed
  • Azldev Build Component

    microsoft/azurelinux

    Official

    Read this before building a component or diagnosing a build failure; do not guess build flags or the inner loop.

    5.3k GitHub stars~808 tokensUpdated today
    Auto-check passed
  • Azldev Comp Toml

    microsoft/azurelinux

    Official

    Read this before authoring, editing, or reviewing a .comp.toml file; do not work from memory.

    5.3k GitHub stars~1.6k tokensUpdated today
    Auto-check passed
  • Azldev Image

    microsoft/azurelinux

    Official

    Read this before building, booting, or configuring an azldev image.

    5.3k GitHub stars~758 tokensUpdated today
    Auto-check passed
  • Azldev Mock

    microsoft/azurelinux

    Official

    Read this before testing or inspecting a built RPM; do not drive mock by hand from memory.

    5.3k GitHub stars~1k tokensUpdated today
    Auto-check passed
  • Azldev Overlays

    microsoft/azurelinux

    Official

    Read this before adding, changing, or diagnosing any overlay; never edit a spec or rendered file from memory.

    5.3k GitHub stars~2.3k tokensUpdated today
    Auto-check passed

Questions about Azldev Overlay Metadata

What does Azldev Overlay Metadata do?

Read this before adding or reviewing an overlay metadata table; do not guess the category or upstream status from memory. Azldev Overlay Metadata is an agent skill from microsoft/azurelinux, published by the product's own GitHub organization. Read this before adding or reviewing an overlay metadata table; do not guess the category or upstream status from memory.

When should I use Azldev Overlay Metadata?

Azldev Overlay Metadata fits situations like: include overlay metadata; upstream-status; upstream-backport; azl-branding-policy.

How do I install Azldev Overlay Metadata in Claude Code?

Run `npx skills add microsoft/azurelinux --skill azldev-overlay-metadata -a claude-code`. Or copy the skill folder (.agents/skills/azldev-overlay-metadata in microsoft/azurelinux) into .claude/skills/azldev-overlay-metadata in your project. Claude Code loads it when a task matches its description.

How do I install Azldev Overlay Metadata in Codex?

Run `npx skills add microsoft/azurelinux --skill azldev-overlay-metadata -a codex`. Or copy the skill folder (.agents/skills/azldev-overlay-metadata in microsoft/azurelinux) into .agents/skills/azldev-overlay-metadata in your project. Codex loads it when a task matches its description.

Can I use Azldev Overlay Metadata in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add microsoft/azurelinux --skill azldev-overlay-metadata -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/azldev-overlay-metadata, .gemini/skills/azldev-overlay-metadata, .github/skills/azldev-overlay-metadata and .opencode/skills/azldev-overlay-metadata in your project.

What does Azldev Overlay Metadata need to run?

Going by SKILL.md and its folder, Azldev Overlay Metadata needs the command-line tools its instructions call (git).

Does Azldev Overlay Metadata access the network?

SKILL.md names 1 domain. In commands or code: src.fedoraproject.org; the agent is likely to contact it when it follows the instructions. This is read from the text; nothing was executed.

Is Azldev Overlay Metadata safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Azldev Overlay Metadata use?

Azldev Overlay Metadata is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Azldev Overlay Metadata use?

About 2.6k tokens (SKILL.md is roughly 10k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Azldev Overlay Metadata?

Skills that share tags, products or a category with Azldev Overlay Metadata: Captions Overlay Rules (heygen-com/hyperframes, 59k stars), Chat Motion Overlay Generator (nexu-io/open-design, 100k stars), Manage Openapi Overlays (trycompai/comp, 2k stars) and PR Review Community Overlay (tractorjuice/arc-kit, 2.3k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Azldev Overlay Metadata?

microsoft (a GitHub organization, an official publisher) maintains it in microsoft/azurelinux, which has 5,348 GitHub stars. The repository holds 10 skills in this directory. The repository was last updated on October 8, 2026.

Source: microsoft/azurelinux on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.