ai.docs: add skill doc category, rename install command

Add a fourth doc category for the Foundry skill resource (the azure.ai.skills extension) alongside agent, connection, and toolbox. Four topics under skills/skill/: overview (versioning model, has_blob, CLI surface, endpoint resolution), manage (imperative CLI reference with Foundry-specific input rules in-context), share (cross-project download flows + safe-extract guarantees), consume (Hosted-agent runtime wiring via skill_directories and the redeploy flow).

Rename azd ai doc skills install to azd ai doc install skill. The new install parent groups embedded-pack installers; the skill child still copies the bundled azd-ai-skill coding-agent pack into the user's project (flag surface unchanged). No backwards-compat alias since the extension is 0.0.1-preview.

Also: update the embedded SKILL.md router with a foundry skills section and azd ai skill in allowed-tools; refresh README directory layout and examples; add CHANGELOG entry; add agentskills/repoint/repoints to cspell.yaml to mirror the azure.ai.skills extension.

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

Author: therealjohn

cli/azd/extensions/azure.ai.docs/CHANGELOG.md

@@ -1,3 +1,25 @@
 # Release History
 
-## 0.0.1-preview - Initial Version
+## 0.0.1-preview - Initial Version
+
+### Added
+
+* `azd ai doc skill` command group with topics for the Foundry skill
+  resource (`overview`, `manage`, `share`, `consume`). Covers the
+  `azure.ai.skills` extension lifecycle: the versioned skill model
+  (`default_version` / `latest_version`), the `azd ai skill` CLI
+  reference, cross-project sharing via download / re-upload, and
+  agent-side wiring (`skill_directories`) for Hosted agents.
+* `azd ai doc install` parent command group for embedded-pack
+  installers, hosting the renamed `install skill` child below.
+
+### Changed
+
+* Renamed `azd ai doc skills install` to `azd ai doc install skill`.
+  The new `install` parent groups embedded-pack installers; the `skill`
+  child copies the bundled `azd-ai-skill` coding-agent pack into the
+  user's project (the existing `--target` / `--path` / `--force` /
+  `--output` flag surface is unchanged). No backwards-compatible alias.
+* The embedded `SKILL.md` router now lists the Foundry skill resource
+  docs alongside agent / connection / toolbox docs and adds
+  `azd ai skill` to the `allowed-tools` list.

cli/azd/extensions/azure.ai.docs/README.md

@@ -20,12 +20,28 @@ azd ai doc agent initialize
 azd ai doc agent configure
 azd ai doc agent investigate
 azd ai doc agent operate
+
+# List topics for the Foundry skill resource (azure.ai.skills)
+azd ai doc skill
+azd ai doc skill overview
+azd ai doc skill manage
+azd ai doc skill share
+azd ai doc skill consume
+
+# Install the embedded azd-ai-skill coding-agent pack into the project
+azd ai doc install skill --target copilot
 ```
 
 Each topic is a contract an agent reads to drive the matching CLI
 commands: exact invocations, JSON shape examples, error codes,
 confirmation-envelope handling.
 
+> Note: the `skill` doc category covers the **Foundry skill resource**
+> managed by the `azure.ai.skills` extension. It is intentionally
+> distinct from `install skill`, which copies the embedded
+> coding-agent pack (`azd-ai-skill`) into the user's project for tools
+> like Claude Code / GitHub Copilot.
+
 ## Local development
 
 The first install in a new environment needs the full pack + publish +
@@ -59,20 +75,34 @@ internal/cmd/
       configure.md
       investigate.md
       operate.md
-    toolbox/          <-- future: topics for azure.ai.toolboxes
+    connection/       <-- topics for azure.ai.connections (today under azd ai agent connection)
+      overview.md
+      add.md
       ...
-    project/          <-- future: topics for azure.ai.projects
+    toolbox/          <-- topics for azure.ai.toolboxes
+      overview.md
+      add.md
       ...
-  doc_index.go        <-- docCategories table (one entry per skills/ subdir)
-  doc_agent.go        <-- per-extension subcommand
+    skill/            <-- topics for azure.ai.skills (Foundry skill resource)
+      overview.md
+      manage.md
+      share.md
+      consume.md
+  doc_catalog.go      <-- docCategories table (one entry per skills/ subdir)
+  doc_agent.go        <-- per-extension subcommand (one per category)
+  doc_connection.go
+  doc_toolbox.go
+  doc_skill.go
 ```
 
 To add a new sibling:
 
 1. Drop `skills/<sibling>/<topic>.md` files into this extension.
