Skillful

A comprehensive command-line interface for managing Claude Code Skills, working exactly like Claude Code's built-in skill system.

Features

• 🚀 Fast and lightweight - Built with Bun for optimal performance
• 📦 Multiple skill sources - Personal, project, and plugin skills
• 🔍 Advanced search - Find skills by name or description
• ✅ Validation - Ensure skills follow Claude Code standards
• 🛠️ Skill creation - Generate new skills with templates
• 🔌 MCP Server - Model Context Protocol support for integration
• 📝 TypeScript support - Full type safety and IntelliSense

Installation

Global Installation (Recommended)

npm install -g skillful
# or
bun add -g skillful

Local Installation

npm install skillful
# or
bun add skillful

Development Installation

git clone https://github.com/your-org/skillful.git
cd skillful
bun install
bun link

Quick Start

# List all available skills
skillful list

# Search for skills
skillful search "git"

# Create a new skill
skillful create my-skill "My custom skill description"

# Validate all skills
skillful validate

# Initialize skills in current project
skillful init

Usage

List Skills

# List all skills
skillful list

# List skills in JSON format
skillful list --json

# Filter by source
skillful list --source personal
skillful list --source project
skillful list --source plugin

Show Skill Details

skillful show <skill-name>

Search Skills

# Search by name or description
skillful search <query>

# Example
skillful search "commit"

Create Skills

# Create a basic skill
skillful create my-skill "Description of what it does"

# Create with specific template
skillful create my-skill "Description" --template workflow

# Create personal skill (global)
skillful create my-skill "Description" --personal

# Force overwrite existing skill
skillful create my-skill "Description" --force

Available templates:

• simple - Basic skill template (default)
• workflow - Multi-step workflow template
• reference - Reference documentation template

Validate Skills

# Validate all skills
skillful validate

# Validate specific skill
skillful validate <skill-name>

Test Skills

# Test all skills
skillful test

# Test specific skill
skillful test <skill-name>

Initialize Project

# Create .claude/skills directory
skillful init

MCP Server

# Start HTTP MCP server
skillful mcp

# Start with custom port
skillful mcp --port 3000

# Start stdio MCP server
skillful mcp --stdio

Marketplace Skill Backup

# List all marketplace skills
skillful marketplace list

# List skills from a specific marketplace
skillful marketplace list personal-plugins

# Download a single skill from a plugin
skillful marketplace download "elements-of-style@superpowers-marketplace" "writing-clearly-and-concisely"

# Download all skills from a specific plugin
skillful marketplace download "frontend@personal-plugins"

# Download all enabled marketplace skills
skillful marketplace download-all

# Download all skills from all plugins (including disabled)
skillful marketplace download-all --all

# Specify custom backup directory
skillful marketplace download "frontend@personal-plugins" --dir ~/my-backup-dir

# Overwrite existing files
skillful marketplace download-all --force

# Output in JSON format
skillful marketplace list --json

Configuration: You can set a default backup directory in your .claude/skills-config.json:

{
  "backupDir": "~/skillful-backup"
}

If no backupDir is configured, skills are backed up to ~/skillful-backup by default.

Skill Format

Skills follow the Claude Code standard format:

---
name: your-skill-name
description: Brief description of what this skill does
allowed-tools: Read, Grep, Glob  # Optional
---

# Your Skill Name

## Instructions
Provide clear, step-by-step guidance for Claude.

## Examples
Show concrete examples of using this skill.

Validation Rules

• Name: max 64 characters, lowercase/numbers/hyphens only
• Description: max 1024 characters, non-empty, no XML tags
• Allowed Tools: comma-separated list of valid tool names

Skill Locations

Skills are discovered from these locations:

1. Personal skills: ~/.claude/skills/
2. Project skills: ./.claude/skills/ (relative to current directory)
3. Plugin skills: ~/.claude/plugins/*/skills/

Development

Setup

git clone https://github.com/your-org/skillful.git
cd skillful
bun install

Build

# Build the project
bun run build

# Build and watch for changes
bun run build:watch

Testing

# Run all tests
bun test

# Run tests with coverage
bun test --coverage

# Run tests in watch mode
bun test --watch

Linting

# Run linter
bun run lint

# Fix linting issues
bun run lint:fix

Type Checking

bun run typecheck

Formatting

# Format code
bun run format

# Check formatting
bun run format:check

API Reference

Programmatic Usage

import { discoverAllSkills, createSkill } from 'skillful';

// Discover all skills
const skills = await discoverAllSkills();

// Create a new skill
await createSkill({
  name: 'my-skill',
  description: 'My custom skill',
  template: 'simple',
  location: 'project'
});

Configuration

Environment Variables

• SKILLFUL_PATH - Custom path for skills directory
• SKILLFUL_PLUGINS_PATH - Custom path for plugins directory

Configuration File

Create .skillful.json in your project root:

{
  "skillsPath": "./custom-skills",
  "templatesPath": "./custom-templates",
  "defaultTemplate": "simple"
}

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please read CONTRIBUTING.md for details on our code of conduct and development process.

Roadmap

• [ ] Web UI for skill management
• [ ] Skill marketplace integration
• [ ] Advanced skill analytics
• [ ] Skill sharing and collaboration
• [ ] IDE extensions

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a list of changes.

Acknowledgments

• Claude Code team for the inspiration
• Bun team for the amazing runtime
• All contributors and users of this tool