feat: v3.1.0 — new skills, spec compliance, end-to-end validation

Phase 1: Agent Skills spec compliance
- Add license, metadata, compatibility to all 40 gateway SKILL.md files
- Add spec validation (name format, description length) to tests/validate.sh

Phase 2: High-value new skills
- New MCP category (3 skills): server fundamentals, tool design, testing
- New Agentic category (3 skills): task decomposition, tool use, memory
- New engineering skills: code-review-rules, git-workflows
- New ML skill: prompt-engineering

Phase 3: Opinionated rules packs
- react-rules (43 rules), api-design-rules (35), sql-rules (33), security-rules (42)

Phase 4: Quality improvements
- Fix discover-collaboration gateway (was listing 0 skills, has 6)
- Add missing categories to skills/README.md (13 categories were unlisted)
- Update all INDEX.md files with new v3.1 skill entries
- Fix diagrams/INDEX.md and research/INDEX.md missing Total Skills headers
- Standardize stale counts across README, PLUGIN.md, docs/, MIGRATION.md
- Remove discover-backend references (gateway doesn't exist)

Phase 5: DX improvements
- Enhanced SessionStart hook with version and skill counts
- New skill-creator agent for generating spec-compliant skills
- Updated /skills command with accurate mappings and counts

Testing:
- Property-based test suite (22 tests) validating structural invariants
- All gateway frontmatter, cross-references, skill counts, config consistency

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: efficient skill management with progressive discovery across 31+ domains",
+  "description": "Official marketplace for cc-polymath: efficient skill management with progressive discovery across 33+ domains",
   "owner": {
     "name": "rand",
     "url": "https://github.com/rand/cc-polymath"
@@ -9,8 +9,8 @@
     {
       "name": "cc-polymath",
       "source": "./",
-      "description": "Efficient skill management with progressive discovery — 400 production-ready skills across 31+ domains.",
-      "version": "3.0.0"
+      "description": "Efficient skill management with progressive discovery — 410+ production-ready skills across 33+ domains.",
+      "version": "3.1.0"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cc-polymath",
-  "version": "3.0.0",
-  "description": "Efficient skill management system with progressive discovery — 400 production-ready skills across 31+ domains",
+  "version": "3.1.0",
+  "description": "Efficient skill management system with progressive discovery — 410+ production-ready skills across 33+ domains",
   "author": {
     "name": "rand"
   },
@@ -37,6 +37,11 @@
     "observability",
     "pyo3",
     "dspy",
+    "mcp",
+    "agentic",
+    "prompt-engineering",
+    "git-workflows",
+    "code-review",
     "context-efficient"
   ],
   "skills": "./skills",
@@ -49,7 +54,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo 'cc-polymath plugin root: ${CLAUDE_PLUGIN_ROOT}'"
+            "command": "echo 'cc-polymath v3.1.0 loaded (410+ skills, 40 gateways). Use /skills to discover relevant skills. Root: ${CLAUDE_PLUGIN_ROOT}'"
           }
         ]
       }

MIGRATION.md

@@ -54,7 +54,7 @@ Install cc-polymath as a plugin:
 ```
 
 That's it! The plugin system will:
-- Download all 400 skills to `<cc-polymath-root>/skills/`
+- Download all 410+ 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) - 400 atomic skills with gateway-based progressive loading
+cc-polymath (v2.0.0) - 410+ atomic skills with gateway-based progressive loading
 ```
 
 Test the `/skills` command:
@@ -151,7 +151,7 @@ git pull
 
 ### Skills Structure
 
-The 400 skills across 31 categories are identical:
+The 410+ skills across 33+ 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 38 gateways, 31 categories, 400 skills unchanged
+- All 40 gateways, 33+ categories, 410+ skills unchanged
 
 ## Troubleshooting
 

PLUGIN.md

@@ -1,23 +1,23 @@
 # cc-polymath Claude Code Plugin
 
-**Version:** 2.0.0
+**Version:** 3.1.0
 **Type:** Skills & Commands Plugin
 **Author:** rand
 **License:** MIT
 
 ## Overview
 
-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.
+cc-polymath is a comprehensive Claude Code plugin that provides 410+ atomic, production-ready skills across 33+ 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/                       # 400 skills, 31+ domains
+├── skills/                       # 410+ skills, 33+ domains
 │   ├── README.md                 # Master catalog (gateway index)
-│   ├── discover-*/               # 38 gateway skills
+│   ├── discover-*/               # 40 gateway skills
 │   │   └── SKILL.md
 │   ├── api/                      # Category directories
 │   │   └── INDEX.md              # Category index
@@ -27,19 +27,17 @@ cc-polymath/
 │   ├── diagrams/
 │   ├── ml/
 │   ├── math/
-│   └── [28+ more categories...]
+│   └── [30+ more categories...]
 ├── commands/                     # Slash commands
