diff --git a/.gitignore b/.gitignore
index f90e44d..448cf80 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,5 @@
-glean
-glean-cli
+/glean
+/glean-cli
 .claude/worktrees/
 EVAL-CHECKLIST.md
 docs/
diff --git a/README.md b/README.md
index b92fa51..0bfac28 100644
--- a/README.md
+++ b/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                      |
diff --git a/internal/skills/generator.go b/internal/skills/generator.go
index 6dc22ea..8564dcb 100644
--- a/internal/skills/generator.go
+++ b/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,
diff --git a/skills/glean-cli-activity/SKILL.md b/skills/glean-cli-activity/SKILL.md
index d4fa91b..dcf5622 100644
--- a/skills/glean-cli-activity/SKILL.md
+++ b/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.
 
diff --git a/skills/glean-cli-agents/SKILL.md b/skills/glean-cli-agents/SKILL.md
index fc656cb..ec1cd86 100644
--- a/skills/glean-cli-agents/SKILL.md
+++ b/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.
 
diff --git a/skills/glean-cli-announcements/SKILL.md b/skills/glean-cli-announcements/SKILL.md
index cbed0f9..68453c5 100644
--- a/skills/glean-cli-announcements/SKILL.md
+++ b/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.
 
diff --git a/skills/glean-cli-answers/SKILL.md b/skills/glean-cli-answers/SKILL.md
index 0fda6f9..e850697 100644
--- a/skills/glean-cli-answers/SKILL.md
+++ b/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.
 
diff --git a/skills/glean-cli-api/SKILL.md b/skills/glean-cli-api/SKILL.md
index 2fed86d..8d9f8b6 100644
--- a/skills/glean-cli-api/SKILL.md
+++ b/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.
 
diff --git a/skills/glean-cli-chat/SKILL.md b/skills/glean-cli-chat/SKILL.md
index 733fbed..b88a096 100644
--- a/skills/glean-cli-chat/SKILL.md
+++ b/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.
 
diff --git a/skills/glean-cli-collections/SKILL.md b/skills/glean-cli-collections/SKILL.md
index 9d3bcd8..94f1c47 100644
--- a/skills/glean-cli-collections/SKILL.md
+++ b/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.
 
diff --git a/skills/glean-cli-documents/SKILL.md b/skills/glean-cli-documents/SKILL.md
index e78185f..b3f7dab 100644
--- a/skills/glean-cli-documents/SKILL.md
+++ b/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.
 
diff --git a/skills/glean-cli-entities/SKILL.md b/skills/glean-cli-entities/SKILL.md
index ecc98fd..2d85963 100644
--- a/skills/glean-cli-entities/SKILL.md
+++ b/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.
 
diff --git a/skills/glean-cli-insights/SKILL.md b/skills/glean-cli-insights/SKILL.md
index 0b9632b..4341b22 100644
--- a/skills/glean-cli-insights/SKILL.md
+++ b/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.
 
diff --git a/skills/glean-cli-messages/SKILL.md b/skills/glean-cli-messages/SKILL.md
index 08da40c..65117b6 100644
--- a/skills/glean-cli-messages/SKILL.md
+++ b/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.
 
diff --git a/skills/glean-cli-pins/SKILL.md b/skills/glean-cli-pins/SKILL.md
index 91a8edb..868e3c9 100644
--- a/skills/glean-cli-pins/SKILL.md
+++ b/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.
 
diff --git a/skills/glean-cli-search/SKILL.md b/skills/glean-cli-search/SKILL.md
index 8db6c5c..a2ab061 100644
--- a/skills/glean-cli-search/SKILL.md
+++ b/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.
 
diff --git a/skills/glean-cli-shortcuts/SKILL.md b/skills/glean-cli-shortcuts/SKILL.md
index 1c1522e..22909a3 100644
--- a/skills/glean-cli-shortcuts/SKILL.md
+++ b/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.
 
diff --git a/skills/glean-cli-tools/SKILL.md b/skills/glean-cli-tools/SKILL.md
index 35a65f5..81e1bac 100644
--- a/skills/glean-cli-tools/SKILL.md
+++ b/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.
 
diff --git a/skills/glean-cli-verification/SKILL.md b/skills/glean-cli-verification/SKILL.md
index 8a085f9..2389f9a 100644
--- a/skills/glean-cli-verification/SKILL.md
+++ b/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.
 
diff --git a/skills/glean-cli-shared/SKILL.md b/skills/glean-cli/SKILL.md
similarity index 78%
rename from skills/glean-cli-shared/SKILL.md
rename to skills/glean-cli/SKILL.md
index a0359a0..0db64a5 100644
--- a/skills/glean-cli-shared/SKILL.md
+++ b/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