Skip to content

Commit 789295e

Browse files
randrand
committed
feat: Convert to Claude Code plugin architecture (v2.0.0)
Transform cc-polymath from manual installation to Claude Code plugin system. This enables one-command installation, automatic updates, and marketplace distribution. Changes: - Add .claude-plugin/plugin.json manifest for plugin system - Add LICENSE (MIT) for marketplace compatibility - Rename slash-commands/ to commands/ (plugin convention) - Remove install.sh and uninstall.sh (no longer needed) - Update README.md with plugin installation as primary method - Update commands/skills/README.md for plugin workflow - Add MIGRATION.md guide for users migrating from manual installation - Add PLUGIN.md with technical details and development guide Plugin structure: - 292 skills across 31 categories (unchanged) - 28 gateway skills for progressive loading (unchanged) - /skills command for context-aware discovery (unchanged) - Gateway-based architecture preserved (unchanged) Installation changes: - Before: git clone + ./commands/install.sh - After: /plugin install https://github.com/rand/cc-polymath Benefits: - One-command installation and updates - Automatic command registration - Better version management - Cleaner file organization - Marketplace distribution ready Breaking changes: - Installation location moved from ~/.claude/skills to ~/.claude/plugins/cc-polymath/ - Manual installation scripts removed (use plugin system instead) - See MIGRATION.md for upgrade instructions
1 parent 2451780 commit 789295e

11 files changed

Lines changed: 860 additions & 167 deletions

File tree