-│   ├── skills.md                 # /skills command
-│   ├── discover-api.md           # /discover-api command
-│   ├── discover-database.md      # /discover-database command
-│   ├── discover-frontend.md      # /discover-frontend command
-│   ├── discover-ml.md            # /discover-ml command
-│   └── [6+ more gateway commands...]
+│   └── skills.md                 # /skills command
 ├── agents/                       # Specialized subagents
 │   ├── skill-navigator.md        # Skills library expert guide
 │   ├── architecture-advisor.md   # System design specialist
-│   └── polyglot-engineer.md      # Multi-language expert
-├── marketplace.json              # Marketplace configuration
+│   ├── polyglot-engineer.md      # Multi-language expert
+│   └── skill-creator.md          # Generates new spec-compliant skills
+├── .claude-plugin/
+│   ├── plugin.json               # Plugin manifest
+│   └── marketplace.json          # Marketplace configuration
 ├── LICENSE                       # MIT License
 ├── README.md                     # Main documentation
 ├── PLUGIN.md                     # This file
@@ -65,8 +63,8 @@ Install the plugin with a single command:
 Claude Code will:
 1. Clone the repository to `<cc-polymath-root>/`
 2. Register all slash commands (e.g., `/skills`, `/discover-api`, etc.)
-3. Make all 400 skills available for discovery
-4. Register specialized subagents (skill-navigator, architecture-advisor, polyglot-engineer)
+3. Make all 410+ skills available for discovery
+4. Register specialized subagents (skill-navigator, architecture-advisor, polyglot-engineer, skill-creator)
 5. Enable gateway-based progressive loading
 
 ### For Developers
@@ -85,19 +83,19 @@ cd cc-polymath
 
 ### Three-Tier Progressive Loading
 
-**Tier 1: Gateway Skills (28 skills)**
+**Tier 1: Gateway Skills (40 skills)**
 - Lightweight entry points (~200 lines each)
 - Activate based on project keywords
 - Guide to category indexes
 - Examples: `discover-frontend`, `discover-database`, `discover-ml`
 
-**Tier 2: Category Indexes (31 indexes)**
+**Tier 2: Category Indexes (33+ indexes)**
 - Comprehensive category overviews
 - List all skills in category with descriptions
 - Load-on-demand when category is relevant
 - Examples: `api/INDEX.md`, `database/INDEX.md`
 
-**Tier 3: Individual Skills (400 skills)**
+**Tier 3: Individual Skills (410+ skills)**
 - Deep, actionable guidance (~320 lines avg)
 - Load only when specifically needed
 - Contain code examples, best practices, workflows
@@ -118,7 +116,7 @@ Project detected → Gateway activates → Category shown → Skill loaded
 ```
 
 **Context Savings:**
-- Loading all 400 skills: ~143,000 lines
+- Loading all 410+ skills: ~143,000 lines
 - Gateway-based approach: ~200-1,500 lines per session
 - **98-99% context reduction**
 
@@ -171,10 +169,10 @@ These commands complement the auto-discovery system by providing explicit invoca
 
 ## Specialized Subagents
 
-cc-polymath includes three specialized subagents that leverage the skills library for focused workflows:
+cc-polymath includes four specialized subagents that leverage the skills library for focused workflows:
 
 ### `skill-navigator`
-**Purpose:** Expert guide for navigating the 400-skill library
+**Purpose:** Expert guide for navigating the 410+ skill library
 
 **Use when:**
 - Users need help finding relevant skills
@@ -220,7 +218,7 @@ Leverages language-specific skills and can implement solutions in the best-fit l
 
 ## Skill Categories
 
-### Available Categories (31 total)
+### Available Categories (33+ total)
 
 | Category | Skills | Description |
 |----------|--------|-------------|
@@ -247,7 +245,7 @@ Leverages language-specific skills and can implement solutions in the best-fit l
 {
   "name": "cc-polymath",
   "version": "2.0.0",
-  "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.",
+  "description": "410+ atomic, production-ready skills with gateway-based progressive loading for Claude Code. 33+ domains including API design, databases, ML, diagrams (Mermaid), mathematics, testing, infrastructure, cryptography, protocols, MCP, agentic workflows, and more. Context-efficient three-tier architecture with auto-discovery gateways.",
   "author": {
     "name": "rand"
   },
@@ -274,7 +272,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 400 skills across 31+ domains
+  - Updated to 410+ skills across 33+ domains
   - Enhanced keywords for better discoverability
   - Converted to Claude Code plugin
   - Added plugin manifest
@@ -283,7 +281,7 @@ Leverages language-specific skills and can implement solutions in the best-fit l
   - Added LICENSE for marketplace compatibility
 
 - **v1.0.0** - Manual installation
-  - 400 skills across 31 categories
+  - 410+ skills across 33+ categories
   - Gateway-based progressive loading
   - Manual sync with install.sh
 
@@ -510,7 +508,7 @@ cd <cc-polymath-root>/skills/
 ├── .claude-plugin/
 │   └── plugin.json          # Metadata read by Claude Code
 ├── skills/                   # Discovered by skill system
-│   ├── README.md             # Master catalog (38 gateways)
+│   ├── README.md             # Master catalog (40 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-400-green)](skills/)
+[![Skills](https://img.shields.io/badge/Skills-410%2B-green)](skills/)
 [![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)
 
 **Context-efficient development knowledge via progressive skill discovery**
@@ -42,7 +42,7 @@ This creates an challenging tradeoff between comprehensive coverage and context
 
 ## The Solution: Atomic Skills + Progressive Discovery
 
-### Atomic Skills (400 total)
+### Atomic Skills (410+ total)
 Each skill is **focused, self-contained, and composable**:
 - Average 320 lines - small enough to load quickly
 - Single responsibility - covers one clear topic
@@ -53,7 +53,7 @@ Each skill is **focused, self-contained, and composable**:
 
 ### Three-Tier Architecture
 
-**Tier 1: Gateway Skills (31 auto-discovered Agent Skills)**
+**Tier 1: Gateway Skills (40 auto-discovered Agent Skills)**
 Lightweight entry points that activate automatically based on keywords:
 - `discover-api` → triggers on "REST", "GraphQL", "authentication"
 - `discover-database` → triggers on "PostgreSQL", "MongoDB", "Redis"
@@ -184,7 +184,7 @@ Complete implementation guides loaded only when needed:
 /plugin install https://github.com/rand/cc-polymath
 ```
 
