feat: v3.0.0 — fix path resolution, modernize plugin, clean up commands

Replace all hardcoded ~/.claude/skills/ and ~/.claude/plugins/cc-polymath/
paths with <cc-polymath-root> placeholder resolved via SessionStart hook.
This fixes broken skill cross-references for marketplace installs.

- Add hooks/hooks.json with SessionStart hook injecting plugin root path
- Replace 1200+ hardcoded path references across 113 files
- Remove bash code block markers from Read tool instructions
- Bump version to 3.0.0 in plugin.json and marketplace.json
- Add skills, agents, hooks fields to plugin.json
- Remove 10 redundant commands/discover-*.md (duplicated by gateway skills)
- Remove stale commands/skills/ subdirectory (old slash-commands docs)
- Reconcile skill counts: 400 skills, 38 gateways, 39 categories
- Fix broken cross-ref to discover-collab → discover-collaboration
- Remove broken ref to nonexistent protocols/protocol-debugging.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: rand

.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-polymath-marketplace",
-  "description": "Official marketplace for cc-polymath: 447 atomic, production-ready skills with progressive loading",
+  "description": "Official marketplace for cc-polymath: efficient skill management with progressive discovery across 31+ domains",
   "owner": {
     "name": "rand",
     "url": "https://github.com/rand/cc-polymath"
@@ -9,8 +9,8 @@
     {
       "name": "cc-polymath",
       "source": "./",
-      "description": "447 atomic skills across 31+ domains with gateway-based progressive loading. Includes API design, databases, ML, diagrams, infrastructure, cryptography, and more.",
-      "version": "2.0.0"
+      "description": "Efficient skill management with progressive discovery — 400 production-ready skills across 31+ domains.",
+      "version": "3.0.0"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cc-polymath",
-  "version": "2.0.0",
-  "description": "447 atomic, production-ready skills with gateway-based progressive loading for Claude Code. 31+ domains including API design, databases, ML, diagrams (Mermaid), mathematics, testing, infrastructure, cryptography, protocols, and more. Context-efficient three-tier architecture with auto-discovery gateways.",
+  "version": "3.0.0",
+  "description": "Efficient skill management system with progressive discovery — 400 production-ready skills across 31+ domains",
   "author": {
     "name": "rand"
   },
@@ -39,5 +39,8 @@
     "dspy",
     "context-efficient"
   ],
-  "commands": "./commands"
+  "skills": "./skills",
+  "agents": "./agents",
+  "commands": "./commands",
+  "hooks": "./hooks"
 }

MIGRATION.md

@@ -8,7 +8,7 @@ The plugin system provides:
 - ✅ **One-command installation** - No scripts, no manual syncing
 - ✅ **Automatic updates** - Pull latest version with `/plugin update`
 - ✅ **Cleaner installation** - No files in `~/.claude/skills` or `~/.claude/commands`
-- ✅ **Better isolation** - Plugin data stays in `~/.claude/plugins/cc-polymath/`
+- ✅ **Better isolation** - Plugin data stays in `<cc-polymath-root>/`
 - ✅ **Version management** - Track which version you're using
 - ✅ **Marketplace distribution** - Discover and share plugins easily
 
@@ -54,7 +54,7 @@ Install cc-polymath as a plugin:
 ```
 
 That's it! The plugin system will:
-- Download all 292 skills to `~/.claude/plugins/cc-polymath/skills/`
+- Download all 400 skills to `<cc-polymath-root>/skills/`
 - Register the `/skills` command automatically
 - Make everything available immediately
 
@@ -68,7 +68,7 @@ Check that the plugin is installed:
 
 You should see:
 ```
-cc-polymath (v2.0.0) - 292 atomic skills with gateway-based progressive loading
+cc-polymath (v2.0.0) - 400 atomic skills with gateway-based progressive loading
 ```
 
 Test the `/skills` command:
@@ -86,25 +86,25 @@ If you customized any skills, you can copy them to the plugin directory:
 ```bash
 # Example: Restore a custom skill
 cp ~/.claude/skills.backup/custom/my-skill.md \
-   ~/.claude/plugins/cc-polymath/skills/custom/my-skill.md
+   <cc-polymath-root>/skills/custom/my-skill.md
 ```
 
-**Note:** The plugin directory is at `~/.claude/plugins/cc-polymath/`, not `~/.claude/skills/`.
+**Note:** The plugin directory is at `<cc-polymath-root>/`, not `<cc-polymath-root>/skills/`.
 
 ## What Changed
 
 ### Installation Location
 
 **Before (Manual):**
 ```
