doc: add design spec for `azd ai skill` commands by huimiu · Pull Request #8204 · Azure/azure-dev

huimiu · 2026-05-15T09:33:28Z

Summary

Adds the design spec for the Foundry Skill commands that ship in the azure.ai.agents extension (cli/azd/docs/design/ai-skill-design-spec.md). The skill subtree provides full CRUD plus download on Foundry Skills, so a developer can create a skill from inline flags or a SKILL.md/*.tar.gz file and round-trip it back out as a folder on disk, all without standing up a Foundry SDK harness.

Related issues:

Feature: Add azd ai skill create/update/show/list/download/delete to manage Foundry Skills from any directory #8142

Key points

Placement: lives in the existing azure.ai.agents extension. Today the commands surface as azd ai agent skill …; the layout is designed so a future move to a standalone azd ai skill extension is registration-only with no behavior diff. No registry.json impact and no new persistent state.
v1 surface: create, update, show, list, download, delete. create has three mutually exclusive input modes (inline --description + --instructions, --file SKILL.md, or --file *.tar.gz); download extracts the server gzip into ./.agents/skills/<name>/ by default, with --raw to keep the archive and --force to overwrite; delete confirms by default with --force to skip.
Endpoint resolution: reuses the standard 5 level cascade and cross-cutting flags (-p, --output, --no-prompt, --debug), matching connection, toolbox, and routine, and works standalone outside an azd project.
Create vs. update: distinct verbs hide the upsert wire. create fails on a name collision (or replaces with --force via delete-then-create). update is GET + local merge + POST that preserves untouched fields; --file rules on update follow the same modes as create, with packaged gzip update gated on the single open question below.
Typed client: new package at internal/pkg/agents/skill_api/ (sibling of agent_api, no overload), so error shapes, headers, and pagination stay consistent with the rest of the AI surface.
Safe tar extraction: zip-slip guard, symlink/hard-link rejection, staging directory, 10k entries / 512 MB decompression cap. JSON output shapes for download and delete are part of the public contract; resource verbs are passthrough.
Errors and telemetry: new exterrors codes (CodeInvalidSkillName, CodeInvalidSkillFile, CodeSkillArchiveUnsafe, CodeSkillOutputCollision) plug into the existing exterrors.Validation factory; one telemetry event per verb, with no skill names, descriptions, file paths, or endpoint values emitted.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

… file handling

…to hui/skill-design-spec

…rsing

github-actions · 2026-05-15T10:01:56Z

📋 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 design spec for azd ai agent skill commands in the Azure AI Agents extension, defining the intended CRUD/download CLI surface, endpoint resolution, output contracts, testing plan, telemetry, and security considerations.

Changes:

Documents create, update, show, list, download, and delete command behavior.
Defines file handling, archive extraction safeguards, JSON output contracts, and telemetry expectations.
Describes placement under the existing azure.ai.agents extension and a new skill_api package.

- Restrict the documented telemetry modes on `azd ai agent skill update` to `inline` / `file-md`. The previous "as above" wording implicitly included `file-gzip`, but section 6.2 rejects gzip on update, so the command can never emit that value. - Replace the inaccurate "debug logger sanitizes request bodies (same as agent_api)" line under Security Considerations. The Azure SDK pipeline used by agent_api sets `IncludeBody: true` under `--debug`, and the current `setupDebugLogging` sanitizer only redacts JSON connection-string fields. Document that this work extends the sanitizer to cover skill `description` / `instructions` before the skill client participates in body logging, and opts out of `IncludeBody` until that lands. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

therealjohn

Left two comments just clarify that it should be in a separate extension which impacts the skill name in the spec.

jongio

Left a question on the name validation regex - the fallback pattern in 6.7 diverges from the existing agent name regex in a few ways.

Reviewer feedback on #8204: - therealjohn: skill commands will ship in a new, standalone `azure.ai.skills` extension (namespace `ai.skill`) rather than the existing `azure.ai.agents` extension. Rename every command from `azd ai agent skill <verb>` to `azd ai skill <verb>` across §1, §3, §6.1–§6.6, §10, and §12. Update file paths to `cli/azd/extensions/azure.ai.skills/...` and move the typed client to the new extension's `internal/pkg/skill_api/`. Telemetry event names change to `azd.ai.skill.*`; debug log file becomes `azd-ai-skills-<date>.log`. - jongio: align the fallback skill-name regex with the existing agent name pattern in `azure.ai.agents/internal/pkg/agents/agent_yaml`: `^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\$` (1–63 chars, alphanumeric with internal hyphens only). The previous fallback was labeled "conservative" but actually allowed underscores, required a leading letter, and permitted trailing special chars; aligning gives users one rule across resource kinds. Connected updates: - §4 endpoint cascade: prefer `extensions.ai-skills.project.context.endpoint` with fallback to `extensions.ai-agents.project.context.endpoint` so users who configured the endpoint via the agents extension are not forced to re-run `set`. - §5 / §9: drop the "sibling of agent_api" framing; the new client lives inside `azure.ai.skills`. Reaffirm that `AgentCardSkill` in `azure.ai.agents` is in a different module with no symbol conflict. - §11 Argument echoing: rewrite to describe `skill_api`'s own logging posture (opt out of `IncludeBody` until the sanitizer covers skill `description` / `instructions`) without depending on `agent_api`'s behavior. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

huimiu · 2026-05-18T04:56:48Z

Thanks for the reviews! Pushed new commit:

@therealjohn: moved skill commands into a new standalone azure.ai.skills extension (namespace ai.skill). All commands renamed from azd ai agent skill to azd ai skill, with matching updates to file paths, telemetry event names (azd.ai.skill.*), and the debug log name.

@jongio: aligned the fallback name regex with the existing agent name pattern: ^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$. Good catch on the underscore/trailing-special drift.

jongio

Addresses my previous feedback on the name validation regex, now aligned with the agent name pattern in agent_yaml/parse.go. The config fallback to extensions.ai-agents.project.context.endpoint is a nice backward-compat touch. Looks good to me. Let's get a sign-off from @JeffreyCA or @vhvb1989 to unblock.

The live Foundry Skills service implements POST /skills:import and GET /skills/{name}:download with application/zip, not application/gzip as the upstream TypeSpec declares. Verified via 415 Unsupported Media Type on gzip uploads. Public docs confirm: https://learn.microsoft.com/azure/foundry/agents/how-to/tools/skills Changes: - skill_api: replace archive/tar+compress/gzip with archive/zip - skill_api: Download now returns []byte (archive/zip needs io.ReaderAt) - skill_api: rename ContentTypeGzip -> ContentTypeZip, ErrInvalidGzip -> ErrInvalidZip - cmd: accept '.zip' for --file; reject '.tar.gz'/'.tgz' - cmd: writeRaw now writes '<name>.zip' - tests: rewrite archive_test.go and archive_peek_test.go for ZIP - docs (AGENTS.md, README.md, CHANGELOG.md): s/gzip,tar.gz/zip/g The design spec (PR #8204) will need a follow-up to match. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

doc: add design spec for azd ai agent skill commands

5875382

microsoft-github-policy-service Bot assigned huimiu May 15, 2026

doc: add exterrors to cspell ignore; drop speculative open question

3e6eb6b

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

huimiu linked an issue May 15, 2026 that may be closed by this pull request

Add azd ai skill create/update/show/list/download/delete to manage Foundry Skills from any directory #8142

Open

huimiu added 3 commits May 15, 2026 17:49

docs: update design spec for azd ai agent skill commands to clarify…

fda201c

… file handling

Merge branch 'hui/skill-design-spec' of github.com:Azure/azure-dev in…

afc1e89

…to hui/skill-design-spec

fix: correct typo in validation error description for front matter pa…

7042035

…rsing

huimiu marked this pull request as ready for review May 15, 2026 10:00

Copilot AI review requested due to automatic review settings May 15, 2026 10:00

huimiu requested review from JeffreyCA, hemarina, jongio, rajeshkamal5050, tg-msft, vhvb1989, wbreza and weikanglim as code owners May 15, 2026 10:00

Copilot started reviewing on behalf of huimiu May 15, 2026 10:04 View session

Copilot AI reviewed May 15, 2026

View reviewed changes

Comment thread cli/azd/docs/design/ai-skill-design-spec.md Outdated

Comment thread cli/azd/docs/design/ai-skill-design-spec.md Outdated

therealjohn approved these changes May 15, 2026

View reviewed changes

Comment thread cli/azd/docs/design/ai-skill-design-spec.md Outdated

Comment thread cli/azd/docs/design/ai-skill-design-spec.md Outdated

jongio reviewed May 16, 2026

View reviewed changes

Comment thread cli/azd/docs/design/ai-skill-design-spec.md Outdated

huimiu changed the title ~~doc: add design spec for azd ai agent skill commands~~ doc: add design spec for azd ai skill commands May 18, 2026

jongio reviewed May 18, 2026

View reviewed changes

huimiu mentioned this pull request May 18, 2026

feat(skills): add azd ai skill command group #8224

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: add design spec for `azd ai skill` commands#8204

doc: add design spec for `azd ai skill` commands#8204
huimiu wants to merge 7 commits into
mainfrom
hui/skill-design-spec

huimiu commented May 15, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 15, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

therealjohn left a comment

Uh oh!

Uh oh!

Uh oh!

jongio left a comment

Uh oh!

Uh oh!

huimiu commented May 18, 2026

Uh oh!

jongio left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

huimiu commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key points

Uh oh!

github-actions Bot commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📋 Prioritization Note

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

therealjohn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jongio left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

huimiu commented May 18, 2026

Uh oh!

jongio left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

huimiu commented May 15, 2026 •

edited

Loading

github-actions Bot commented May 15, 2026 •

edited

Loading