Merge pull request #13183 from cli/babakks/improve-skill-docs

docs(skill): polish skill commadset docs

pkg/cmd/skills/install/install.go

@@ -78,12 +78,12 @@ func NewCmdInstall(f *cmdutil.Factory, runF func(*InstallOptions) error) *cobra.
 			scope (in your home directory, available everywhere). Supported hosts
 			and their storage directories are (project, user):
 
-			- GitHub Copilot (%[1]s.agents/skills%[1]s, %[1]s~/.copilot/skills%[1]s)
-			- Claude Code    (%[1]s.claude/skills%[1]s, %[1]s~/.claude/skills%[1]s)
-			- Cursor         (%[1]s.agents/skills%[1]s, %[1]s~/.cursor/skills%[1]s)
-			- Codex          (%[1]s.agents/skills%[1]s, %[1]s~/.codex/skills%[1]s)
-			- Gemini CLI     (%[1]s.agents/skills%[1]s, %[1]s~/.gemini/skills%[1]s)
-			- Antigravity    (%[1]s.agents/skills%[1]s, %[1]s~/.gemini/antigravity/skills%[1]s)
+			  - GitHub Copilot (%[1]s.agents/skills%[1]s, %[1]s~/.copilot/skills%[1]s)
+			  - Claude Code    (%[1]s.claude/skills%[1]s, %[1]s~/.claude/skills%[1]s)
+			  - Cursor         (%[1]s.agents/skills%[1]s, %[1]s~/.cursor/skills%[1]s)
+			  - Codex          (%[1]s.agents/skills%[1]s, %[1]s~/.codex/skills%[1]s)
+			  - Gemini CLI     (%[1]s.agents/skills%[1]s, %[1]s~/.gemini/skills%[1]s)
+			  - Antigravity    (%[1]s.agents/skills%[1]s, %[1]s~/.gemini/antigravity/skills%[1]s)
 
 			Use %[1]s--agent%[1]s and %[1]s--scope%[1]s to control placement, or %[1]s--dir%[1]s for a
 			custom directory. The default scope is %[1]sproject%[1]s, and the default

pkg/cmd/skills/preview/preview.go

