Files
zeekayandHanzo Dev 1f30086c79 Undo a find-and-replace that ate the paths
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]>
2026-09-10 21:54:42 -07:00

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:

  1. Clone the repository to ~/.claude/plugins/hanzo-skills/
  2. Register all commands (e.g., /skills)
  3. Make all 292 skills available for discovery
  4. 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:

  1. Claude Code clones repository to ~/.claude/plugins/hanzo-skills/
  2. Reads .claude-plugin/plugin.json for metadata
  3. Registers commands from commands/ directory
  4. Makes skills available at ~/.claude/plugins/hanzo-skills/skills/

Updates

/plugin update hanzo-skills

Process:

  1. Pulls latest version from repository
  2. Updates plugin metadata
  3. Refreshes commands and skills
  4. Preserves user customizations (if any)

Uninstallation

/plugin uninstall hanzo-skills

Process:

  1. Unregisters all commands
  2. Removes ~/.claude/plugins/hanzo-skills/ directory
  3. Cleans up plugin metadata
  4. No traces left in Claude Code configuration

Development

Adding New Skills

  1. Choose category or create new one:

    mkdir skills/new-category
    
  2. 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
    
  3. Update category INDEX.md:

    ## Skills
    - **my-skill.md** - Brief description
    
  4. Write its SKILL.md (skills/<name>/SKILL.md)

  5. Update master catalog (skills/README.md):

    ### New Category (1 skill)
    Keywords: keyword1, keyword2
    
  6. Test the skill:

    /skills new-category
    cat skills/new-category/my-skill.md
    

Adding New Commands

  1. Create command file in commands/:

    cat > commands/my-command.md << 'EOF'
    ---
    name: my-command
    description: What this command does
    ---
    
    # Command implementation
    EOF
    
  2. Test the command:

    /my-command
    
  3. Document in README.md

Contribution Guidelines

  1. Fork the repository
  2. Create feature branch: git checkout -b feature/new-skill
  3. Follow naming conventions:
    • Skills: category-skill-name.md (kebab-case)
    • Categories: lowercase, no spaces
    • Commands: lowercase, hyphen-separated
  4. Keep skills focused: 200-400 lines, single responsibility
  5. Add YAML frontmatter: name, category, description, keywords
  6. Update documentation: INDEX.md, README.md, skills
  7. Test locally: Install as plugin, verify discovery works
  8. 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

  1. Use /skills for discovery - Don't manually browse directories
  2. Load skills on-demand - Let skills guide you
  3. Update regularly - /plugin update hanzo-skills for latest skills
  4. Provide feedback - Report issues or suggest improvements

For Plugin Developers

  1. Maintain skill architecture - Don't break progressive loading
  2. Keep skills atomic - One skill = one responsibility
  3. Optimize for context - Skills should be 200-400 lines
  4. Test before publishing - Verify plugin installs and commands work
  5. Semantic versioning - Use semver for releases (2.0.0, 2.1.0, etc.)
  6. 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:

  1. Scan working directory for indicator files
    • package.json → Frontend/Node.js
    • go.mod → Go
    • Cargo.toml → Rust
    • pyproject.toml → Python
    • etc.
  2. Analyze conversation context
  3. Match to skill keywords
  4. Recommend relevant skills

Skill Matching:

  1. Skill activates based on keywords
  2. Category index provides overview
  3. 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

  1. Check documentation - README.md, PLUGIN.md, MIGRATION.md
  2. Browse issues - https://github.com/hanzoai/skills/issues
  3. Open new issue - Provide details about problem
  4. Discussions - https://github.com/hanzoai/skills/discussions

Contributing

Contributions welcome! See Development section above.

  1. Fork repository
  2. Create feature branch
  3. Make changes
  4. Test locally
  5. 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