feat(skills): add azd ai skill command group

[huimiu]

Closes #8142. Implements the design from #8204.

Summary

New standalone azure.ai.skills extension exposing azd ai skill create | update | show | list | download | delete.

• create — three mutually exclusive modes: inline (--description + --instructions), SKILL.md (--file *.md), or gzip package (--file *.zip). --force does delete-then-create.
• update — inline flags or --file *.md only; gzip rejected with suggestion to use create --force.
• download — default extracts into ./.agents/skills/<name>/ with two-phase safe extraction (zip-slip guard, no symlinks, 10K-entry / 512 MB caps). --raw keeps the gzip archive.
• delete — confirms by default; --force skips, --no-prompt requires --force.
• Endpoint cascade shares state with azure.ai.agents via read-only fallback to extensions.ai-agents.project.context.endpoint.

Test

• Install ai.skill extension
  

• Create skill
  

• Create skill (create --description X --file Y)
  

• Create skill (zip)
  

• Show skill
  

• List skills
  

• Download skill (no-blob)
  

• Download skill
  

• Update skill
  

• Delete skill (interactive)
  

• Delete skill (--no-prompt, without --force)
  

• Delete skill
  

[github-actions]

📋 Prioritization Note

Thanks for the contribution! The linked issue isn't in the current milestone yet.
Review may take a bit longer — reach out to @rajeshkamal5050 or @kristenwomack if you'd like to discuss prioritization.

[Copilot]

Pull request overview

Adds a new first-party azure.ai.skills azd extension that exposes the standalone azd ai skill command group for managing Foundry Skills from the terminal, including endpoint resolution, typed REST client calls, SKILL.md parsing, and safe package download/extraction.

Changes:

• Introduces the azd ai skill Cobra command tree (create|update|show|list|download|delete) with structured errors and output formatting.
• Adds a typed Skills data-plane REST client plus SKILL.md parsing and archive handling helpers (including “safe extract”).
• Adds extension packaging/build assets (extension.yaml, versioning, build scripts, lint config, and docs).

Reviewed changes

Copilot reviewed 42 out of 43 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
cli/azd/extensions/azure.ai.skills/version.txt	Initial extension version.
cli/azd/extensions/azure.ai.skills/README.md	Extension overview, command surface, endpoint resolution, dev workflow.
cli/azd/extensions/azure.ai.skills/main.go	Extension binary entry point.
cli/azd/extensions/azure.ai.skills/internal/version/version.go	Build-time version variables.
cli/azd/extensions/azure.ai.skills/internal/pkg/skill_api/skill_md.go	SKILL.md YAML-front-matter + body parser.
cli/azd/extensions/azure.ai.skills/internal/pkg/skill_api/skill_md_test.go	Unit tests for SKILL.md parsing.
cli/azd/extensions/azure.ai.skills/internal/pkg/skill_api/models.go	Public/CLI JSON models + wire conversions.
cli/azd/extensions/azure.ai.skills/internal/pkg/skill_api/client.go	Typed REST client for Skills (create/update/get/list/download/delete).
cli/azd/extensions/azure.ai.skills/internal/pkg/skill_api/client_test.go	Client request/response behavior tests via httptest server.
cli/azd/extensions/azure.ai.skills/internal/pkg/skill_api/archive.go	Archive format detection + safe extraction implementation.
cli/azd/extensions/azure.ai.skills/internal/pkg/skill_api/archive_test.go	Tests for safe extraction and validation limits.
cli/azd/extensions/azure.ai.skills/internal/pkg/skill_api/archive_peek.go	ZIP SKILL.md name peek helper for --force safety checks.
cli/azd/extensions/azure.ai.skills/internal/pkg/skill_api/archive_peek_test.go	Tests for archive name peek behavior.
cli/azd/extensions/azure.ai.skills/internal/exterrors/errors.go	Structured error helpers and Azure SDK error conversion.
cli/azd/extensions/azure.ai.skills/internal/exterrors/codes.go	Extension-specific error codes and operation names.
cli/azd/extensions/azure.ai.skills/internal/cmd/version.go	version subcommand.
cli/azd/extensions/azure.ai.skills/internal/cmd/skill_validate.go	Skill name validation.
cli/azd/extensions/azure.ai.skills/internal/cmd/skill_validate_test.go	Tests for name validation + flag-mode validation helpers.
cli/azd/extensions/azure.ai.skills/internal/cmd/skill_update.go	skill update implementation (GET-merge-POST).
cli/azd/extensions/azure.ai.skills/internal/cmd/skill_show.go	skill show implementation.
cli/azd/extensions/azure.ai.skills/internal/cmd/skill_list.go	skill list implementation (paged flattening).
cli/azd/extensions/azure.ai.skills/internal/cmd/skill_download.go	skill download implementation (raw vs extracted).
cli/azd/extensions/azure.ai.skills/internal/cmd/skill_delete.go	skill delete implementation with confirmation behavior.
cli/azd/extensions/azure.ai.skills/internal/cmd/skill_create.go	skill create implementation (inline, SKILL.md, ZIP package).
cli/azd/extensions/azure.ai.skills/internal/cmd/skill_context.go	Endpoint + credential + client construction.
cli/azd/extensions/azure.ai.skills/internal/cmd/root.go	Root command wiring, persistent flags, and host commands.
cli/azd/extensions/azure.ai.skills/internal/cmd/output.go	JSON/table output helpers for skills.
cli/azd/extensions/azure.ai.skills/internal/cmd/output_test.go	Tests for table output rendering.
cli/azd/extensions/azure.ai.skills/internal/cmd/endpoint.go	Endpoint resolution cascade + URL validation.
cli/azd/extensions/azure.ai.skills/internal/cmd/endpoint_test.go	Tests for endpoint resolution and validation.
cli/azd/extensions/azure.ai.skills/internal/cmd/debug.go	Debug logging setup for stdlib log + Azure SDK logger.
cli/azd/extensions/azure.ai.skills/go.sum	Extension module dependency lockfile.
cli/azd/extensions/azure.ai.skills/go.mod	Extension module definition and dependencies.
cli/azd/extensions/azure.ai.skills/extension.yaml	Extension metadata and examples for azd.
cli/azd/extensions/azure.ai.skills/cspell.yaml	Spellcheck configuration for extension-specific terms.
cli/azd/extensions/azure.ai.skills/ci-test.ps1	CI test runner for the extension.
cli/azd/extensions/azure.ai.skills/ci-build.ps1	CI build script for the extension binary.
cli/azd/extensions/azure.ai.skills/CHANGELOG.md	Initial release notes for the extension.
cli/azd/extensions/azure.ai.skills/build.sh	Local multi-platform build helper (bash).
cli/azd/extensions/azure.ai.skills/build.ps1	Local multi-platform build helper (PowerShell).
cli/azd/extensions/azure.ai.skills/AGENTS.md	Extension-specific contributor/agent guidance.
cli/azd/extensions/azure.ai.skills/.golangci.yaml	Extension-local golangci-lint configuration.
cli/azd/extensions/azure.ai.skills/.gitignore	Ignores local build/test artifacts for the extension.

