feat: add agentskills.io-compatible SKILL.md generation

[gauravverma]

Add support for SKILLS.md generation

Summary

Adds GenSkills and GenSkillsDir to Cobra's doc package, enabling CLI tools built with Cobra to automatically generate agentskills.io-compatible SKILL.md files. This gives AI agents a standardized way to discover and use any Cobra-powered CLI.

Why this matters

AI coding agents (Claude Code, Copilot, Cursor, etc.) are increasingly used to operate CLI tools on behalf of developers. Today, agents either rely on --help output (verbose, unstructured) or hand-written documentation (often stale). The agentskills.io open standard solves this by defining a machine-readable SKILL.md format that agents can discover and consume automatically.

Cobra already generates man pages, markdown, YAML, and REST docs from command trees. This PR extends that same pattern to generate agent-optimized documentation — making every Cobra CLI "agent-ready" with a single function call.

What it does

Two new public functions in the doc package:

• GenSkills(cmd, w, config) — Writes a single SKILL.md to any io.Writer. Produces a concise document with YAML frontmatter (name, description, license, compatibility, metadata, allowed-tools, disable-model-invocation) and a command summary body. Best for small CLIs.

• GenSkillsDir(cmd, dir, config) — Generates a complete skill directory following the progressive disclosure convention:

  <dir>/<skill-name>/SKILL.md              (~100 tokens, always loaded by agents)
  <dir>/<skill-name>/references/<cmd>.md   (one per command, loaded on demand)
  

  The main SKILL.md stays concise with linked references. Each reference file contains detailed docs for a single command (description, usage, examples, flags). Agents load only what they need, keeping context window usage minimal.

Progressive disclosure in practice

1. Discovery — Agent reads SKILL.md frontmatter (~100 tokens) to decide relevance
2. Instructions — Agent reads the body (<500 lines) for a command overview
3. Detail — Agent follows a link to references/<cmd>.md only for the specific command it needs

How to use

import "github.com/spf13/cobra/doc"

// Simple: write a single SKILL.md
doc.GenSkills(rootCmd, os.Stdout, doc.SkillsConfig{
    Name:        "my-cli",
    Description: "Manage cloud resources",
    License:     "MIT",
})

// Full: generate skill directory with per-command references
doc.GenSkillsDir(rootCmd, "./skills", doc.SkillsConfig{
    Name:          "my-cli",
    Description:   "Manage cloud resources",
    License:       "MIT",
    Compatibility: "Requires docker and kubectl",
    AllowedTools:  "Bash(kubectl:*) Read",
    Metadata: map[string]string{
        "author":  "my-org",
        "version": "2.0",
    },
})
// Creates: skills/my-cli/SKILL.md + skills/my-cli/references/*.md

Typical integration: add a docs or skills subcommand to your CLI, or call it from a go generate directive.

Design decisions

• Follows existing doc package patterns — Same naming conventions (Gen* / Gen*Dir), same use of printOptions, byName, hasSeeAlso, same test and benchmark style
• One reference file per command — Rather than a single monolithic REFERENCE.md, each command gets its own file. This aligns with how agents work: they need detail on one command at a time, not the entire CLI
• Config struct instead of many parameters — SkillsConfig keeps the API clean and extensible as the agentskills.io spec evolves
• No new dependencies — Uses only stdlib and existing Cobra internals

[CLAassistant]

All committers have signed the CLA.