-2. Add an entry to `docCategories` in `doc_index.go`.
-3. Add a `new<Sibling>Command()` constructor mirroring `newAgentCommand()`
-   and register it in `root.go`.
+2. Add an entry to `docCategories` in `doc_catalog.go` (plus a
+   `categoryExtensionName` case in `doc_renderer.go`).
+3. Add a `new<Sibling>Command()` constructor mirroring `newSkillCommand()`
+   and register it (plus the matching `helpformat.Install` block) in
+   `root.go`.
 
 No coordination with the sibling extension is required; this extension is
 the source of truth for its agent-friendly docs.

cli/azd/extensions/azure.ai.docs/cspell.yaml

@@ -40,6 +40,13 @@ words:
   - tmpfs
   # Used in skill_install.go comments describing the JSON wire shape
   - parseable
+  # Foundry-skills terms used in skill/* topic markdown bodies.
+  # `agentskills` references the agentskills.io naming spec.
+  # `repoint` / `repoints` describe the metadata-only default-version
+  # update flow on Foundry skills (mirrors azure.ai.skills cspell.yaml).
+  - agentskills
+  - repoint
+  - repoints
 overrides:
   - filename: internal/cmd/doc_catalog.go
     words:

cli/azd/extensions/azure.ai.docs/internal/cmd/doc_catalog.go

@@ -174,6 +174,33 @@ var docCategories = []DocCategory{
 			"Print the consumer-side runtime guide.":  "azd ai doc toolbox consume",
 		},
 	},
+	{
+		Name:        "skill",
+		DisplayName: "Foundry skills (azure.ai.skills)",
+		// Foundry skills are centrally-stored, versioned behavioral
+		// guidelines a Hosted agent downloads and injects as
+		// instructions. Managed via the `azd ai skill` CLI (from the
+		// `azure.ai.skills` extension). Intentionally distinct from
+		// the embedded `azd-ai-skill` pack installed by
+		// `azd ai doc install skill` -- that is a coding-agent pack
+		// consumed by tools like Claude Code / GitHub Copilot.
+		Short: "Manage Foundry skills -- versioned, project-scoped behavioral guidelines a Hosted agent downloads and injects " +
+			"(azure.ai.skills).",
+		Preamble: []string{
+			"Foundry skills are reusable behavioral guidelines stored centrally on a Foundry project. " +
+				"A Hosted agent downloads them at build time and the agent runtime injects them as " +
+				"additional instructions on every session.",
+			"Use `azd ai doc skill <topic>` to print one topic's body in full. " +
+				"Start with `overview` for the mental model, then `manage` for the CLI.",
+		},
+		Examples: map[string]string{
+			"List topics for skills.":                   "azd ai doc skill",
+			"Print the overview topic.":                 "azd ai doc skill overview",
+			"Print the management CLI reference.":       "azd ai doc skill manage",
+			"Print the cross-project sharing recipes.":  "azd ai doc skill share",
+			"Print the hosted-agent consumption guide.": "azd ai doc skill consume",
+		},
+	},
 }
 
 // init populates the Topics field of every DocCategory from the

cli/azd/extensions/azure.ai.docs/internal/cmd/doc_renderer.go

@@ -253,6 +253,8 @@ func categoryExtensionName(cat DocCategory) string {
 		return "azure.ai.connections"
 	case "toolbox":
 		return "azure.ai.agents"
+	case "skill":
+		return "azure.ai.skills"
 	default:
 		return fmt.Sprintf("azure.ai.%s", cat.Name)
 	}

cli/azd/extensions/azure.ai.docs/internal/cmd/doc_skill.go