-That's it! All 400 skills and the `/skills` command are immediately available.
+That's it! All 410+ 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.
 
 ---
 
-**400 atomic skills** • **41 gateway Agent Skills** • **35+ categories** • **100% CI-validated**
+**410+ atomic skills** • **40 gateway Agent Skills** • **33+ categories** • **100% CI-validated**

agents/skill-creator.md

@@ -0,0 +1,83 @@
+---
+name: skill-creator
+description: Generate spec-compliant skills for the cc-polymath library. Takes a topic/domain and produces a well-structured SKILL.md with proper frontmatter, progressive loading, and atomic design.
+tools: Read, Write, Edit, Glob, Grep
+---
+
+# Skill Creator
+
+Generate new skills for the cc-polymath library that follow the Agent Skills spec and cc-polymath conventions.
+
+## Process
+
+### 1. Understand the Request
+- What domain/topic does the skill cover?
+- Is this a gateway skill, INDEX, or leaf skill?
+- Which existing category does it belong to (or is it a new category)?
+
+### 2. Check Existing Skills
+- Read `skills/README.md` for the master catalog
+- Check if a similar skill already exists using Grep
+- Identify the target category directory
+
+### 3. Generate the Skill
+
+**For leaf skills** (`skills/{category}/{name}.md`):
+```yaml
+---
+name: {category}-{skill-name}
+description: One-line description of the skill (up to 1024 chars)
+---
+```
+
+Body structure:
+- `# {Title}` — clear, descriptive
+- `**Scope**: ...` / `**Lines**: ~N`
+- `## When to Use This Skill` — bullet list of triggers
+- `## Core Concepts` — organized subsections with code examples
+- `## Anti-Patterns` — common mistakes with corrections
+- `## Checklist` — quick reference for applying the skill
+- `## Related Skills` — cross-references using `<cc-polymath-root>/skills/...`
+
+**For gateway skills** (`skills/discover-{category}/SKILL.md`):
+```yaml
+---
+name: discover-{category}
+description: Automatically discover {category} skills when working with {keywords}. Activates for {domain} tasks.
+license: MIT
+metadata:
+  author: rand
+  version: "3.1"
+compatibility: Designed for Claude Code. Compatible with any agent supporting the Agent Skills format.
+---
+```
+
+Body structure:
+- Title, description
+- When This Skill Activates (bullet list)
+- Available Skills (numbered quick reference)
+- Load commands using `Read <cc-polymath-root>/skills/...`
+- Common Workflows (sequences of skills)
+- Progressive Loading section
+
+**For INDEX.md** (`skills/{category}/INDEX.md`):
+- Category Overview (Total Skills, Focus, Use Cases)
+- Each skill: Description, Lines, Use When (bullets), Key Concepts
+- Common Workflows with sequences
+- Skill Combinations with other categories
+
+### 4. Quality Checks
+- Name is kebab-case, 1-64 characters
+- Description ≤ 1024 characters
+- Leaf skills: 200-400 lines, focused on one topic
+- Code examples are practical and correct
+- Cross-references use `<cc-polymath-root>` prefix
+- No overlap with existing skills
+
+## Design Principles
+
+- **Atomic**: One skill = one concept. If it covers two things, split it.
+- **Actionable**: Rules and patterns, not encyclopedic reference.
+- **Context-efficient**: Target ~3K tokens per leaf skill. Use progressive loading.
+- **Opinionated**: State best practices directly. "Do X" not "You could do X or Y."
+- **Example-driven**: Show code, not just explain concepts.