Comments suppressed due to low confidence (3)

cli/azd/extensions/azure.ai.skills/internal/pkg/skill_api/archive.go:389

• copyFile writes to dst via os.OpenFile(..., O_TRUNC, ...), which will follow a symlink if one exists at dst. For a “safe extraction” helper, this should defensively refuse to write through symlinks (and other non-regular file types), including in --force mode.
  cli/azd/extensions/azure.ai.skills/internal/cmd/skill_download.go:287
• The command help text says download retrieves a “ZIP package” and --raw writes the “ZIP archive as-is”, but the implementation explicitly supports ZIP or gzip-tar downloads (and even chooses the extension based on magic bytes). Update the Long/flag help strings to refer to a generic “archive/package” to avoid contradicting actual behavior.
  cli/azd/extensions/azure.ai.skills/internal/cmd/endpoint.go:133
• validateEndpoint returns plain fmt.Errorf errors for invalid user input. Since endpoint validation errors are user-fixable and should produce stable telemetry, consider returning a structured exterrors.Validation (e.g., CodeInvalidParameter) instead of an untyped error so the azd host categorizes and renders it consistently.

[jongio]

Clean extension structure - follows the azure.ai.agents patterns well, archive security is solid (zip-slip guard, symlink rejection, staging directory, size caps), and the test coverage across client/archive/parser/validation is thorough.

One nit on Go 1.26 style below. The Copilot bot's comment about the unused bufio.Scanner in findFrontMatterBounds is valid too - that variable gets .Buffer() called so it compiles, but it's never actually used for scanning.

[jongio]

[MEDIUM] Use errors.AsType per Go 1.26 convention

AGENTS.md says to always use errors.AsType when checking if an error matches a specific type. This still uses the old two-step errors.As pattern. exterrors/errors.go already uses the correct style (errors.AsType[*azcore.ResponseError]) so it'd be consistent to do the same here.

Suggested change

	func isNotFound(err error) bool {
	var respErr *azcore.ResponseError
	if errors.As(err, &respErr) {
	return respErr.StatusCode == 404
	}
	return false
	}
	func isNotFound(err error) bool {
	if respErr, ok := errors.AsType[*azcore.ResponseError](err); ok {
	return respErr.StatusCode == 404
	}
	return false
	}

[huimiu]

Good catch, thanks! Switched to errors.AsType[*azcore.ResponseError]

[trangevi]

Please add tests where possible

[trangevi]

I don't think we should have this message about re-creating. In theory, if a user is trying to download the skill, they don't have the skill locally with which to recreate it.

[trangevi]

Would we be better served by not doing the extraction ourselves? Or requiring it as an opt-in instead? So that these security concerns are more of an opt in from the user, rather than an opt out?

@therealjohn thoughts?

[trangevi]

Is there a better name we can give this? Or we think it's a common enough thing that it won't be weird to people?

@therealjohn

[trangevi]

Should we also indicate that updating zipped skills needs to be done via create with --force? Or am I misunderstanding what this means?

[trangevi]

Skills aren't versioned, correct? Should we call that out, that this will be a destructive operation?