@@ -0,0 +1,65 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+// doc_skill.go implements `azd ai doc skill [topic]` -- prints
+// embedded skill-friendly markdown from skills/skill/*.md. Mirrors
+// doc_agent.go / doc_connection.go / doc_toolbox.go; all four share
+// printCategoryTopic and the embedded skillsFS in doc_agent.go (via
+// the //go:embed skills/*/*.md glob).
+//
+// These are docs for the Foundry Skill resource (versioned,
+// project-scoped behavioral guidelines managed via `azd ai skill`
+// from the azure.ai.skills extension). They are intentionally
+// distinct from the embedded `azd-ai-skill` pack copied into the
+// user's project by `azd ai doc install skill`.
+//
+// Add a new topic by dropping a markdown file with front-matter into
+// skills/skill/; the catalog loader picks it up automatically.
+
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+)
+
+// newSkillCommand returns `azd ai doc skill [topic]`. When invoked
+// with no positional arg, prints the skill topic list. When invoked
+// with a positional topic name, prints that topic body.
+//
+// Acts as a single entry point an agent uses to load just the slice of
+// Foundry skill docs it needs to drive the `azd ai skill` CLI and to
+// wire downloaded SKILL.md files into a Hosted agent.
+func newSkillCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "skill [topic]",
+		Short: "Print agent-friendly documentation for Foundry skills.",
+		// Long is intentionally empty: the styled Description function
+		// passed via helpformat.Install in root.go drives the --help
+		// preamble (the same string the RunE prints below for direct
+		// invocation). cmd.Example is also intentionally empty so
+		// helpformat.Install's cmd.Example auto-migration does not
+		// produce a duplicate Examples block alongside the Footer one
+		// we wire in root.go.
+		Args: cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if len(args) == 0 {
+				cat := FindCategory("skill")
+				if cat == nil {
+					return fmt.Errorf("doc catalog: skill category not registered")
+				}
+				out := cmd.OutOrStdout()
+				if _, err := fmt.Fprint(out, renderCatalogBody(*cat)); err != nil {
+					return err
+				}
+				if _, err := fmt.Fprint(out, renderCatalogExamples(*cat)); err != nil {
+					return err
+				}
+				return nil
+			}
+			return printCategoryTopic(cmd.OutOrStdout(), "skill", args[0])
+		},
+	}
+	return cmd
+}

cli/azd/extensions/azure.ai.docs/internal/cmd/help_styling_test.go

@@ -63,10 +63,11 @@ func TestDocRootHelp_StyledSections(t *testing.T) {
 	assert.Contains(t, out, "Print the samples topic body.",
 		"third catalog example title missing")
 
-	// Cobra's Available Commands listing should include the 3 visible
-	// leaves (agent, skills, version; metadata is reserved by the SDK
-	// and may appear as well -- not asserted).
-	for _, name := range []string{"agent", "skills", "version"} {
+	// Cobra's Available Commands listing should include the visible
+	// leaves (agent, connection, toolbox, skill, install, version;
+	// metadata is reserved by the SDK and may appear as well -- not
+	// asserted).
+	for _, name := range []string{"agent", "connection", "toolbox", "skill", "install", "version"} {
 		assert.True(t, strings.Contains(out, name),
 			"Cobra subcommand list missing %q", name)
 	}
@@ -99,21 +100,21 @@ func TestDocAgentHelp_Smoke(t *testing.T) {
 		"first catalog example title missing")
 }
 
-// TestDocSkillsInstallHelp_BulletPreambleAndExamples confirms the
-// long-form skill install command -- which has an existing Long
+// TestDocInstallSkillHelp_BulletPreambleAndExamples confirms the
+// long-form `install skill` command -- which has an existing Long
 // containing bullet items written into the cobra.Command literal --
 // renders those as plain text alongside the styled section headers
 // and migrated Examples. This is the "leave existing Long verbatim"
 // path: no Description override, just styling around it.
-func TestDocSkillsInstallHelp_BulletPreambleAndExamples(t *testing.T) {
+func TestDocInstallSkillHelp_BulletPreambleAndExamples(t *testing.T) {
 	withColorDisabled(t)
 
-	out := helpOf(t, "skills", "install")
+	out := helpOf(t, "install", "skill")
 	assert.Contains(t, out, "Built-in targets:")
 	assert.Contains(t, out, "Usage:")
 	assert.Contains(t, out, "Flags:")
-	assert.Contains(t, out, "--target", "install's --target flag should appear in Flags section")
-	assert.Contains(t, out, "Examples:", "skills install has migrated examples")
+	assert.Contains(t, out, "--target", "install skill's --target flag should appear in Flags section")
+	assert.Contains(t, out, "Examples:", "install skill has migrated examples")
 }
 
 // runE runs the root command with args (no --help) and returns the

cli/azd/extensions/azure.ai.docs/internal/cmd/install.go

@@ -0,0 +1,51 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+// install.go is the parent command for `azd ai doc install ...`. Today it
+// hosts a single child (`skill`, which installs the embedded azd-ai-skill
+// coding-agent pack into the user's project), but the design keeps
+// "install" as its own subtree so future installable artifacts (e.g.
+// `install hooks`, `install workflows`) slot in without resurfacing the
+// install ergonomics.
+//
+// Note: the embedded pack installed by `azd ai doc install skill` is the
+// coding-agent skill consumed by tools like Claude Code / GitHub Copilot.
+// It is intentionally distinct from the Foundry Skill resource managed by
+// the `azure.ai.skills` extension (see `azd ai doc skill` for those
+// docs).
+
+package cmd
+
+import (
+	"github.com/azure/azure-dev/cli/azd/pkg/azdext"
+	"github.com/spf13/cobra"
+)
+
+// newInstallCommand returns the `azd ai doc install` parent command. The
+// parent has no RunE -- it just hangs the skill subcommand off the tree.
+// Help text doubles as the index of available verbs.
+func newInstallCommand(extCtx *azdext.ExtensionContext) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "install <command> [options]",
+		Short: "Install agent-friendly packs into your project.",
+		Long: `Install agent-friendly packs into your project so a coding agent
+(Claude Code, Codex, Gemini CLI, GitHub Copilot, Opencode, or a custom
+integration) can follow them.
+
+Packs are read from this extension's embedded content; installing copies
+them into a tool-specific path under the current project (e.g.
+.claude/skills/azd-ai-skill/ for Claude Code).`,
+		Example: `  # Install the AZD AI skill pack for GitHub Copilot
+  azd ai doc install skill --target copilot
+
+  # Install for Claude Code (writes .claude/skills/azd-ai-skill/)
+  azd ai doc install skill --target claude
+
+  # Install to a custom directory
+  azd ai doc install skill --target custom --path .my-tool/skills/azd-ai`,
+	}
+
+	cmd.AddCommand(newInstallSkillCommand(extCtx))
+
+	return cmd
+}

