feat: Add comprehensive getting started documentation and setup scripts

rand · rand · commit 4e045621aeae · 2025-11-25T14:02:44.000-07:00
- Fix path references in all command files for plugin installation
- Remove 'skills' field from plugin.json per Claude Code docs
- Add prominent 'New? Start here' section to README
- Create 5 documentation files (GETTING_STARTED, FIRST_CONVERSATIONS,
  TROUBLESHOOTING, WALKTHROUGHS, FAQ)
- Create 3 safe setup scripts (verify, diagnose, demo)
- Include ML/AI examples throughout (6th example + 5th walkthrough)
- Total: 3,535 lines of docs + 620 lines of scripts

Addresses user feedback that cc-polymath is hard to get started with.
All scripts are safe and non-destructive (read-only operations).
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -39,6 +39,5 @@
     "dspy",
     "context-efficient"
   ],
-  "commands": "./commands",
-  "skills": "./skills"
+  "commands": "./commands"
 }
diff --git a/README.md b/README.md
@@ -6,7 +6,27 @@
 
 **Context-efficient development knowledge via progressive skill discovery**
 
-> **Claude Code Plugin**: Install with `/plugin install https://github.com/rand/cc-polymath`
+## 🚀 New? Start Here
+
+**Install in 30 seconds**:
+```
+/plugin install https://github.com/rand/cc-polymath
+```
+
+**Your first 3 commands**:
+```bash
+/skills                    # See what's recommended for your project
+/discover-frontend         # Load React, Next.js, TypeScript skills (example)
+bash ~/.claude/plugins/cc-polymath/scripts/verify-install.sh  # Verify installation
+```
+
+**Learn more**:
+- 📖 **[Getting Started Guide](docs/GETTING_STARTED.md)** - 5-minute quick start
+- 💬 **[Example Conversations](docs/FIRST_CONVERSATIONS.md)** - See it in action
+- 🆘 **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues & solutions
+- ❓ **[FAQ](docs/FAQ.md)** - Quick answers
+
+---
 
 This repository solves a tradeoff problem: how to give Claude Code access to comprehensive development knowledge without overwhelming its context window on boot. The solution is atomic, composable skills organized through a multi-tier discovery system.
 
diff --git a/commands/discover-api.md b/commands/discover-api.md
@@ -7,7 +7,7 @@ description: Load API design skills (REST, GraphQL, auth, rate limiting)
 Load the API design gateway skill:
 
 ```bash
-cat ~/.claude/skills/discover-api/SKILL.md
+cat ~/.claude/plugins/cc-polymath/skills/discover-api/SKILL.md
 ```
 
 This activates skills for:
diff --git a/commands/discover-containers.md b/commands/discover-containers.md
@@ -7,7 +7,7 @@ description: Load container skills (Docker, Kubernetes, security, optimization)
 Load the containers gateway skill:
 
 ```bash
-cat ~/.claude/skills/discover-containers/SKILL.md
+cat ~/.claude/plugins/cc-polymath/skills/discover-containers/SKILL.md
 ```
 
 This activates skills for:
diff --git a/commands/discover-database.md b/commands/discover-database.md
@@ -7,7 +7,7 @@ description: Load database skills (PostgreSQL, MongoDB, Redis, optimization)
 Load the database gateway skill:
 
 ```bash
-cat ~/.claude/skills/discover-database/SKILL.md
+cat ~/.claude/plugins/cc-polymath/skills/discover-database/SKILL.md
 ```
 
 This activates skills for:
diff --git a/commands/discover-debugging.md b/commands/discover-debugging.md
@@ -7,7 +7,7 @@ description: Load debugging skills (GDB, LLDB, profiling, memory analysis)
 Load the debugging gateway skill:
 
 ```bash
-cat ~/.claude/skills/discover-debugging/SKILL.md
+cat ~/.claude/plugins/cc-polymath/skills/discover-debugging/SKILL.md
 ```
 
 This activates skills for:
diff --git a/commands/discover-diagrams.md b/commands/discover-diagrams.md
@@ -7,7 +7,7 @@ description: Load diagram skills (Mermaid flowcharts, sequence, ER, architecture
 Load the diagrams gateway skill:
 
 ```bash
-cat ~/.claude/skills/discover-diagrams/SKILL.md
+cat ~/.claude/plugins/cc-polymath/skills/discover-diagrams/SKILL.md
 ```
 
 This activates skills for:
diff --git a/commands/discover-frontend.md b/commands/discover-frontend.md
@@ -7,7 +7,7 @@ description: Load frontend skills (React, Next.js, TypeScript, state management)
 Load the frontend gateway skill:
 
 ```bash
-cat ~/.claude/skills/discover-frontend/SKILL.md
+cat ~/.claude/plugins/cc-polymath/skills/discover-frontend/SKILL.md
 ```
 
 This activates skills for:
diff --git a/commands/discover-infrastructure.md b/commands/discover-infrastructure.md
@@ -7,7 +7,7 @@ description: Load infrastructure skills (Terraform, IaC, cloud platforms, contai
 Load the infrastructure gateway skill:
 
 ```bash
-cat ~/.claude/skills/discover-infrastructure/SKILL.md
+cat ~/.claude/plugins/cc-polymath/skills/discover-infrastructure/SKILL.md
 ```
 
 This activates skills for:
diff --git a/commands/discover-ml.md b/commands/discover-ml.md
@@ -7,7 +7,7 @@ description: Load ML/AI skills (DSPy, training, RAG, embeddings, evaluation)
 Load the ML/AI gateway skill:
 
 ```bash
-cat ~/.claude/skills/discover-ml/SKILL.md
+cat ~/.claude/plugins/cc-polymath/skills/discover-ml/SKILL.md
 ```
 
 This activates skills for:
diff --git a/commands/discover-mobile.md b/commands/discover-mobile.md
@@ -7,7 +7,7 @@ description: Load mobile development skills (iOS, Swift, SwiftUI, React Native)
 Load the mobile development gateway skill:
 
 ```bash
-cat ~/.claude/skills/discover-mobile/SKILL.md
+cat ~/.claude/plugins/cc-polymath/skills/discover-mobile/SKILL.md
 ```
 
 This activates skills for:
diff --git a/commands/discover-testing.md b/commands/discover-testing.md
@@ -7,7 +7,7 @@ description: Load testing skills (unit, integration, e2e, TDD, coverage)
 Load the testing gateway skill:
 
 ```bash
-cat ~/.claude/skills/discover-testing/SKILL.md
+cat ~/.claude/plugins/cc-polymath/skills/discover-testing/SKILL.md
 ```
 
 This activates skills for:
diff --git a/commands/skills.md b/commands/skills.md
@@ -17,7 +17,7 @@ Follow these steps:
 
 Read the master catalog:
 ```bash
-cat ~/.claude/skills/README.md
+cat ~/.claude/plugins/cc-polymath/skills/README.md
 ```
 
 ### 2. Detect Project Context
@@ -76,10 +76,10 @@ Display in this format:
 ```
 RECOMMENDED FOR THIS PROJECT:
 → discover-[category]
-  cat ~/.claude/skills/discover-[category]/SKILL.md
+  cat ~/.claude/plugins/cc-polymath/skills/discover-[category]/SKILL.md
 
 → discover-[category]
-  cat ~/.claude/skills/discover-[category]/SKILL.md
+  cat ~/.claude/plugins/cc-polymath/skills/discover-[category]/SKILL.md
 
 CATEGORIES (292 skills):
 Frontend (8) | Database (8) | API (7) | Testing (6) | Diagrams (8) | ML (30)
@@ -105,11 +105,11 @@ Recommend 2-4 gateway skills that match:
 RECOMMENDED GATEWAYS:
 → discover-api
   Keywords: REST, GraphQL, authentication, authorization, rate limiting
-  cat ~/.claude/skills/discover-api/SKILL.md
+  cat ~/.claude/plugins/cc-polymath/skills/discover-api/SKILL.md
 
 → discover-database
   Keywords: PostgreSQL, MongoDB, Redis, query optimization
-  cat ~/.claude/skills/discover-database/SKILL.md
+  cat ~/.claude/plugins/cc-polymath/skills/discover-database/SKILL.md
 ```
 
 **If ARGUMENT = category name:**
@@ -126,8 +126,8 @@ KEY SKILLS:
 [List 3-5 key skills with one-line descriptions]
 
 LOAD:
-cat ~/.claude/skills/{category}/INDEX.md          # All skills in category
-cat ~/.claude/skills/discover-{category}/SKILL.md # Gateway overview
+cat ~/.claude/plugins/cc-polymath/skills/{category}/INDEX.md          # All skills in category
+cat ~/.claude/plugins/cc-polymath/skills/discover-{category}/SKILL.md # Gateway overview
 ```
 
 **B) If searching root-level skills:**
@@ -153,9 +153,9 @@ SKILLS:
 7. api-error-handling - RFC 7807, validation errors
 
 LOAD:
-cat ~/.claude/skills/api/INDEX.md                  # Full details
-cat ~/.claude/skills/discover-api/SKILL.md         # Gateway overview
-cat ~/.claude/skills/api/rest-api-design.md        # Specific skill
+cat ~/.claude/plugins/cc-polymath/skills/api/INDEX.md                  # Full details
+cat ~/.claude/plugins/cc-polymath/skills/discover-api/SKILL.md         # Gateway overview
+cat ~/.claude/plugins/cc-polymath/skills/api/rest-api-design.md        # Specific skill
 ```
 
 **If ARGUMENT = search term:**
@@ -173,20 +173,20 @@ SEARCH: 'postgres'
 GATEWAY:
 → discover-database
   Keywords: PostgreSQL, MongoDB, Redis, query optimization
-  cat ~/.claude/skills/discover-database/SKILL.md
+  cat ~/.claude/plugins/cc-polymath/skills/discover-database/SKILL.md
 
 SKILLS:
 → postgres-query-optimization.md
   Debug slow queries, EXPLAIN plans, index design
-  cat ~/.claude/skills/database/postgres-query-optimization.md
+  cat ~/.claude/plugins/cc-polymath/skills/database/postgres-query-optimization.md
 
 → postgres-migrations.md
   Schema changes, zero-downtime deployments
-  cat ~/.claude/skills/database/postgres-migrations.md
+  cat ~/.claude/plugins/cc-polymath/skills/database/postgres-migrations.md
 
 → postgres-schema-design.md
   Designing schemas, relationships, data types
-  cat ~/.claude/skills/database/postgres-schema-design.md
+  cat ~/.claude/plugins/cc-polymath/skills/database/postgres-schema-design.md
 
 RELATED: discover-observability, discover-caching
 ```
@@ -290,7 +290,7 @@ No skills found matching '$ARGUMENTS'
 Try:
 - Broader search term
 - View all gateways: /skills list
-- Browse full catalog: cat ~/.claude/skills/README.md
+- Browse full catalog: cat ~/.claude/plugins/cc-polymath/skills/README.md
 - Check a category: /skills api
 ```
 
@@ -302,15 +302,15 @@ No project files detected in current directory.
 
 GENERAL-PURPOSE GATEWAYS:
 → discover-collab - Collaboration, documentation, CodeTour walkthroughs
-  Load: cat ~/.claude/skills/discover-collab/SKILL.md
+  Load: cat ~/.claude/plugins/cc-polymath/skills/discover-collab/SKILL.md
 
 ROOT-LEVEL SKILLS:
 → beads-workflow.md - Multi-session task management
 → skill-creation.md - Creating new atomic skills
 → skill-repo-discovery.md - Discover skills for repositories
 
 [View all: /skills list]
-[Browse catalog: cat ~/.claude/skills/README.md]
+[Browse catalog: cat ~/.claude/plugins/cc-polymath/skills/README.md]
 ```
 
 ## Remember
diff --git a/commands/skills/PROJECT_STATUS.md b/commands/skills/PROJECT_STATUS.md
@@ -10,7 +10,7 @@
 
 ## What Was Built
 
-A context-aware skills discovery slash command for Claude Code that helps users discover and activate relevant skills from their `~/.claude/skills/` library using a gateway-based progressive loading architecture.
+A context-aware skills discovery slash command for Claude Code that helps users discover and activate relevant skills from their `~/.claude/plugins/cc-polymath/skills/` library using a gateway-based progressive loading architecture.
 
 ## Project Files
 
@@ -175,15 +175,15 @@ Complete removal with no traces left.
 
 **Dependencies:**
 - None (uses Claude Code built-in slash command system)
-- Reads from existing `~/.claude/skills/` directory
+- Reads from existing `~/.claude/plugins/cc-polymath/skills/` directory
 - Compatible with all skill discovery mechanisms
 
 ### Read Operations
 
 The command reads from:
-- `~/.claude/skills/README.md` (master catalog)
-- `~/.claude/skills/{category}/INDEX.md` (category indexes)
-- `~/.claude/skills/discover-*/SKILL.md` (gateway skills)
+- `~/.claude/plugins/cc-polymath/skills/README.md` (master catalog)
+- `~/.claude/plugins/cc-polymath/skills/{category}/INDEX.md` (category indexes)
+- `~/.claude/plugins/cc-polymath/skills/discover-*/SKILL.md` (gateway skills)
 - Current working directory (for project detection)
 - Conversation context (provided by Claude Code)
 
diff --git a/commands/skills/QUICK_START.md b/commands/skills/QUICK_START.md
@@ -24,10 +24,10 @@ Restart Claude Code, then try:
 ```
 RECOMMENDED FOR THIS PROJECT:
 → discover-frontend
-  cat ~/.claude/skills/discover-frontend/SKILL.md
+  cat ~/.claude/plugins/cc-polymath/skills/discover-frontend/SKILL.md
 
 → discover-database
-  cat ~/.claude/skills/discover-database/SKILL.md
+  cat ~/.claude/plugins/cc-polymath/skills/discover-database/SKILL.md
 
 CATEGORIES (292 skills):
 Frontend (8) | Database (8) | API (7) | Testing (6) | Diagrams (8) | ML (30)
diff --git a/commands/skills/README.md b/commands/skills/README.md
@@ -97,7 +97,7 @@ RECOMMENDED FOR THIS PROJECT:
 CATEGORIES (292 total skills):
 Frontend (8) | Database (8) | API (7) | Testing (6) | Diagrams (8) | ML (30)
 Math (19) | Debugging (14) | Build Systems (8) | Caching (7) | Observability (8)
-[View full catalog: ~/.claude/skills/README.md]
+[View full catalog: ~/.claude/plugins/cc-polymath/skills/README.md]
 
 COMMANDS:
 /skills frontend     - View all Frontend skills
@@ -122,9 +122,9 @@ SKILLS:
 8. nextjs-seo - SEO best practices, metadata, structured data
 
 LOAD:
-cat ~/.claude/skills/frontend/INDEX.md                  # Full details
-cat ~/.claude/skills/discover-frontend/SKILL.md         # Gateway overview
-cat ~/.claude/skills/frontend/react-component-patterns.md  # Specific skill
+cat ~/.claude/plugins/cc-polymath/skills/frontend/INDEX.md                  # Full details
+cat ~/.claude/plugins/cc-polymath/skills/discover-frontend/SKILL.md         # Gateway overview
+cat ~/.claude/plugins/cc-polymath/skills/frontend/react-component-patterns.md  # Specific skill
 ```
 
 ### Search Results (`/skills postgres`)
@@ -135,20 +135,20 @@ SEARCH: 'postgres'
 GATEWAY:
 → discover-database
   Keywords: PostgreSQL, MongoDB, Redis, query optimization
-  cat ~/.claude/skills/discover-database/SKILL.md
+  cat ~/.claude/plugins/cc-polymath/skills/discover-database/SKILL.md
 
 SKILLS:
 → postgres-query-optimization.md
   Debug slow queries, EXPLAIN plans, index design
-  cat ~/.claude/skills/database/postgres-query-optimization.md
+  cat ~/.claude/plugins/cc-polymath/skills/database/postgres-query-optimization.md
 
 → postgres-migrations.md
   Schema changes, zero-downtime deployments
-  cat ~/.claude/skills/database/postgres-migrations.md
+  cat ~/.claude/plugins/cc-polymath/skills/database/postgres-migrations.md
 
 → postgres-schema-design.md
   Designing schemas, relationships, data types
-  cat ~/.claude/skills/database/postgres-schema-design.md
+  cat ~/.claude/plugins/cc-polymath/skills/database/postgres-schema-design.md
 
 RELATED: discover-observability, discover-caching
 ```
@@ -174,9 +174,9 @@ Based on detected context, it recommends skills that:
 ### Read-Only Operations
 
 The command **only reads** from:
-- `~/.claude/skills/README.md` (master catalog)
-- `~/.claude/skills/{category}/INDEX.md` (category indexes)
-- `~/.claude/skills/discover-*/SKILL.md` (gateway skills)
+- `~/.claude/plugins/cc-polymath/skills/README.md` (master catalog)
+- `~/.claude/plugins/cc-polymath/skills/{category}/INDEX.md` (category indexes)
+- `~/.claude/plugins/cc-polymath/skills/discover-*/SKILL.md` (gateway skills)
 - Current working directory (for project detection)
 
 It **never modifies**:
@@ -239,15 +239,15 @@ The `cc-polymath` plugin should no longer appear in the list. All commands (incl
 
 **Possible causes:**
 - Empty/new project directory → Expected behavior, shows general skills
-- Skills catalog not found → Check `~/.claude/skills/README.md` exists
+- Skills catalog not found → Check `~/.claude/plugins/cc-polymath/skills/README.md` exists
 
 ### Skills Catalog Not Found
 
 **Problem:** Error message about missing `README.md`
 
 **Solution:**
-1. Verify skills directory: `ls ~/.claude/skills/`
-2. Check catalog exists: `cat ~/.claude/skills/README.md`
+1. Verify skills directory: `ls ~/.claude/plugins/cc-polymath/skills/`
+2. Check catalog exists: `cat ~/.claude/plugins/cc-polymath/skills/README.md`
 3. If missing, restore from your skills repository (cc-polymath)
 
 ## Examples
@@ -309,7 +309,7 @@ cd ~/projects/slow-app
 
 This slash command is designed to be self-contained and maintenance-free. However, if you find issues or have suggestions:
 
-1. The command reads from `~/.claude/skills/README.md` (master catalog)
+1. The command reads from `~/.claude/plugins/cc-polymath/skills/README.md` (master catalog)
 2. Keep that file updated as you add new skills
 3. Update individual category `INDEX.md` files as needed
 4. The command will automatically show new skills
diff --git a/docs/FAQ.md b/docs/FAQ.md
diff --git a/docs/FIRST_CONVERSATIONS.md b/docs/FIRST_CONVERSATIONS.md
diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
diff --git a/docs/WALKTHROUGHS.md b/docs/WALKTHROUGHS.md
diff --git a/scripts/demo-skills.sh b/scripts/demo-skills.sh
diff --git a/scripts/diagnose.sh b/scripts/diagnose.sh
diff --git a/scripts/verify-install.sh b/scripts/verify-install.sh

Original file line number	Diff line number	Diff line change
`@@ -39,6 +39,5 @@`
`39`	`39`	`"dspy",`
`40`	`40`	`"context-efficient"`
`41`	`41`	`],`
`42`		`- "commands": "./commands",`
`43`		`- "skills": "./skills"`
	`42`	`+ "commands": "./commands"`
`44`	`43`	`}`