Something rewrote every `/skills` into `~/.hanzo/skills` without checking what sat to its left, so the install docs sent readers to `~/.claude~/.hanzo/skills/`, the plugin dir became `hanzo-skills~/.hanzo/skills/`, and the issue tracker was advertised at `github.com/hanzoai~/.hanzo/skills/issues`. The same pass turned a noun in `commands/skills.md` into "skills", so `/skills` greeted the reader with "292 skills, 28 skills". Only the glued occurrences are reverted — `~/.hanzo/skills/` is a real path and the corpus keeps it. Three references point at files this tree does not have, and one recipe cloned `skills` and then cd'd into `hanzo-skills`. Co-authored-by: Hanzo Dev <[email protected]>
13 KiB
hanzo-skills Claude Code Plugin
Version: 2.0.0 Type: Skills & Commands Plugin Author: rand License: MIT
Overview
hanzo-skills is a comprehensive Claude Code plugin that provides 292 atomic, composable skills across 31 categories, plus context-aware skill discovery commands. It uses a skill-based progressive loading architecture to minimize context usage while maximizing skill availability.
Plugin Structure
hanzo-skills/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest
├── skills/ # 292 skills, 31 categories
│ ├── README.md # Master catalog (skill index)
│ ├── <name>/SKILL.md # one skill, one directory
│ │ └── SKILL.md
│ ├── api/ # Category directories
│ │ └── INDEX.md # Category index
│ │ └── *.md # Individual skills
│ ├── database/
│ ├── testing/
│ ├── diagrams/
│ ├── ml/
│ ├── math/
│ └── [28 more categories...]
├── commands/
│ └── skills.md # /skills command
├── LICENSE # MIT License
├── README.md # Main documentation
├── PLUGIN.md # This file
└── MIGRATION.md # Migration guide
Installation
For Users
Install the plugin with a single command:
/plugin install https://github.com/hanzoai/skills
Claude Code will:
- Clone the repository to
~/.claude/plugins/hanzo-skills/ - Register all commands (e.g.,
/skills) - Make all 292 skills available for discovery
- Enable skill-based progressive loading
For Developers
Clone the repository to develop locally:
git clone https://github.com/hanzoai/skills
cd skills
# Install as plugin from local directory
/plugin install file://$(pwd)
Plugin Architecture
Three-Tier Progressive Loading
Tier 1: Skills (28 skills)
- Lightweight entry points (~200 lines each)
- Activate based on project keywords
- Guide to category indexes
- Examples:
frontend,database,ml
Tier 2: Category Indexes (31 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 (233 skills)
- Deep, actionable guidance (~300 lines avg)
- Load only when specifically needed
- Contain code examples, best practices, workflows
- Examples:
api/rest-design.md,database/postgres-optimization.md
Context Management
Lazy Loading:
- skills load first (minimal context)
- Category indexes load on-demand
- Individual skills load when explicitly needed
Progressive Discovery:
Project detected → the skill activates → its files are read as needed
(~200 lines) (~500 lines) (~300 lines)
Context Savings:
- Loading all 292 skills: ~87,600 lines
- Skill-based approach: ~200-1,000 lines per session
- 98-99% context reduction
Commands
/skills - Skill Discovery
Purpose: Context-aware skill discovery and browsing
Usage:
/skills # Recommendations based on project
/skills frontend # Browse frontend skills
/skills postgres # Search for postgres-related skills
/skills list # Show all categories
Features:
- Detects project type (Next.js, Go, Rust, Python, etc.)
- Recommends relevant skills automatically
- Non-destructive (read-only operations)
- CLI-optimized output (max 25 lines)
Implementation: commands/skills.md (325 lines)
Skill Categories
Available Categories (31 total)
| Category | Skills | Description |
|---|---|---|
| API | 7 | REST, GraphQL, gRPC, authentication, rate limiting |
| Testing | 6 | Unit, integration, E2E, property-based testing |
| Database | 8 | PostgreSQL, MongoDB, Redis, migrations, optimization |
| Frontend | 8 | React, Next.js, state management, accessibility |
| Diagrams | 8 | Mermaid, Graphviz, railroad diagrams, ASCII art |
| ML | 30 | LLMs, RAG, evaluation, DSPy, prompt engineering |
| Math | 19 | Category theory, algebra, topology, differential equations |
| Debugging | 14 | Performance profiling, memory analysis, distributed tracing |
| Build Systems | 8 | Docker, CI/CD, dependency management |
| Caching | 7 | Redis, CDN, cache invalidation strategies |
| Observability | 8 | Logging, metrics, tracing, alerting |
| ... | ... | 20 more categories |
Full list: See skills/README.md after installation
Plugin Metadata
plugin.json
{
"name": "hanzo-skills",
"version": "2.0.0",
"description": "292 atomic skills with skill-based progressive loading",
"author": "rand",
"homepage": "https://github.com/hanzoai/skills",
"repository": "https://github.com/hanzoai/skills",
"license": "MIT",
"keywords": [
"skills", "skill", "progressive-loading",
"diagrams", "mermaid", "ml", "api", "database",
"testing", "infrastructure", "mathematics", "debugging"
]
}
Version History
-
v2.0.0 - Plugin architecture (2025-10-27)
- Converted to Claude Code plugin
- Added plugin manifest
- Removed manual installation scripts
- Renamed
slash-commands/→commands/ - Added LICENSE for marketplace compatibility
-
v1.0.0 - Manual installation
- 292 skills across 31 categories
- Skill-based progressive loading
- Manual sync with install.sh
Plugin Lifecycle
Installation
/plugin install https://github.com/hanzoai/skills
Process:
- Claude Code clones repository to
~/.claude/plugins/hanzo-skills/ - Reads
.claude-plugin/plugin.jsonfor metadata - Registers commands from
commands/directory - Makes skills available at
~/.claude/plugins/hanzo-skills/skills/
Updates
/plugin update hanzo-skills
Process:
- Pulls latest version from repository
- Updates plugin metadata
- Refreshes commands and skills
- Preserves user customizations (if any)
Uninstallation
/plugin uninstall hanzo-skills
Process:
- Unregisters all commands
- Removes
~/.claude/plugins/hanzo-skills/directory - Cleans up plugin metadata
- No traces left in Claude Code configuration
Development
Adding New Skills
-
Choose category or create new one:
mkdir skills/new-category -
Create skill file (use kebab-case):
cat > skills/new-category/my-skill.md << 'EOF' --- name: new-category-my-skill category: new-category description: Brief description of what this skill does keywords: [keyword1, keyword2, keyword3] --- # Skill content here EOF -
Update category INDEX.md:
## Skills - **my-skill.md** - Brief description -
Write its SKILL.md (
skills/<name>/SKILL.md) -
Update master catalog (
skills/README.md):### New Category (1 skill) Keywords: keyword1, keyword2 -
Test the skill:
/skills new-category cat skills/new-category/my-skill.md
Adding New Commands
-
Create command file in
commands/:cat > commands/my-command.md << 'EOF' --- name: my-command description: What this command does --- # Command implementation EOF -
Test the command:
/my-command -
Document in README.md
Contribution Guidelines
- Fork the repository
- Create feature branch:
git checkout -b feature/new-skill - Follow naming conventions:
- Skills:
category-skill-name.md(kebab-case) - Categories: lowercase, no spaces
- Commands: lowercase, hyphen-separated
- Skills:
- Keep skills focused: 200-400 lines, single responsibility
- Add YAML frontmatter: name, category, description, keywords
- Update documentation: INDEX.md, README.md, skills
- Test locally: Install as plugin, verify discovery works
- Submit pull request with clear description
Testing Locally
# Install from local directory
cd /path/to/hanzo-skills
/plugin install file://$(pwd)
# Test commands
/skills
/skills your-category
# Test skill discovery
cat skills/your-category/your-skill.md
# Uninstall local version
/plugin uninstall hanzo-skills
Plugin Best Practices
For Plugin Users
- Use
/skillsfor discovery - Don't manually browse directories - Load skills on-demand - Let skills guide you
- Update regularly -
/plugin update hanzo-skillsfor latest skills - Provide feedback - Report issues or suggest improvements
For Plugin Developers
- Maintain skill architecture - Don't break progressive loading
- Keep skills atomic - One skill = one responsibility
- Optimize for context - Skills should be 200-400 lines
- Test before publishing - Verify plugin installs and commands work
- Semantic versioning - Use semver for releases (2.0.0, 2.1.0, etc.)
- Document changes - Update README.md and PLUGIN.md
Compatibility
Claude Code Version
- Required: Claude Code v2.0+ with plugin support
- Recommended: Latest version for best experience
Existing Installations
- Migrating from manual installation? See MIGRATION.md
- Can coexist with manual installation (not recommended)
- Plugin takes precedence for commands and discovery
Other Plugins
- Compatible with all Claude Code plugins
- No conflicts with built-in skills or commands
- Composable with other skill libraries
Troubleshooting
Plugin not installing
Check:
# Verify plugin system is available
/plugin help
# Check Claude Code version
# Plugins require v2.0+
Commands not working after install
Solution:
# Restart Claude Code session
# Then verify
/plugin list # Should show hanzo-skills
/skills # Should work
Skills not discovered
Check:
# Verify plugin directory exists
ls ~/.claude/plugins/hanzo-skills/skills/
# Reinstall if missing
/plugin uninstall hanzo-skills
/plugin install https://github.com/hanzoai/skills
Want to modify skills
Location:
cd ~/.claude/plugins/hanzo-skills/skills/
# Edit skills here
# Changes will persist until plugin update
Note: Plugin updates will overwrite changes. Fork the repository for permanent modifications.
Technical Details
File Structure
~/.claude/plugins/hanzo-skills/
├── .claude-plugin/
│ └── plugin.json # Metadata read by Claude Code
├── skills/ # Discovered by skill system
│ ├── README.md # Master catalog (28 skills)
│ ├── <name>/SKILL.md # one skill, one directory
│ └── */INDEX.md # Category indexes
├── commands/ # Auto-registered by plugin system
│ └── skills.md # /skills command
└── [docs, license, etc.]
Discovery Algorithm
Project Detection:
- Scan working directory for indicator files
package.json→ Frontend/Node.jsgo.mod→ GoCargo.toml→ Rustpyproject.toml→ Python- etc.
- Analyze conversation context
- Match to skill keywords
- Recommend relevant skills
Skill Matching:
- Skill activates based on keywords
- Category index provides overview
- User loads specific skill when needed
Performance
- Installation: ~2-3 seconds (clone + register)
- Command execution: <100ms (read-only operations)
- Skill discovery: <50ms (file scanning + matching)
- Context usage: 200-1,000 lines per session (vs 87,600 if all loaded)
Future Enhancements
Planned Features
- Marketplace distribution - Publish to official Claude Code marketplace
- Skill analytics - Track most-used skills, improve recommendations
- Custom skills - User-defined skills
- Skill collections - Curated bundles for specific workflows
- Interactive skill wizard - Guide users to right skills
Community Requests
See GitHub Issues for feature requests and discussions.
Support
Documentation
- README.md - Main documentation and quick start
- PLUGIN.md - This file (plugin details)
- MIGRATION.md - Migration from manual installation
- commands/skills/README.md - /skills command documentation
- skills/README.md - Master skills catalog
Getting Help
- Check documentation - README.md, PLUGIN.md, MIGRATION.md
- Browse issues - https://github.com/hanzoai/skills/issues
- Open new issue - Provide details about problem
- Discussions - https://github.com/hanzoai/skills/discussions
Contributing
Contributions welcome! See Development section above.
- Fork repository
- Create feature branch
- Make changes
- Test locally
- Submit pull request
License
MIT License - See LICENSE file for details.
Credits
Author: rand Repository: https://github.com/hanzoai/skills Plugin System: Claude Code by Anthropic
Plugin Status: ✅ Active Development Latest Version: 2.0.0 Last Updated: 2025-10-27