Skill Search

A lightweight Node.js CLI tool for quick retrieval of skill documentation from GitHub repositories 🚀

Skill Search is a command-line interface tool designed to help developers and users quickly access skill documentation (Markdown format) stored on GitHub, enhancing learning and reference efficiency.

✨ Features

• 🖥️ Interactive TUI: Modern text-based user interface with keyboard navigation
• 🔍 Fast Access: Retrieve skill documentation with a single command, no browser required
• 💾 Smart Caching: Local caching to reduce network requests and support offline access
• 🎯 Intelligent Matching: Supports exact matching, keyword matching, and fuzzy search
• 🎨 Beautiful Output: Terminal-friendly Markdown formatting and display
• 📋 Convenient Operations: Support for copying to clipboard or saving to files
• 🔧 Flexible Configuration: Support for multiple skill directory sources and API configurations

📦 Installation & Development

Multi-Device Development Environment Setup (Recommended)

If you sync code across multiple devices using OneDrive/Dropbox, use the following installation method to avoid node_modules conflicts between devices:

1. Run Setup Script (Windows): Double-click to run scripts/setup-env.bat

   Or execute in terminal:

   .\scripts\setup-env.bat

   This will create independent dependency directories based on device names in .local/DEVICE_NAME/node_modules and link them to the root directory.

2. Link Command:

   npm link

Standard Installation

# Global installation
npm install -g skill-search

# Local development
npm install
npm link

🛠️ Usage Guide

0. TUI Interactive Mode (Recommended)

Launch the interactive TUI interface by running skill without arguments:

skill          # Launch TUI (default when no arguments provided)
skill --tui    # Explicitly specify TUI mode

Keyboard Shortcuts:

• ↑↓ Navigate up/down | Tab Switch panes | Enter Select
• / Search | l List | y Sync | c Config | q Quit

1. Get Skill Documentation

Retrieve documentation by skill ID or keyword:

skill <keyword> [options]

Examples:

# Get React-related documentation
skill react

# Copy Git workflow documentation to clipboard
skill git-workflow --copy

# Save Docker documentation to local file
skill docker -o ./docker-guide.md

# Force refresh from remote (ignore cache)
skill typescript --no-cache

Options:

• -c, --copy: Copy content to clipboard
• -r, --raw: Output raw Markdown content (no terminal formatting)
• -o, --output <file>: Save content to specified file
• --no-cache: Ignore local cache, force remote fetch

2. Search Skills

Search for skills locally:

skill search <query>
# Alias
skill s <query>

Examples:

skill search frontend
skill s hooks

3. List All Skills

Display all locally available skills:

skill list
# Alias
skill ls

4. Cache Management

Manage local cache (stored by default in ~/.skill-search/):

# List cached documentation
skill cache list

# Clear all cache
skill cache clear

5. Directory Management

Add Custom Skill Paths

Add custom skill directory paths beyond the default locations:

skill add <path>

Example:

skill add /path/to/my/custom/skills

Remove Custom Skill Paths

Remove a custom skill directory path:

skill remove <path>
# Alias
skill rm <path>

Set Primary Directory

Configure the primary skill directory:

skill primary [directory]

Available directories:

• .skill-search - Default Skill Search directory
• .claude - Claude AI directory
• .codex - OpenAI Codex directory
• .gemini - Google Gemini directory
• .copilot - GitHub Copilot directory

Example:

skill primary claude

6. Theme Management

Switch between dark and light themes in TUI mode:

skill theme [mode]

Examples:

skill theme dark
skill theme light
skill theme  # Toggle between themes

⚙️ Configuration

Default API configuration is located in src/config.js. You can modify this file to point to your own GitHub repository:

module.exports = {
    api: {
        baseUrl: 'https://skillsmp.com/api/v1',
        // API Key should be configured by user
    },
    github: {
        owner: 'your-username',     // Your GitHub username
        repo: 'your-skills-repo',   // Your repository name
        branch: 'main',             // Branch name
        // ...
    }
};

API Configuration

Set up API access for remote skill search:

skill config --api-key <your-api-key>

📂 Project Structure

skill-search/
├── bin/
│   ├── skill.js            # CLI entry point
│   └── tui.js              # TUI entry point
├── scripts/
│   └── setup-env.bat       # Multi-device environment setup
├── src/
│   ├── config.js           # Configuration management
│   ├── api.js              # SkillsMP API client
│   ├── store.js            # Local data storage
│   ├── syncer.js           # Sync operations
│   ├── cache.js            # Cache management
│   ├── matcher.js          # Skill matching and search (Fuse.js)
│   ├── localCrawler.js     # Local skill directory scanning
│   ├── interactive.js      # Interactive skill selection
│   ├── actions.js          # Action handlers (sync, move, delete)
│   ├── utils.js            # Utility functions (Markdown rendering, clipboard)
│   ├── theme.js            # Theme management
│   └── tui/                # TUI components
│       ├── App.js          # Main TUI application
│       ├── SearchView.js   # Search interface
│       ├── SyncView.js     # Sync management
│       ├── ConfigView.js   # Configuration interface
│       ├── ThemeView.js    # Theme selection
│       ├── PrimaryView.js  # Primary directory selection
│       ├── AddDelView.js   # Custom path management
│       ├── ActionModal.js  # Action confirmation modal
│       └── ...             # Other UI components
├── package.json
└── README.md

🔄 Sync Operations

Local Sync

Sync locally discovered skills to the primary directory:

skill sync --docs

Remote Sync

Download all remote skills to the primary directory:

skill sync --full

Sync Specific Skill

Sync only a specific skill:

skill sync --id <skill-id>

Full Sync

Sync both local and remote skills:

skill sync --force

Sync Status

Check sync status and history:

skill sync --status

🎨 TUI Interface

The Text User Interface provides a modern, keyboard-driven experience:

• Dual-Pane Layout: Local and remote skill results side by side
• Keyboard Navigation: Arrow keys, Tab, and shortcuts for efficient browsing
• Real-time Search: Instant local search as you type
• Action Modals: Context menus for sync, move, delete, and open operations
• Theme Support: Dark and light themes with customizable colors

TUI Navigation

• Search: Type to search locally, press Enter for remote search
• Navigation: Tab between local/remote panes, arrows to select items
• Actions: Enter to open action modal, Shift+O to open directly
• Pagination: [ and ] for previous/next page
• Commands: / to access command palette

📋 Dependencies

Runtime Dependencies:

• axios: HTTP client for API requests
• chalk: Terminal text styling
• clipboardy: Clipboard operations
• commander: CLI argument parsing
• fuse.js: Fuzzy search implementation
• ink: React-based terminal UI framework
• inquirer: Interactive CLI prompts
• marked: Markdown parser
• marked-terminal: Terminal Markdown rendering
• ora: Terminal spinners
• react: UI framework for TUI

Development Dependencies:

• eslint: Code linting
• jest: Testing framework
• pkg: Binary packaging
• prettier: Code formatting

🔧 Development

Building

Create executable binaries for multiple platforms:

npm run build

This generates binaries in the dist/ directory for Linux, macOS, and Windows.

Testing

npm test

Code Quality

# Lint code
npx eslint src/

# Format code
npx prettier --write src/

🤝 Contributing

1. Fork the repository
2. Create a 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

📝 License

ISC

🙏 Acknowledgments

• Built with Ink for terminal UI
• Powered by Fuse.js for fuzzy search
• Markdown rendering with Marked

---

Happy Skill Hunting! 🎯