feat: replace glean-cli-shared with root glean-cli discovery skill

.gitignore

@@ -1,5 +1,5 @@
-glean
-glean-cli
+/glean
+/glean-cli
 .claude/worktrees/
 EVAL-CHECKLIST.md
 docs/

README.md

@@ -354,7 +354,7 @@ npx skills add https://github.com/gleanwork/glean-cli/tree/main/skills/glean-cli
 
 | Skill                     | Description                                            |
 | ------------------------- | ------------------------------------------------------ |
-| `glean-cli-shared`        | Shared patterns: auth, global flags, output formatting |
+| `glean-cli`               | Root skill: discovery, auth, global flags, output formatting |
 | `glean-cli-search`        | Search across company knowledge                        |
 | `glean-cli-chat`          | Chat with Glean Assistant                              |
 | `glean-cli-schema`        | Runtime JSON schema introspection                      |

internal/skills/generator.go

@@ -14,9 +14,12 @@ import (
 	"github.com/gleanwork/glean-cli/internal/schema"
 )
 
+// rootSkillName is the directory and frontmatter name for the root discovery skill.
+const rootSkillName = "glean-cli"
+
 // skillPrefix is prepended to command names to form skill directory and
-// frontmatter names (e.g. "glean-cli-search", "glean-cli-shared").
-const skillPrefix = "glean-cli-"
+// frontmatter names (e.g. "glean-cli-search").
+const skillPrefix = rootSkillName + "-"
 
 // subcommandMap provides human-friendly descriptions for subcommands that
 // the schema registry doesn't capture (schemas are per-namespace, not per-sub).
