agent-skill-manager

Agent Skill Manager

ALL codes are written by Claude Code.

A comprehensive CLI tool for managing AI agent skills across multiple platforms. Download, deploy, update, and manage skills for AI coding assistants like Claude Code, Cursor, Windsurf, and more.

Features

• 📥 Download skills from GitHub with metadata tracking
• 🔍 Discover all skills in a repository automatically
• 🚀 Deploy skills to multiple AI agents (global or project-level)
• 🔗 Symlink support - save disk space with symbolic links
• 🔄 Update skills automatically from GitHub sources
• 🗑️ Uninstall with safe deletion (move to trash) or hard delete
• ♻️ Restore deleted skills from trash
• 📋 List all installed skills with version information
• ⚡ CLI-first - full command-line parameter support for automation
• 🏎️ Fast downloads - 3-tier strategy: git sparse-checkout → Tree API + raw URLs → Contents API fallback

Supported AI Agents

[!NOTE] Kiro CLI users: After installing skills, manually add them to your custom agent's resources in .kiro/agents/<agent>.json:

{
  "resources": ["skill://.kiro/skills/**/SKILL.md"]
}

Installation

Recommended: Install with uv tool

The best way to install is using uv tool:

# Install from PyPI
uv tool install agent-skill-manager

# Verify installation
sm --version

# Start using
sm install

Why uv tool?

• Isolated environment (no package conflicts)
• Easy updates: uv tool upgrade agent-skill-manager
• Clean uninstall: uv tool uninstall agent-skill-manager
• Works across all projects

Alternative: Run Without Installing

For one-time use or testing:

# Run directly with uvx (no installation needed)
uvx agent-skill-manager

# Or run specific commands
uvx --from agent-skill-manager sm install
uvx --from agent-skill-manager sm list

Other Installation Methods

# Using pip
pip install agent-skill-manager

# Using pipx (isolated like uv tool)
pipx install agent-skill-manager

# From source (for development)
git clone https://github.com/ackness/skill-manager.git
cd skill-manager
uv sync
uv pip install -e .

Usage Methods Comparison

Quick Start

# Run without installing (using uvx)
uvx --from agent-skill-manager sm install
uvx --from agent-skill-manager sm list

# Or after installation, use sm command directly:
sm install          # Install a skill from GitHub (interactive)
sm list             # List installed skills
sm update --all     # Update all skills
sm deploy           # Deploy local skills to agents
sm uninstall        # Uninstall a skill (safe delete)
sm agents           # List all supported agents

Commands

CLI Options

Network Configuration

The tool supports proxy, GitHub token, and GitHub mirror via environment variables:

# Example: use proxy for faster downloads
export HTTPS_PROXY=http://127.0.0.1:7890
sm install https://github.com/cloudflare/skills -a windsurf

# Example: use GitHub token to avoid rate limits
export GITHUB_TOKEN=ghp_your_token_here
sm install https://github.com/cloudflare/skills -a windsurf

# Example: use GitHub mirror (for users in China)
export GITHUB_MIRROR=https://mirror.ghproxy.com
sm install https://github.com/cloudflare/skills -a windsurf

# PowerShell (Windows)
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:GITHUB_TOKEN="ghp_your_token_here"
sm install https://github.com/cloudflare/skills -a windsurf

[!TIP] Get a GitHub token at https://github.com/settings/tokens (only public_repo scope needed). Network status is shown during GitHub operations.

Usage Examples

Install skills from a GitHub repository

# Install all skills from a repo (auto-discovery and symlinks enabled by default)
sm install https://github.com/cloudflare/skills -a windsurf -a cursor

# Install specific skills only
sm install https://github.com/cloudflare/skills -s mcp -s browser-rendering -a windsurf

# Full CLI mode - no prompts
sm install https://github.com/user/repo/tree/main/skills/my-skill -a claude-code -t global

# Disable auto-discovery to install only the specific path
sm install https://github.com/user/repo/tree/main/skills/my-skill --no-discover -a cursor

# Disable symlinks, copy files instead
sm install https://github.com/cloudflare/skills --no-symlink -a windsurf

# Download to custom location
sm install https://github.com/user/repo/tree/main/skills/my-skill -d ./my-skills -a cursor

Install skills from a local directory

# Install from a previously downloaded skills directory
sm install ~/.skill-manager/skills -a windsurf -a cursor

# Install specific skills from local directory
sm install ~/my-skills -s my-skill-name -a claude-code

# Install from any local directory containing SKILL.md files
sm install ./path/to/skills -a windsurf

Discover skills in a repository

# Scan a repository to find all skills
sm discover https://github.com/cloudflare/skills
# Shows a table of all found skills with their paths

Interactive mode

sm install
# Enter URL when prompted, all skills are pre-selected by default
# Follow the prompts to select agents and deploy

Update all skills

sm update --all
# Automatically updates all skills installed from GitHub

List installed skills with versions

sm list
# Shows a table for each agent with:
# - Skill Name
# - Version/Updated timestamp
# - Source (GitHub/Local)
# - GitHub URL (for updatable skills)

Safe delete and restore

# Uninstall with safe delete (default)
sm uninstall

# Restore if needed
sm restore

Using symlinks

Symlinks allow you to maintain a single copy of skills while deploying to multiple agents:

# Download skills to a central location and symlink to agents (default behavior)
sm install https://github.com/cloudflare/skills -d ~/skills -a windsurf -a cursor -a claude-code

# Disable symlinks if needed
sm install https://github.com/cloudflare/skills --no-symlink -a windsurf

[!NOTE] On Windows, symlinks require Developer Mode or administrator privileges. If symlinks are not supported, the tool will automatically fall back to copying.

Version Tracking

The tool uses two methods for version identification:

1. GitHub Metadata (for installed skills)

   • Tracks installation and update timestamps
   • Stores repository information
   • Enables automatic updates

2. File Modification Time (for local skills)

   • Uses SKILL.md modification time as fallback
   • For skills without metadata

Directory Structure

Default Skills Cache

Downloaded skills are stored in ~/.skill-manager/skills/ by default (cross-platform).

Global Installation

Skills are available to all projects:

~/.claude/skills/           # Claude Code
~/.cursor/skills/           # Cursor
~/.codeium/windsurf/skills/ # Windsurf
# ... other agents

Project Installation

Skills are only available in the current project:

project-root/
  .claude/skills/
  .cursor/skills/
  # ... other agents

Configuration

Each skill installed from GitHub includes metadata in .skill_metadata.json:

{
  "source": "github",
  "github_url": "https://github.com/...",
  "owner": "user",
  "repo": "repo-name",
  "branch": "main",
  "path": "skills/skill-name",
  "installed_at": "2026-01-20T14:30:52+00:00",
  "updated_at": "2026-01-20T14:30:52+00:00"
}

Development

Adding Support for New Agents

Edit src/skill_manager/agents.py and add the agent configuration:

"agent-id": {
    "name": "Agent Name",
    "project": ".agent/skills/",
    "global": "~/.agent/skills/",
}

Running Tests

uv run pytest

Code Formatting

uv run ruff format .
uv run ruff check . --fix

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

Related Projects

• Agent Skills Specification
• Agent Skills Registry

License

MIT License - See LICENSE file for details

Author

ackness - ackness8@gmail.com

Acknowledgments

• Built following the Agent Skills specification
• Supports all major AI coding assistants