‎.claude-plugin/plugin.json‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"name": "cc-polymath",
3+
"version": "2.0.0",
4+
"description": "292 atomic skills with gateway-based progressive loading for Claude Code. Comprehensive coverage of API design, databases, ML, diagrams (Mermaid), mathematics, testing, infrastructure, and more.",
5+
"author": "rand",
6+
"homepage": "https://github.com/rand/cc-polymath",
7+
"repository": "https://github.com/rand/cc-polymath",
8+
"license": "MIT",
9+
"keywords": [
10+
"skills",
11+
"gateway",
12+
"progressive-loading",
13+
"diagrams",
14+
"mermaid",
15+
"ml",
16+
"api",
17+
"database",
18+
"testing",
19+
"infrastructure",
20+
"mathematics",
21+
"debugging",
22+
"frontend",
23+
"backend"
24+
]
25+
}

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 rand
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎MIGRATION.md‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
# Migration Guide: Manual Installation → Plugin
2+
3+
This guide is for users who previously installed cc-polymath manually using `install.sh` and are migrating to the new plugin system.
4+
5+
## Why Migrate?
6+
7+
The plugin system provides:
8+
- ✅ **One-command installation** - No scripts, no manual syncing
9+
- ✅ **Automatic updates** - Pull latest version with `/plugin update`
10+
- ✅ **Cleaner installation** - No files in `~/.claude/skills` or `~/.claude/commands`
11+
- ✅ **Better isolation** - Plugin data stays in `~/.claude/plugins/cc-polymath/`
12+
- ✅ **Version management** - Track which version you're using
13+
- ✅ **Marketplace distribution** - Discover and share plugins easily
14+
15+
## Migration Steps
16+
17+
### 1. Backup Your Data (Optional)
18+
19+
If you've customized any skills or commands, back them up:
20+
21+
```bash
22+
# Backup skills
23+
cp -r ~/.claude/skills ~/.claude/skills.backup
24+
25+
# Backup commands
26+
cp -r ~/.claude/commands ~/.claude/commands.backup
27+
```
28+
29+
### 2. Uninstall Manual Installation
30+
31+
Remove the manually installed files:
32+
33+
```bash
34+
# Remove skills directory
35+
rm -rf ~/.claude/skills
36+
37+
# Remove /skills command
38+
rm ~/.claude/commands/skills.md
39+
```
40+
41+
**Note:** If you have other custom commands in `~/.claude/commands/`, only remove `skills.md`:
42+
43+
```bash
44+
ls ~/.claude/commands/ # Check what's there
45+
rm ~/.claude/commands/skills.md # Remove only skills.md
46+
```
47+
48+
### 3. Install Plugin
49+
50+
Install cc-polymath as a plugin:
51+
52+
```bash
53+
/plugin install https://github.com/rand/cc-polymath
54+
```
55+
56+
That's it! The plugin system will:
57+
- Download all 292 skills to `~/.claude/plugins/cc-polymath/skills/`
58+
- Register the `/skills` command automatically
59+
- Make everything available immediately
60+
61+
### 4. Verify Installation
62+
63+
Check that the plugin is installed:
64+
65+
```bash
66+
/plugin list
67+
```
68+
69+
You should see:
70+
```
71+
cc-polymath (v2.0.0) - 292 atomic skills with gateway-based progressive loading
72+
```
73+
74+
Test the `/skills` command:
75+
76+
```bash
77+
/skills
78+
```
79+
80+
You should see skill recommendations and categories.
81+
82+
### 5. Restore Customizations (If Any)
83+
84+
If you customized any skills, you can copy them to the plugin directory:
85+
86+
```bash
87+
# Example: Restore a custom skill
88+
cp ~/.claude/skills.backup/custom/my-skill.md \
89+
~/.claude/plugins/cc-polymath/skills/custom/my-skill.md
90+
```
91+
92+
**Note:** The plugin directory is at `~/.claude/plugins/cc-polymath/`, not `~/.claude/skills/`.
93+
94+
## What Changed
95+
96+
### Installation Location
97+
98+
**Before (Manual):**
99+
```
100+
~/.claude/skills/ # Skills directory
101+
~/.claude/commands/ # Commands directory
102+
```
103+
104+
**After (Plugin):**
105+
```
106+
~/.claude/plugins/cc-polymath/skills/ # Skills
107+
~/.claude/plugins/cc-polymath/commands/ # Commands
108+
```
109+
110+
### Installation Method
111+
112+
**Before (Manual):**
113+
```bash
114+
git clone https://github.com/rand/cc-polymath
115+
cd cc-polymath
116+
./commands/install.sh
117+
```
118+
119+
**After (Plugin):**
120+
```bash
121+
/plugin install https://github.com/rand/cc-polymath
122+
```
123+
124+
### Updating
125+
126+
**Before (Manual):**
127+
```bash
128+
cd ~/src/cc-polymath
129+
git pull
130+
./commands/install.sh # Re-run install
131+
```
132+
133+
**After (Plugin):**
134+
```bash
135+
/plugin update cc-polymath
136+
```
137+
138+
### Uninstallation
139+
140+
**Before (Manual):**
141+
```bash
142+
./commands/uninstall.sh
143+
```
144+
145+
**After (Plugin):**
146+
```bash
147+
/plugin uninstall cc-polymath
148+
```
149+
150+
## What Stayed the Same
151+
152+
### Skills Structure
153+
154+
The 292 skills across 31 categories are identical:
155+
- Same gateway architecture
156+
- Same progressive loading
157+
- Same skill content and guidance
158+
- Same category organization
159+
160+
### Skills Discovery
161+
162+
All discovery mechanisms work exactly the same:
163+
- `/skills` command (context-aware recommendations)
164+
- `/skills frontend` (browse by category)
165+
- `/skills postgres` (search by keyword)
166+
- Automatic gateway activation
167+
- Manual skill reading with `cat`
168+
169+
### Compatibility
170+
171+
All existing workflows continue to work:
172+
- Gateway skills still activate based on project context
173+
- Skills still compose with each other
174+
- All 28 gateways, 31 categories, 292 skills unchanged
175+
176+
## Troubleshooting
177+
178+
### `/skills` command not found after migration
179+
180+
**Solution:**
181+
```bash
182+
# Verify plugin is installed
183+
/plugin list
184+
185+
# If not listed, install it
186+
/plugin install https://github.com/rand/cc-polymath
187+
188+
# Restart Claude Code session
189+
```
190+
191+
### Skills not showing up
192+
193+
**Solution:**
194+
```bash
195+
# Check plugin directory exists
196+
ls ~/.claude/plugins/cc-polymath/skills/
197+
198+
# If empty, reinstall plugin
199+
/plugin uninstall cc-polymath
200+
/plugin install https://github.com/rand/cc-polymath
201+
```
202+
203+
### Want to keep both installations?
204+
205+
You can keep the manual installation in `~/.claude/skills/` for reference, but:
206+
- Only the plugin version will be used by `/skills` command
207+
- Gateway skills will activate from plugin location
208+
- This may cause confusion - recommended to remove manual installation
209+
210+
## Rollback (If Needed)
211+
212+
If you need to rollback to manual installation:
213+
214+
```bash
215+
# 1. Uninstall plugin
216+
/plugin uninstall cc-polymath
217+
218+
# 2. Restore backup
219+
cp -r ~/.claude/skills.backup ~/.claude/skills
220+
cp ~/.claude/commands.backup/skills.md ~/.claude/commands/skills.md
221+
222+
# 3. Restart Claude Code
223+
```
224+
225+
## Questions?
226+
227+
### How do I know which version I have?
228+
229+
**Plugin:**
230+
```bash
231+
/plugin list # Shows version number
232+
```
233+
234+
**Manual:**
235+
```bash
236+
cat ~/.claude/skills/README.md | grep "Version:"
237+
```
238+
239+
### Can I install both?
240+
241+
Technically yes, but not recommended. The plugin system will take precedence for commands and skill discovery.
242+
243+
### Will my custom skills be lost?
244+
245+
No, but you need to manually copy them from `~/.claude/skills/` to `~/.claude/plugins/cc-polymath/skills/` after installing the plugin.
246+
247+
### How do I contribute updates?
248+
249+
Same as before:
250+
1. Fork the repository: https://github.com/rand/cc-polymath
251+
2. Make changes to skills
252+
3. Submit a pull request
253+
254+
Once merged, users can update with `/plugin update cc-polymath`.
255+
256+
## Next Steps
257+
258+
After migration:
259+
1. Explore the plugin system: `/plugin list`, `/plugin help`
260+
2. Test your workflows with the plugin-based installation
261+
3. Remove backups if everything works: `rm -rf ~/.claude/skills.backup ~/.claude/commands.backup`
262+
4. Update any documentation or personal notes about installation
263+
264+
## Support
265+
266+
If you encounter issues during migration:
267+
1. Check this guide's troubleshooting section
268+
2. Review plugin documentation: `cat ~/.claude/plugins/cc-polymath/PLUGIN.md`
269+
3. Open an issue: https://github.com/rand/cc-polymath/issues
270+
271+
---
272+
273+
**Migration complete!** You're now using cc-polymath as a Claude Code plugin with cleaner installation, automatic updates, and better version management.

0 commit comments

Comments
 (0)