Smart Skills

Agent skill management tool - manage and sync AI agent instructions for opencode, nvim, Cursor, and Claude Code.

Features

• Config-Based Skills: Configure skill sources in JSON config
• Per-Project Skills: Add custom skills in configured directories
• Global Skills: Support for ~/.config/smart-skills/skills/
• Skill Validation: Validate skill structure and content
• Multi-Platform: Installs skills for opencode, nvim, Cursor, and Claude Code

Installation

Via Cargo (recommended)

cargo install smart-skills

Via Homebrew

brew tap armedev/tap
brew install smart-skills

Via Install Script

curl -sL https://raw.githubusercontent.com/armedev/smart-skills/main/install.sh | bash

From Source

cargo build --release
cargo install --path .

Usage

Initialize a project

smart-skills init                                    # Use global skills (~/.config/smart-skills/skills/)
smart-skills init --skills-source ./my-skills       # Use custom skill source
smart-skills init --skills-source skills            # Use local skills/ directory

This creates:

• .smart-skills/config.json - Project config with skill sources
• .agents/skills/ - Skills for opencode/nvim
• .cursor/rules/ - Skills for Cursor
• .claude/rules/ - Skills for Claude Code

Global Skills

By default, init uses skills from:

• ~/.config/smart-skills/skills/ (all platforms)

Add skills

smart-skills add planning
smart-skills add planning execution  # Add multiple
smart-skills add                     # Show available skills

Remove skills

smart-skills remove planning
smart-skills remove                 # Show installed skills

List skills

smart-skills list

Sync skills

smart-skills sync

Check status (with validation)

smart-skills status

Config management

smart-skills config              # Show current config
smart-skills set-sources ./my-skills /global/skills  # Set skill sources

Clear all skills

smart-skills clear

Configuration

Project Config (.smart-skills/config.json)

{
  "skill_sources": [
    {
      "path": "skills",
      "priority": 10
    }
  ],
  "install_targets": {
    "agents": true,
    "cursor": true,
    "claude": true
  }
}

Skill Sources

• path: Path to skill directory (relative or absolute)
• priority: Higher priority sources are checked first (10 = highest)

Global Config

You can also set up global skills at ~/.config/smart-skills/config.json

Skill Structure

Skills should be in directories with SKILL.md files:

skills/
├── planning/
│   └── SKILL.md
├── code-review/
│   └── SKILL.md
└── ...

Validating Skills

Run smart-skills status to validate:

• Empty skill files
• Missing content
• Proper formatting (## headers or bullet points)

Priority Order

Skills are loaded in this order:

1. Project config skill sources (by priority)
2. Global skills (~/.config/smart-skills/skills/)

Adding Custom Skills

1. Create a skill directory:

   mkdir -p skills/my-custom-skill
   

2. Add a SKILL.md file:

   ## My Custom Skill
   
   * Follow these guidelines
   * For your team
   

3. Initialize or sync:

   smart-skills init
   # or
   smart-skills sync
   

Structure

smart-skills/
├── Cargo.toml
├── src/
│   ├── main.rs
│   ├── cli/
│   │   ├── commands.rs
│   │   ├── picker.rs
│   │   └── mod.rs
│   ├── skills/
│   │   ├── mod.rs
│   │   ├── loader.rs
│   │   └── installer.rs
│   └── config/
│       └── mod.rs
└── README.md