[azure.ai.skills] `azd ai skill update --file` should accept `.zip` archives and directories (parity with `create`)

[lindazqli]

Summary

azd ai skill create --file accepts three input shapes — a SKILL.md file, a .zip archive, or a directory containing a SKILL.md at its root (the directory mode was added in #8431). azd ai skill update --file, however, accepts only a single .md file. Both .zip and directory inputs are explicitly rejected:

$ azd ai skill update my-skill --file ./pkg.zip
ERROR: ZIP packages cannot be applied via `skill update`
Suggestion: use `azd ai skill create <name> --file <path>.zip --force` to replace the skill (this deletes the existing skill and all of its versions first)

$ azd ai skill update my-skill --file ./skill-folder
ERROR: directory uploads cannot be applied via `skill update`
Suggestion: use `azd ai skill create <name> --file <directory> --force` to replace the skill (this deletes the existing skill and all of its versions first)

The current update --help text confirms this is by design:

--file string Path to a SKILL.md file whose values become the next version's inline content

ZIP packages are not accepted here. To replace the entire skill (deleting all existing versions), use azd ai skill create <name> --file <archive>.zip --force.

Why this matters

The documented workaround — azd ai skill create <name> --file <zip-or-dir> --force — is destructive: --force deletes the skill (and every prior version) before recreating it. The whole point of update is to add a new immutable version while preserving history; the workaround throws history away.

Concrete consequences today:

1. Authors who package skills as folders or zips lose version history on every iteration. If a skill ships as a multi-file bundle (e.g. SKILL.md + supporting prompts/assets that the runtime expects), the only way to publish a v2 is to create --force, which deletes v1. --set-default-version <prev> rollback stops being possible.
2. It splits the mental model. create says "files, folders, and zips are all valid skill sources"; update says "only .md". Users naturally try the same input shape they used for create and hit a hard error.
3. It blocks CI / GitOps flows. A pipeline that builds dist/my-skill/ and pushes new versions has to either (a) zip-then-update (rejected), (b) pass the directory to update (rejected), or (c) create --force (loses history). Today there is no non-destructive option.

Proposed behavior

Make azd ai skill update --file accept the same three shapes as create --file:

Input	create --file	update --file (today)	update --file (proposed)
SKILL.md (or any .md)	✅	✅	✅ (unchanged)
.zip archive containing SKILL.md at root	✅	❌	✅ (new — creates next version from archive)
Directory containing SKILL.md at root	✅ (#8431)	❌	✅ (new — creates next version from directory)
Inline --description / --instructions	n/a	✅	✅ (unchanged)
--set-default-version <ver>	n/a	✅	✅ (unchanged)

Semantics for the new modes should mirror create:

• Validate the archive/directory contains a SKILL.md at its root (same preflight error as create: "--file <path> is a directory without a SKILL.md at its root").
• Upload the full bundle as the next immutable version.
• Promote the new version to default_version (current update behavior).
• Preserve all prior versions — never delete-and-recreate. --force should remain a create-only flag.

Suggested help-text update

--file string  Path to a SKILL.md file, a .zip archive, or a directory whose
               contents become the next version. Archives and directories must
               contain a SKILL.md at the root.

…and drop the "ZIP packages are not accepted here" sentence.

Repro

Tested with azure.ai.skills 0.0.1-preview-local built from Azure/azure-dev@5e8b3b9c (PR #8431 included), against a Foundry project. Full matrix:

# Seed v1
azd ai skill create upd-probe --file ./seed.md --no-prompt

# A) update --file alt.md         → ✅ v2 created
# B) update --file not-md.txt     → ❌ unsupported --file extension ".txt"
# C) update --file ./dirX         → ❌ directory uploads cannot be applied via `skill update`
# D) update --file ./upd.zip      → ❌ ZIP packages cannot be applied via `skill update`

Workaround today

azd ai skill create <name> --file <zip-or-directory> --force — destructive, loses version history.

Related

• fix(skills): accept directory uploads on azd ai skill create #8431 — added directory support to skill create --file