-~/.claude/skills/          # Skills directory
+<cc-polymath-root>/skills/          # Skills directory
 ~/.claude/commands/        # Commands directory
 ```
 
 **After (Plugin):**
 ```
-~/.claude/plugins/cc-polymath/skills/      # Skills
-~/.claude/plugins/cc-polymath/commands/    # Commands
+<cc-polymath-root>/skills/      # Skills
+<cc-polymath-root>/commands/    # Commands
 ```
 
 ### Installation Method
@@ -151,7 +151,7 @@ git pull
 
 ### Skills Structure
 
-The 292 skills across 31 categories are identical:
+The 400 skills across 31 categories are identical:
 - Same gateway architecture
 - Same progressive loading
 - Same skill content and guidance
@@ -171,7 +171,7 @@ All discovery mechanisms work exactly the same:
 All existing workflows continue to work:
 - Gateway skills still activate based on project context
 - Skills still compose with each other
-- All 28 gateways, 31 categories, 292 skills unchanged
+- All 38 gateways, 31 categories, 400 skills unchanged
 
 ## Troubleshooting
 
@@ -193,7 +193,7 @@ All existing workflows continue to work:
 **Solution:**
 ```bash
 # Check plugin directory exists
-ls ~/.claude/plugins/cc-polymath/skills/
+ls <cc-polymath-root>/skills/
 
 # If empty, reinstall plugin
 /plugin uninstall cc-polymath
@@ -202,7 +202,7 @@ ls ~/.claude/plugins/cc-polymath/skills/
 
 ### Want to keep both installations?
 
-You can keep the manual installation in `~/.claude/skills/` for reference, but:
+You can keep the manual installation in `<cc-polymath-root>/skills/` for reference, but:
 - Only the plugin version will be used by `/skills` command
 - Gateway skills will activate from plugin location
 - This may cause confusion - recommended to remove manual installation
@@ -232,17 +232,16 @@ cp ~/.claude/commands.backup/skills.md ~/.claude/commands/skills.md
 ```
 
 **Manual:**
-```bash
-cat ~/.claude/skills/README.md | grep "Version:"
-```
+Read <cc-polymath-root>/skills/README.md | grep "Version:"
+
 
 ### Can I install both?
 
 Technically yes, but not recommended. The plugin system will take precedence for commands and skill discovery.
 
 ### Will my custom skills be lost?
 
-No, but you need to manually copy them from `~/.claude/skills/` to `~/.claude/plugins/cc-polymath/skills/` after installing the plugin.
+No, but you need to manually copy them from `<cc-polymath-root>/skills/` to `<cc-polymath-root>/skills/` after installing the plugin.
 
 ### How do I contribute updates?
 
@@ -265,7 +264,7 @@ After migration:
 
 If you encounter issues during migration:
 1. Check this guide's troubleshooting section
-2. Review plugin documentation: `cat ~/.claude/plugins/cc-polymath/PLUGIN.md`
+2. Review plugin documentation: `Read <cc-polymath-root>/PLUGIN.md`
 3. Open an issue: https://github.com/rand/cc-polymath/issues
 
 ---

PLUGIN.md

@@ -7,17 +7,17 @@
 
 ## Overview
 
-cc-polymath is a comprehensive Claude Code plugin that provides 447 atomic, production-ready skills across 31+ domains, plus context-aware skill discovery commands and specialized subagents. It uses a gateway-based progressive loading architecture to minimize context usage while maximizing skill availability.
+cc-polymath is a comprehensive Claude Code plugin that provides 400 atomic, production-ready skills across 31+ domains, plus context-aware skill discovery commands and specialized subagents. It uses a gateway-based progressive loading architecture to minimize context usage while maximizing skill availability.
 
 ## Plugin Structure
 
 ```
 cc-polymath/
 ├── .claude-plugin/
 │   └── plugin.json              # Plugin manifest
-├── skills/                       # 447 skills, 31+ domains
+├── skills/                       # 400 skills, 31+ domains
 │   ├── README.md                 # Master catalog (gateway index)
-│   ├── discover-*/               # 28 gateway skills
+│   ├── discover-*/               # 38 gateway skills
 │   │   └── SKILL.md
 │   ├── api/                      # Category directories
 │   │   └── INDEX.md              # Category index
