feat: auto-generate Agent Skills from schema registry

.github/workflows/generate-skills.yml

@@ -0,0 +1,55 @@
+name: Generate Skills
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "cmd/**"
+      - "internal/schema/**"
+      - "internal/skills/**"
+  workflow_dispatch:
+
+concurrency:
+  group: generate-skills
+  cancel-in-progress: true
+
+jobs:
+  generate:
+    name: Regenerate skills
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up mise
+        uses: jdx/mise-action@v4
+        with:
+          cache: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build CLI
+        run: go build -o glean
+
+      - name: Generate skills
+        run: ./glean generate-skills
+
+      - name: Check for changes
+        id: diff
+        run: |
+          if git diff --quiet skills/ && [ -z "$(git status --porcelain skills/)" ]; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Commit and push
+        if: steps.diff.outputs.changed == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add skills/
+          git commit -m "chore: regenerate skills from schema registry [skip ci]"
+          git push

README.md

@@ -299,15 +299,41 @@ glean completion fish   # Fish
 
 ## Agent Skills
 
-The `skills/` directory contains markdown skill files for AI coding agents (Claude Code, etc.). They describe how to use each CLI command effectively in an automated context — flag patterns, output formats, and composition examples.
+The `skills/` directory contains [Agent Skills](https://agentskills.io) for AI coding agents (Claude Code, Codex, etc.). Each skill teaches the agent how to use a specific CLI command effectively — flags, output formats, and composition patterns.
 
-| File | Description |
-|------|-------------|
-| `skills/CONTEXT.md` | CLI-wide guidance: auth, output formats, error handling |
-| `skills/search.md` | How to use `glean search` in agent pipelines |
-| `skills/chat.md` | How to use `glean chat` for AI-assisted workflows |
-| `skills/schema.md` | How to use `glean schema` for command introspection |
-| `skills/shortcuts.md` | How to manage go-links programmatically |
+### Install
+
+```bash
+# Install all skills at once
+npx skills add https://github.com/gleanwork/glean-cli
+
+# Or pick only what you need
+npx skills add https://github.com/gleanwork/glean-cli/tree/main/skills/glean-search
+npx skills add https://github.com/gleanwork/glean-cli/tree/main/skills/glean-chat
+```
+
+### Available Skills
+
+| Skill | Description |
+|-------|-------------|
+| `glean-shared` | Shared patterns: auth, global flags, output formatting |
+| `glean-search` | Search across company knowledge |
+| `glean-chat` | Chat with Glean Assistant |
+| `glean-schema` | Runtime JSON schema introspection |
+| `glean-agents` | List, inspect, and run Glean AI agents |
+| `glean-documents` | Retrieve and summarize documents |
+| `glean-collections` | Manage curated document collections |
+| `glean-entities` | Look up people, teams, and entities |
+| `glean-answers` | Manage curated Q&A pairs |
+| `glean-shortcuts` | Manage go-links |
+| `glean-pins` | Manage promoted search results |
+| `glean-announcements` | Manage company announcements |
+| `glean-api` | Raw authenticated API access |
+| `glean-activity` | Report user activity and feedback |
+| `glean-verification` | Document verification workflows |
+| `glean-tools` | List and run platform tools |
+| `glean-messages` | Retrieve indexed messages |
+| `glean-insights` | Search and usage analytics |
 
 ## Contributing
 

cmd/generate_skills.go

@@ -0,0 +1,32 @@
+package cmd
+
+import (
+	"github.com/gleanwork/glean-cli/internal/skills"
+	"github.com/spf13/cobra"
+)
+
+// NewCmdGenerateSkills creates the generate-skills command.
+func NewCmdGenerateSkills() *cobra.Command {
+	var outputDir string
+
+	cmd := &cobra.Command{
+		Use:   "generate-skills",
+		Short: "Generate SKILL.md files from the CLI's schema registry",
+		Long: `Generates Agent Skills (https://agentskills.io) from the CLI's own
+schema registry. Each command gets a SKILL.md with frontmatter, flags,
+subcommands, and examples — derived deterministically from the registered
+schemas.
+
+Run this after adding or modifying commands to keep skills in sync.
+
+  glean generate-skills                    # write to skills/
+  glean generate-skills --output-dir out/  # write to out/`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return skills.Generate(outputDir)
+		},
+	}
+
+	cmd.Flags().StringVar(&outputDir, "output-dir", "skills", "Output directory for generated skills")
+
+	return cmd
+}

cmd/root.go

@@ -151,6 +151,11 @@ func NewCmdRoot() *cobra.Command {
 		cmd.AddCommand(sub)
 	}
 
+	// Dev/maintenance commands (hidden from default help)
+	genSkills := NewCmdGenerateSkills()
+	genSkills.Hidden = true
+	cmd.AddCommand(genSkills)
+
 	// Propagate settings to all subcommands
 	for _, subCmd := range cmd.Commands() {
 		subCmd.SilenceUsage = true