cli/azd/extensions/azure.ai.docs/internal/cmd/root.go

@@ -39,7 +39,8 @@ func NewRootCommand() *cobra.Command {
 	rootCmd.AddCommand(newAgentCommand())
 	rootCmd.AddCommand(newConnectionCommand())
 	rootCmd.AddCommand(newToolboxCommand())
-	rootCmd.AddCommand(newSkillsCommand(extCtx))
+	rootCmd.AddCommand(newSkillCommand())
+	rootCmd.AddCommand(newInstallCommand(extCtx))
 	rootCmd.AddCommand(newVersionCommand(&extCtx.OutputFormat))
 	rootCmd.AddCommand(newMetadataCommand(rootCmd))
 
@@ -92,6 +93,18 @@ func NewRootCommand() *cobra.Command {
 		}
 	}
 
+	// Same wiring for the skill category command. Mirrors the agent /
+	// connection / toolbox blocks above. doc_skill.go stays cobra-only.
+	if skillCmd := findChild(rootCmd, "skill"); skillCmd != nil {
+		if cat := FindCategory("skill"); cat != nil {
+			c := *cat
+			helpformat.Install(skillCmd, helpformat.Options{
+				Description: func(*cobra.Command) string { return renderCatalogBody(c) },
+				Footer:      func(*cobra.Command) string { return renderCatalogExamples(c) },
+			})
+		}
+	}
+
 	// Walk the rest of the tree (skills, version, metadata) and apply
 	// default styling. InstallAll skips already-Installed commands so
 	// root and agent (above) keep their custom Description/Footer.

cli/azd/extensions/azure.ai.docs/internal/cmd/root_test.go

@@ -20,6 +20,14 @@ func TestNewRootCommand_HasAgentSubcommand(t *testing.T) {
 	}
 	assert.Contains(t, names, "agent",
 		"azd ai doc must expose the agent subgroup")
+	assert.Contains(t, names, "connection",
+		"azd ai doc must expose the connection subgroup")
+	assert.Contains(t, names, "toolbox",
+		"azd ai doc must expose the toolbox subgroup")
+	assert.Contains(t, names, "skill",
+		"azd ai doc must expose the skill subgroup (Foundry skill resource docs)")
+	assert.Contains(t, names, "install",
+		"azd ai doc must expose the install subgroup (embedded skill-pack installer)")
 }
 
 func TestNewRootCommand_RunsIndexAsDefault(t *testing.T) {
@@ -60,6 +68,25 @@ func TestSkillsFS_HasAllAgentTopics(t *testing.T) {
 	}, got)
 }
 
+func TestSkillsFS_HasAllSkillTopics(t *testing.T) {
+	// Pins the topic set for the Foundry skill resource docs (the
+	// azure.ai.skills extension). A future drop or rename is a
+	// deliberate test update -- topic names are the wire contract
+	// callers rely on (`azd ai doc skill <topic>`).
+	topics, err := loadCategoryTopics("skill")
+	require.NoError(t, err)
+	var got []string
+	for _, top := range topics {
+		got = append(got, top.Name)
+	}
+	assert.ElementsMatch(t, []string{
+		"overview",
+		"manage",
+		"share",
+		"consume",
+	}, got)
+}
+
 func TestPrintCategoryTopic_KnownTopicEmitsBody(t *testing.T) {
 	var buf bytes.Buffer
 	require.NoError(t, printCategoryTopic(&buf, "agent", "initialize"))