@@ -63,9 +63,9 @@ Install the plugin with a single command:
 ```
 
 Claude Code will:
-1. Clone the repository to `~/.claude/plugins/cc-polymath/`
+1. Clone the repository to `<cc-polymath-root>/`
 2. Register all slash commands (e.g., `/skills`, `/discover-api`, etc.)
-3. Make all 447 skills available for discovery
+3. Make all 400 skills available for discovery
 4. Register specialized subagents (skill-navigator, architecture-advisor, polyglot-engineer)
 5. Enable gateway-based progressive loading
 
@@ -97,7 +97,7 @@ cd cc-polymath
 - Load-on-demand when category is relevant
 - Examples: `api/INDEX.md`, `database/INDEX.md`
 
-**Tier 3: Individual Skills (447 skills)**
+**Tier 3: Individual Skills (400 skills)**
 - Deep, actionable guidance (~320 lines avg)
 - Load only when specifically needed
 - Contain code examples, best practices, workflows
@@ -118,7 +118,7 @@ Project detected → Gateway activates → Category shown → Skill loaded
 ```
 
 **Context Savings:**
-- Loading all 447 skills: ~143,000 lines
+- Loading all 400 skills: ~143,000 lines
 - Gateway-based approach: ~200-1,500 lines per session
 - **98-99% context reduction**
 
@@ -174,7 +174,7 @@ These commands complement the auto-discovery system by providing explicit invoca
 cc-polymath includes three specialized subagents that leverage the skills library for focused workflows:
 
 ### `skill-navigator`
-**Purpose:** Expert guide for navigating the 447-skill library
+**Purpose:** Expert guide for navigating the 400-skill library
 
 **Use when:**
 - Users need help finding relevant skills
