OpenParable
Skip to content
← Back to skills

Skill Fix Overlay

Testing & Quality
skill-fix-overlay

Skill Fix Overlay is an Agent Skill for testing & quality published in the microsoft/azurelinux repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

[Skill] Diagnose and fix overlay issues in Azure Linux components. Use when overlays fail to apply, produce unexpected results, or need debugging. Triggers: overlay error, fix overlay, overlay not applying, spec-search-replace failed, overlay debug.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/microsoft/azurelinux/blob/HEAD/.github/skills/skill-fix-overlay/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/skill-fix-overlay, 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.

Fix an Overlay

Diagnosis Workflow

1. Render and inspect

The fastest way to check if overlays apply cleanly:

azldev comp render -p <name>
# Inspect the result
cat specs/<first-char>/<name>/<name>.spec

If render fails, the error message will identify which overlay failed and why.

2. Diff pre/post overlay (deep debug)

When you need to understand exactly what upstream provides vs. what overlays change:

Use a temp dir for prep-sources output. Use --force to 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

3. Inspect the upstream spec/sources

Look at the pre-overlay output dir — this is what the overlay is trying to modify. Common root cause: upstream changed and the overlay's assumptions no longer hold.

Common Failures

spec-add-tag: "tag already exists"

The tag is already in the upstream spec. Fix: use spec-set-tag (replaces value if exists, adds if not) or spec-update-tag (replaces value, but fails if tag doesn't exist — use when you want to guarantee the tag was already present) instead.

spec-search-replace: no match

The regex doesn't match anything in the spec. Causes:

  • Upstream changed the line (check <pre-dir>/<name>.spec)
  • Regex escaping issues — TOML basic strings need \\ for literal backslash
  • Use TOML literal strings ('...') to avoid escaping: regex = 'RPM_VENDOR=redhat'
  • No multi-line regex — (?s)/DOTALL is not supported. Use multiple targeted single-line replacements instead.

spec-*-lines: section not found

The spec section (%prep, %build, %install, etc.) doesn't exist or has different casing. Check the actual section names in <pre-dir>/<name>.spec.

file-*: file not found

The file doesn't exist in the upstream sources. Check ls <pre-dir>/ for actual filenames. Globs (**/*) are supported for file-search-replace.

Overlay applies but build still fails

The overlay applied cleanly but the result is wrong. Compare <post-dir>/<name>.spec against what you expect. Common issues:

  • Regex matched more/fewer lines than intended (try to avoid regex, they are brittle)
  • Replacement introduced syntax errors in the spec
  • Missing dependency that the overlay was supposed to add

For overlay type reference (all 12 types with key fields), see comp-toml.instructions.md. Full schema: azldev.schema.json.

Tips

  • Test incrementally. Apply one overlay at a time and verify with prep-sources. Debugging 10 overlays at once is painful.
  • Minimize overlays. Each is a potential failure point. Prefer the smallest delta from upstream.
  • Verify in chroot. If overlays apply but the build still fails, use skill-mock to inspect the build environment.
  • Follow the inner loop. The full cycle is: investigate → modify → render → build → test → inspect. See skill-build-component for details.
  • Smoke-test after fixing overlays. A clean apply and successful build don't guarantee working RPMs. See skill-mock.