@@ -50,12 +50,12 @@ func NewCmdPreview(f *cmdutil.Factory, runF func(*PreviewOptions) error) *cobra.
 	cmd := &cobra.Command{
 		Use:   "preview <repository> [<skill>]",
 		Short: "Preview a skill from a GitHub repository (preview)",
-		Long: heredoc.Doc(`
-			Render a skill's SKILL.md content in the terminal. This fetches the
+		Long: heredoc.Docf(`
+			Render a skill's %[1]sSKILL.md%[1]s content in the terminal. This fetches the
 			skill file from the repository and displays it using the configured
 			pager, without installing anything.
 
-			A file tree is shown first, followed by the rendered SKILL.md content.
+			A file tree is shown first, followed by the rendered %[1]sSKILL.md%[1]s content.
 			When running interactively and the skill contains additional files
 			(scripts, references, etc.), a file picker lets you browse them
 			individually.
@@ -63,10 +63,9 @@ func NewCmdPreview(f *cmdutil.Factory, runF func(*PreviewOptions) error) *cobra.
 			When run with only a repository argument, lists available skills and
 			prompts for selection.
 
-			To preview a specific version of the skill, append @VERSION to the
-			skill name. The version is resolved as a git tag, branch, or commit
-			SHA.
-		`),
+			To preview a specific version of the skill, append %[1]s@VERSION%[1]s to the
+			skill name. The version is resolved as a git tag, branch, or commit SHA.
+		`, "`"),
 		Example: heredoc.Doc(`
 			# Preview a specific skill
 			$ gh skill preview github/awesome-copilot documentation-writer

pkg/cmd/skills/publish/publish.go

@@ -98,29 +98,29 @@ func NewCmdPublish(f *cmdutil.Factory, runF func(*PublishOptions) error) *cobra.
 	cmd := &cobra.Command{
 		Use:   "publish [<directory>] [flags]",
 		Short: "Validate and publish skills to a GitHub repository (preview)",
-		Long: heredoc.Doc(`
+		Long: heredoc.Docf(`
 			Validate a local repository's skills against the Agent Skills specification
 			and publish them by creating a GitHub release.
 
 			Validation checks include:
 
-			  - Skills follow the skills/*/SKILL.md directory convention
+			  - Skills follow the %[1]sskills/*/SKILL.md%[1]s directory convention
 			  - Skill names match the strict agentskills.io naming rules
 			  - Each skill name matches its directory name
 			  - Required frontmatter fields (name, description) are present
 			  - allowed-tools is a string, not an array
-			  - Install metadata (metadata.github-*) is stripped if present
+			  - Install metadata (%[1]smetadata.github-*%[1]s) is stripped if present
 
 			After validation passes, publish will interactively guide you through:
 
-			  - Adding the "agent-skills" topic to the repository
+			  - Adding the %[1]sagent-skills%[1]s topic to the repository
 			  - Choosing a version tag (semver recommended)
 			  - Creating a GitHub release with auto-generated notes
 
-			Use --dry-run to validate without publishing.
-			Use --tag to publish non-interactively with a specific tag.
-			Use --fix to automatically strip install metadata from committed files.
-		`),
+			Use %[1]s--dry-run%[1]s to validate without publishing.
+			Use %[1]s--tag%[1]s to publish non-interactively with a specific tag.
+			Use %[1]s--fix%[1]s to automatically strip install metadata from committed files.
+		`, "`"),
 		Example: heredoc.Doc(`
 			# Validate and publish interactively
 			$ gh skill publish
@@ -134,8 +134,7 @@ func NewCmdPublish(f *cmdutil.Factory, runF func(*PublishOptions) error) *cobra.
 			# Validate and strip install metadata
 			$ gh skills publish --fix
 		`),
-		Aliases: []string{"validate"},
-		Args:    cobra.MaximumNArgs(1),
+		Args: cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if len(args) == 1 {
 				opts.Dir = args[0]

pkg/cmd/skills/search/search.go

@@ -73,20 +73,19 @@ func NewCmdSearch(f *cmdutil.Factory, runF func(*SearchOptions) error) *cobra.Co
 	cmd := &cobra.Command{
 		Use:   "search <query> [flags]",
 		Short: "Search for skills across GitHub (preview)",
-		Long: heredoc.Doc(`
+		Long: heredoc.Docf(`
 			Search across all public GitHub repositories for skills matching a keyword.
 
-			Uses the GitHub Code Search API to find SKILL.md files whose name or
+			Uses the GitHub Code Search API to find %[1]sSKILL.md%[1]s files whose name or
 			description matches the query term.
 
 			Results are ranked by relevance: skills whose name contains the query
 			term appear first.
 
-			Use --owner to scope results to a specific GitHub user or organization.
+			Use %[1]s--owner%[1]s to scope results to a specific GitHub user or organization.
 
-			In interactive mode, you can select skills from the results to install
-			directly.
-		`),
+			In interactive mode, you can select skills from the results to install directly.
+		`, "`"),
 		Example: heredoc.Doc(`
 			# Search for skills related to terraform
 			$ gh skill search terraform

pkg/cmd/skills/update/update.go

@@ -75,9 +75,9 @@ func NewCmdUpdate(f *cmdutil.Factory, runF func(*UpdateOptions) error) *cobra.Co
 	cmd := &cobra.Command{
 		Use:   "update [<skill>...] [flags]",
 		Short: "Update installed skills to their latest versions (preview)",
-		Long: heredoc.Doc(`
+		Long: heredoc.Docf(`
 			Checks installed skills for available updates by comparing the local
-			tree SHA (from SKILL.md frontmatter) against the remote repository.
+			tree SHA (from %[1]sSKILL.md%[1]s frontmatter) against the remote repository.
 
 			Scans all known agent host directories (Copilot, Claude, Cursor, Codex,
 			Gemini, Antigravity) in both project and user scope automatically.
@@ -85,8 +85,8 @@ func NewCmdUpdate(f *cmdutil.Factory, runF func(*UpdateOptions) error) *cobra.Co
 			Without arguments, checks all installed skills. With skill names,
 			checks only those specific skills.
 
-			Pinned skills (installed with --pin) are skipped with a notice.
-			Use --unpin to clear the pinned version and include those skills
+			Pinned skills (installed with %[1]s--pin%[1]s) are skipped with a notice.
+			Use %[1]s--unpin%[1]s to clear the pinned version and include those skills
 			in the update.
 
 			Skills without GitHub metadata (e.g. installed manually or by another
@@ -94,14 +94,14 @@ func NewCmdUpdate(f *cmdutil.Factory, runF func(*UpdateOptions) error) *cobra.Co
 			The update re-downloads the skill with metadata injected, so future
 			updates work automatically.
 
-			With --force, re-downloads skills even when the remote version matches
+			With %[1]s--force%[1]s, re-downloads skills even when the remote version matches
 			the local tree SHA. This overwrites locally modified skill files with
 			their original content, but does not remove extra files added locally.
 
 			In interactive mode, shows which skills have updates and asks for
-			confirmation before proceeding. With --all, updates without prompting.
-			With --dry-run, reports available updates without modifying any files.
-		`),
+			confirmation before proceeding. With %[1]s--all%[1]s, updates without prompting.
+			With %[1]s--dry-run%[1]s, reports available updates without modifying any files.
+		`, "`"),
 		Example: heredoc.Doc(`
 			# Check and update all skills interactively
 			$ gh skill update