@@ -247,7 +247,7 @@ Leverages language-specific skills and can implement solutions in the best-fit l
 {
   "name": "cc-polymath",
   "version": "2.0.0",
-  "description": "447 atomic, production-ready skills with gateway-based progressive loading for Claude Code. 31+ domains including API design, databases, ML, diagrams (Mermaid), mathematics, testing, infrastructure, cryptography, protocols, and more. Context-efficient three-tier architecture with auto-discovery gateways.",
+  "description": "400 atomic, production-ready skills with gateway-based progressive loading for Claude Code. 31+ domains including API design, databases, ML, diagrams (Mermaid), mathematics, testing, infrastructure, cryptography, protocols, and more. Context-efficient three-tier architecture with auto-discovery gateways.",
   "author": {
     "name": "rand"
   },
@@ -274,7 +274,7 @@ Leverages language-specific skills and can implement solutions in the best-fit l
   - Added 10 gateway discovery slash commands (`/discover-*`)
   - Created 3 specialized subagents (skill-navigator, architecture-advisor, polyglot-engineer)
   - Added marketplace.json for distribution
-  - Updated to 447 skills across 31+ domains
+  - Updated to 400 skills across 31+ domains
   - Enhanced keywords for better discoverability
   - Converted to Claude Code plugin
   - Added plugin manifest
@@ -283,7 +283,7 @@ Leverages language-specific skills and can implement solutions in the best-fit l
   - Added LICENSE for marketplace compatibility
 
 - **v1.0.0** - Manual installation
-  - 292 skills across 31 categories
+  - 400 skills across 31 categories
   - Gateway-based progressive loading
   - Manual sync with install.sh
 
@@ -295,10 +295,10 @@ Leverages language-specific skills and can implement solutions in the best-fit l
 ```
 
 **Process:**
-1. Claude Code clones repository to `~/.claude/plugins/cc-polymath/`
+1. Claude Code clones repository to `<cc-polymath-root>/`
 2. Reads `.claude-plugin/plugin.json` for metadata
 3. Registers commands from `commands/` directory
-4. Makes skills available at `~/.claude/plugins/cc-polymath/skills/`
+4. Makes skills available at `<cc-polymath-root>/skills/`
 
 ### Updates
 ```bash
@@ -318,7 +318,7 @@ Leverages language-specific skills and can implement solutions in the best-fit l
 
 **Process:**
 1. Unregisters all commands
-2. Removes `~/.claude/plugins/cc-polymath/` directory
+2. Removes `<cc-polymath-root>/` directory
 3. Cleans up plugin metadata
 4. No traces left in Claude Code configuration
 
@@ -483,7 +483,7 @@ cat skills/your-category/your-skill.md
 **Check:**
 ```bash
 # Verify plugin directory exists
-ls ~/.claude/plugins/cc-polymath/skills/
+ls <cc-polymath-root>/skills/
 
 # Reinstall if missing
 /plugin uninstall cc-polymath
@@ -494,7 +494,7 @@ ls ~/.claude/plugins/cc-polymath/skills/
 
 **Location:**
 ```bash
-cd ~/.claude/plugins/cc-polymath/skills/
+cd <cc-polymath-root>/skills/
 # Edit skills here
 # Changes will persist until plugin update
 ```
@@ -506,11 +506,11 @@ cd ~/.claude/plugins/cc-polymath/skills/
 ### File Structure
 
 ```
-~/.claude/plugins/cc-polymath/
+<cc-polymath-root>/
 ├── .claude-plugin/
 │   └── plugin.json          # Metadata read by Claude Code
 ├── skills/                   # Discovered by skill system
-│   ├── README.md             # Master catalog (28 gateways)
+│   ├── README.md             # Master catalog (38 gateways)
 │   ├── discover-*/SKILL.md   # Gateway skills
 │   └── */INDEX.md            # Category indexes
 ├── commands/                 # Auto-registered by plugin system

README.md

@@ -1,7 +1,7 @@
 # Atomic Skills for Claude Code
 
 [![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-blue)](https://docs.claude.com/en/docs/claude-code/plugins)
-[![Skills](https://img.shields.io/badge/Skills-447-green)](skills/)
+[![Skills](https://img.shields.io/badge/Skills-400-green)](skills/)
 [![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)
 
 **Context-efficient development knowledge via progressive skill discovery**
@@ -18,7 +18,7 @@
 ```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
+bash <cc-polymath-root>/scripts/verify-install.sh  # Verify installation
 ```
 
 **Learn more**:
@@ -42,7 +42,7 @@ This creates an challenging tradeoff between comprehensive coverage and context
 
 ## The Solution: Atomic Skills + Progressive Discovery
 
-### Atomic Skills (447 total)
+### Atomic Skills (400 total)
 Each skill is **focused, self-contained, and composable**:
 - Average 320 lines - small enough to load quickly
 - Single responsibility - covers one clear topic
@@ -184,7 +184,7 @@ Complete implementation guides loaded only when needed:
 /plugin install https://github.com/rand/cc-polymath
 ```
 
-That's it! All 447 skills and the `/skills` command are immediately available.
+That's it! All 400 skills and the `/skills` command are immediately available.
 
 **For local development or testing**:
 ```bash
@@ -545,4 +545,4 @@ Feel free to fork and adapt for your own use. Pull requests welcome.
 
 ---
 
-**447 atomic skills** • **41 gateway Agent Skills** • **35+ categories** • **100% CI-validated**
+**400 atomic skills** • **41 gateway Agent Skills** • **35+ categories** • **100% CI-validated**

STATUS.md

@@ -182,7 +182,7 @@ This initiative creates a comprehensive PyO3 skill library covering:
   - ✅ Skill file (692 lines): Complete web framework integration guide
   - ✅ REFERENCE.md (2,262 lines): FastAPI, Flask, Django, WebSocket patterns
   - ✅ 3 production scripts (2,839 lines)
-  - ✅ 10 examples (3,447 lines)
+  - ✅ 10 examples (3,400 lines)
 - **Scripts**:
   - api_benchmark.py (947 lines): API performance benchmarking
   - middleware_generator.py (1,056 lines): Middleware boilerplate generator

agents/skill-navigator.md

@@ -1,13 +1,13 @@
 ---
 name: skill-navigator
-description: Expert guide for navigating and discovering the 447-skill cc-polymath library. Use when users need help finding relevant skills or understanding skill coverage.
+description: Expert guide for navigating and discovering the 400-skill cc-polymath library. Use when users need help finding relevant skills or understanding skill coverage.
 tools: Read, Grep, Glob
 model: haiku
 ---
 
 # Skill Navigator
 
-You are an expert guide for the cc-polymath skills library, which contains 447 atomic, production-ready skills across 31+ domains.
+You are an expert guide for the cc-polymath skills library, which contains 400 atomic, production-ready skills across 31+ domains.
 
 ## Your Role
 
@@ -19,13 +19,13 @@ Help users efficiently discover and activate relevant skills by:
 
 ## Three-Tier Architecture
 
-**Tier 1 - Gateway Skills (28 auto-discovered):**
+**Tier 1 - Gateway Skills (38 auto-discovered):**
 Entry points that activate based on keywords. Located in `skills/discover-*/SKILL.md`
 
 **Tier 2 - Category Indexes (31+ domains):**
 Full skill listings at `skills/{category}/INDEX.md`
 
-**Tier 3 - Individual Skills (447 skills):**
+**Tier 3 - Individual Skills (400 skills):**
 Complete implementation guides at `skills/{category}/{skill-name}.md`
 
 ## Discovery Process