@@ -101,6 +104,7 @@ type FlagInfo struct {
 // SkillData holds all data needed to render a SKILL.md template.
 type SkillData struct {
 	Prefix      string
+	RootSkill   string
 	Name        string
 	Description string
 	Command     string
@@ -124,7 +128,7 @@ description: "{{ .Description }}"
 
 # glean {{ .Command }}
 
-> **PREREQUISITE:** Read ` + "`../{{ .Prefix }}shared/SKILL.md`" + ` for auth, global flags, and security rules.
+> **PREREQUISITE:** Read ` + "`../{{ .RootSkill }}/SKILL.md`" + ` for auth, global flags, and security rules.
 
 {{ .SchemaDesc }}
 
@@ -163,15 +167,25 @@ glean schema | jq '.commands'
 ` + "```" + `
 `))
 
-var sharedTmpl = template.Must(template.New("shared").Parse(`---
-name: {{ .Prefix }}shared
-description: "Glean CLI: Shared patterns for authentication, global flags, output formatting, and security rules."
+var rootTmpl = template.Must(template.New("root").Parse(`---
+name: {{ .RootSkill }}
+description: "Glean CLI: access company knowledge, search documents, chat with Glean Assistant, look up people, and manage enterprise content. Use when the user asks about internal docs, company information, people, policies, or enterprise data."
 compatibility: Requires the glean binary on $PATH. Install via brew install gleanwork/tap/glean-cli
 ---
 
-# glean — Shared Reference
+# Glean CLI
+
+The ` + "`glean`" + ` command-line tool provides authenticated access to your company's Glean instance. It can search documents, chat with Glean Assistant, look up people and teams, manage collections, and more.
+
+## When to Use
+
+Use the Glean CLI when the user:
 
-> **Read this first.** All other glean skills assume familiarity with auth, flags, and output formats described here.
+- Asks about internal documents, policies, wikis, or company knowledge
+- Wants to find people, teams, or org structure
+- Needs to search across enterprise data sources (Confluence, Jira, Google Drive, Slack, etc.)
+- Asks questions that require company-specific context
+- Wants to manage Glean resources (collections, shortcuts, pins, announcements)
 
 ## Installation
 
@@ -212,7 +226,7 @@ glean <command> [subcommand] [flags]
 
 ## Schema Introspection
 
-Always call glean schema <command> before invoking a command you haven't used before.
+Always call ` + "`glean schema <command>`" + ` before invoking a command you haven't used before.
 
 ` + "```bash" + `
 glean schema | jq '.commands'          # list all commands
@@ -266,10 +280,10 @@ func Generate(outputDir string) error {
 		entries = append(entries, CommandEntry{Name: name, Description: s.Description})
 	}
 
-	if err := writeSharedSkill(outputDir, entries); err != nil {
-		return fmt.Errorf("writing shared skill: %w", err)
+	if err := writeRootSkill(outputDir, entries); err != nil {
+		return fmt.Errorf("writing root skill: %w", err)
 	}
-	fmt.Fprintf(os.Stderr, "  wrote %sshared/SKILL.md\n", skillPrefix)
+	fmt.Fprintf(os.Stderr, "  wrote %s/SKILL.md\n", rootSkillName)
 
 	// Generate per-command skills
 	for _, name := range commands {
@@ -290,8 +304,8 @@ func Generate(outputDir string) error {
 	return nil
 }
 
-func writeSharedSkill(outputDir string, commands []CommandEntry) error {
-	dir := filepath.Join(outputDir, skillPrefix+"shared")
+func writeRootSkill(outputDir string, commands []CommandEntry) error {
+	dir := filepath.Join(outputDir, rootSkillName)
 	if err := os.MkdirAll(dir, 0o755); err != nil {
 		return err
 	}
@@ -302,10 +316,11 @@ func writeSharedSkill(outputDir string, commands []CommandEntry) error {
 	defer f.Close()
 
 	data := struct {
-		Prefix   string
-		Commands []CommandEntry
-	}{Prefix: skillPrefix, Commands: commands}
-	return sharedTmpl.Execute(f, data)
+		Prefix    string
+		RootSkill string
+		Commands  []CommandEntry
+	}{Prefix: skillPrefix, RootSkill: rootSkillName, Commands: commands}
+	return rootTmpl.Execute(f, data)
 }
 
 func writeCommandSkill(outputDir, name string, s schema.CommandSchema) error {
@@ -374,6 +389,7 @@ func buildSkillData(name string, s schema.CommandSchema) SkillData {
 
 	return SkillData{
 		Prefix:      skillPrefix,
+		RootSkill:   rootSkillName,
 		Name:        skillPrefix + name,
 		Description: desc,
 		Command:     name,

skills/glean-cli-activity/SKILL.md

@@ -5,7 +5,7 @@ description: "Report user activity and submit feedback to Glean. Use when loggin
 
 # glean activity
 
-> **PREREQUISITE:** Read `../glean-cli-shared/SKILL.md` for auth, global flags, and security rules.
+> **PREREQUISITE:** Read `../glean-cli/SKILL.md` for auth, global flags, and security rules.
 
 Report user activity and feedback. Subcommands: report, feedback.
 

skills/glean-cli-agents/SKILL.md

@@ -5,7 +5,7 @@ description: "List, inspect, and run Glean AI agents. Use when discovering avail
 
 # glean agents
 
-> **PREREQUISITE:** Read `../glean-cli-shared/SKILL.md` for auth, global flags, and security rules.
+> **PREREQUISITE:** Read `../glean-cli/SKILL.md` for auth, global flags, and security rules.
 
 Manage and run Glean agents. Subcommands: list, get, schemas, run.
 

skills/glean-cli-announcements/SKILL.md

@@ -5,7 +5,7 @@ description: "Manage time-bounded company announcements in Glean. Use when creat
 
 # glean announcements
 
-> **PREREQUISITE:** Read `../glean-cli-shared/SKILL.md` for auth, global flags, and security rules.
+> **PREREQUISITE:** Read `../glean-cli/SKILL.md` for auth, global flags, and security rules.
 
 Manage Glean announcements. Subcommands: create, update, delete.
 

skills/glean-cli-answers/SKILL.md

@@ -5,7 +5,7 @@ description: "Manage curated Q&A pairs in Glean. Use when creating, updating, or
 
 # glean answers
 
-> **PREREQUISITE:** Read `../glean-cli-shared/SKILL.md` for auth, global flags, and security rules.
+> **PREREQUISITE:** Read `../glean-cli/SKILL.md` for auth, global flags, and security rules.
 
 Manage Glean answers. Subcommands: list, get, create, update, delete.
 

skills/glean-cli-api/SKILL.md

@@ -5,7 +5,7 @@ description: "Make raw authenticated HTTP requests to any Glean REST API endpoin
 
 # glean api
 
-> **PREREQUISITE:** Read `../glean-cli-shared/SKILL.md` for auth, global flags, and security rules.
+> **PREREQUISITE:** Read `../glean-cli/SKILL.md` for auth, global flags, and security rules.
 
 Make a raw authenticated HTTP request to any Glean REST API endpoint.
 

skills/glean-cli-chat/SKILL.md

@@ -5,7 +5,7 @@ description: "Chat with Glean Assistant from the command line. Use when asking q
 
 # glean chat
 
-> **PREREQUISITE:** Read `../glean-cli-shared/SKILL.md` for auth, global flags, and security rules.
+> **PREREQUISITE:** Read `../glean-cli/SKILL.md` for auth, global flags, and security rules.
 
 Have a conversation with Glean AI. Streams response to stdout.
 

skills/glean-cli-collections/SKILL.md

@@ -5,7 +5,7 @@ description: "Manage curated document collections in Glean. Use when creating, u
 
 # glean collections
 
-> **PREREQUISITE:** Read `../glean-cli-shared/SKILL.md` for auth, global flags, and security rules.
+> **PREREQUISITE:** Read `../glean-cli/SKILL.md` for auth, global flags, and security rules.
 
 Manage Glean collections. Subcommands: create, delete, update, add-items, delete-item.
 

skills/glean-cli-documents/SKILL.md

@@ -5,7 +5,7 @@ description: "Retrieve, summarize, and inspect documents indexed by Glean. Use w
 
 # glean documents
 
-> **PREREQUISITE:** Read `../glean-cli-shared/SKILL.md` for auth, global flags, and security rules.
+> **PREREQUISITE:** Read `../glean-cli/SKILL.md` for auth, global flags, and security rules.
 
 Retrieve and summarize Glean documents. Subcommands: get, get-by-facets, get-permissions, summarize.
 

skills/glean-cli-entities/SKILL.md

@@ -5,7 +5,7 @@ description: "Look up people, teams, and custom entities in Glean. Use when find
 
 # glean entities
 
-> **PREREQUISITE:** Read `../glean-cli-shared/SKILL.md` for auth, global flags, and security rules.
+> **PREREQUISITE:** Read `../glean-cli/SKILL.md` for auth, global flags, and security rules.
 
 List and read Glean entities and people. Subcommands: list, read-people.
 

skills/glean-cli-insights/SKILL.md

@@ -5,7 +5,7 @@ description: "Retrieve search and usage analytics from Glean. Use when analyzing
 
 # glean insights
 
-> **PREREQUISITE:** Read `../glean-cli-shared/SKILL.md` for auth, global flags, and security rules.
+> **PREREQUISITE:** Read `../glean-cli/SKILL.md` for auth, global flags, and security rules.
 
 Retrieve Glean usage insights. Subcommands: get.
 

skills/glean-cli-messages/SKILL.md

@@ -5,7 +5,7 @@ description: "Retrieve indexed messages from Slack, Teams, and other messaging p
 
 # glean messages
 
-> **PREREQUISITE:** Read `../glean-cli-shared/SKILL.md` for auth, global flags, and security rules.
+> **PREREQUISITE:** Read `../glean-cli/SKILL.md` for auth, global flags, and security rules.
 
 Retrieve Glean messages. Subcommands: get.
 

skills/glean-cli-pins/SKILL.md

@@ -5,7 +5,7 @@ description: "Manage promoted search results (pins) in Glean. Use when pinning s
 
 # glean pins
 
-> **PREREQUISITE:** Read `../glean-cli-shared/SKILL.md` for auth, global flags, and security rules.
+> **PREREQUISITE:** Read `../glean-cli/SKILL.md` for auth, global flags, and security rules.
 
 Manage Glean pins. Subcommands: list, get, create, update, remove.
 

skills/glean-cli-search/SKILL.md

@@ -5,7 +5,7 @@ description: "Search across company knowledge with the Glean CLI. Use when findi
 
 # glean search
 
-> **PREREQUISITE:** Read `../glean-cli-shared/SKILL.md` for auth, global flags, and security rules.
+> **PREREQUISITE:** Read `../glean-cli/SKILL.md` for auth, global flags, and security rules.
 
 Search for content in your Glean instance. Results are JSON.
 

skills/glean-cli-shortcuts/SKILL.md

@@ -5,7 +5,7 @@ description: "Manage Glean go-links (shortcuts). Use when creating, listing, upd
 
 # glean shortcuts
 
-> **PREREQUISITE:** Read `../glean-cli-shared/SKILL.md` for auth, global flags, and security rules.
+> **PREREQUISITE:** Read `../glean-cli/SKILL.md` for auth, global flags, and security rules.
 
 Manage Glean shortcuts (go-links). Subcommands: list, get, create, update, delete.
 

skills/glean-cli-tools/SKILL.md

@@ -5,7 +5,7 @@ description: "List and run Glean platform tools. Use when discovering available
 
 # glean tools
 
-> **PREREQUISITE:** Read `../glean-cli-shared/SKILL.md` for auth, global flags, and security rules.
+> **PREREQUISITE:** Read `../glean-cli/SKILL.md` for auth, global flags, and security rules.
 
 List and run Glean tools. Subcommands: list, run.
 

skills/glean-cli-verification/SKILL.md

@@ -5,7 +5,7 @@ description: "Manage document verification and review workflows in Glean. Use wh
 
 # glean verification
 
-> **PREREQUISITE:** Read `../glean-cli-shared/SKILL.md` for auth, global flags, and security rules.
+> **PREREQUISITE:** Read `../glean-cli/SKILL.md` for auth, global flags, and security rules.
 
 Manage document verification. Subcommands: list, verify, remind.
 

skills/glean-cli-shared/SKILL.md → skills/glean-cli/SKILL.md

@@ -1,12 +1,22 @@
 ---
-name: glean-cli-shared
-description: "Glean CLI: Shared patterns for authentication, global flags, output formatting, and security rules."
+name: glean-cli
+description: "Glean CLI: access company knowledge, search documents, chat with Glean Assistant, look up people, and manage enterprise content. Use when the user asks about internal docs, company information, people, policies, or enterprise data."
 compatibility: Requires the glean binary on $PATH. Install via brew install gleanwork/tap/glean-cli
 ---
 
-# glean — Shared Reference
+# Glean CLI
 
-> **Read this first.** All other glean skills assume familiarity with auth, flags, and output formats described here.
+The `glean` command-line tool provides authenticated access to your company's Glean instance. It can search documents, chat with Glean Assistant, look up people and teams, manage collections, and more.
+
+## When to Use
+
+Use the Glean CLI when the user:
+
+- Asks about internal documents, policies, wikis, or company knowledge
+- Wants to find people, teams, or org structure
+- Needs to search across enterprise data sources (Confluence, Jira, Google Drive, Slack, etc.)
+- Asks questions that require company-specific context
+- Wants to manage Glean resources (collections, shortcuts, pins, announcements)
 
 ## Installation
 
@@ -47,7 +57,7 @@ glean <command> [subcommand] [flags]
 
 ## Schema Introspection
 
-Always call glean schema <command> before invoking a command you haven't used before.
+Always call `glean schema <command>` before invoking a command you haven't used before.
 
 ```bash
 glean schema | jq '.commands'          # list all commands