Documentation

Everything you need to know about SkillOps - from installation to advanced usage

Overview

Introduction to SkillOps and core concepts

Installation

Get SkillOps up and running on your system

Commands Reference

Complete guide to all SkillOps commands

Configuration

Configure SkillOps for your workflow

Workflows

Real-world workflow examples and use cases

Troubleshooting

Common issues and solutions

SkillOps: Complete User Guide

SkillOps is a powerful, high-performance CLI tool developed in Go that helps you manage "skills" (AI-supporting capabilities/scripts) for various Agentic IDEs (like Claude Desktop, Antigravity, OpenCode, Vercel, etc.) through a symlink-first mechanism.

Instead of manually copying skills into each IDE's directory, SkillOps stores them centrally and creates intelligent symlinks, making synchronization effortless.

Core Concepts

Global Skills Directory

The central directory (~/.skillops/skills) where all downloaded skill repositories are stored.

Agentic IDE

Code editors or agent environments (Claude, Antigravity, etc.) that support AI-powered skills.

Symlinking

SkillOps creates links from the global directory to your project directories (e.g., .agents/skills), avoiding file duplication and ensuring consistency across projects.

Key Features

  • Centralized Management: Store all skills in one location
  • Symlink-Based: No file duplication across projects
  • Multi-IDE Support: Manage skills for multiple IDEs simultaneously
  • Interactive TUI: Beautiful terminal interfaces for all operations
  • Git Integration: Pull skills directly from GitHub repositories
  • Selective Downloads: Download entire repos or specific skills
  • Safe Operations: Confirmation prompts and safety checks

Architecture

~/.skillops/
├── skills/              # Global skills storage
│   ├── repo-1/
│   │   └── SKILL.md    # Skill identifier
│   └── repo-2/
│       └── SKILL.md
└── config/
    └── agentics.yaml   # IDE configurations

Your Project/
├── .agents/            # Claude Desktop
│   └── skills/         # Symlinks to global skills
├── .agent/             # Antigravity
│   └── skills/
└── .skillops/          # Other IDEs
    └── skills/

Workflow Overview

  1. Install SkillOps on your system
  2. Pull skills from GitHub repositories
  3. Configure which IDEs you want to use in your project
  4. Manage which skills are active for each IDE
  5. Update skills to get the latest versions

Supported IDEs

SkillOps comes pre-configured with support for popular Agentic IDEs:

  • Claude Desktop
  • Antigravity
  • OpenCode
  • Windsurf
  • Cursor
  • And more...

You can also add custom IDE configurations to support any tool that uses a skills directory.

Next Steps

Installation Guide

Quick Installation

Homebrew (macOS & Linux)

brew tap leodinhsa/skillops
brew install skillops

Manual Installation (from source)

# Build from source
go build -o skillops main.go

# Move to PATH
sudo mv skillops /usr/local/bin/

# Verify installation
skillops --help

Verification

After installation, verify that SkillOps is working correctly:

# View help and available commands
skillops --help

# Check if skillops is in your PATH
which skillops

Configuration

SkillOps stores its configuration in ~/.skillops/config/agentics.yaml. The configuration file is created automatically on first run.

Configuration File Location

  • All Config: ~/.skillops/config/agentics.yaml

Skill Identification

Skill folders are identified by the presence of a SKILL.md file in the repository root.

Troubleshooting

Permission Denied

If you encounter permission issues:

# Make sure the binary is executable
chmod +x /usr/local/bin/skillops

# Check if /usr/local/bin is in your PATH
echo $PATH

Command Not Found

If skillops command is not found:

# Add to your shell profile (.bashrc, .zshrc, etc.)
export PATH="/usr/local/bin:$PATH"

# Reload your shell
source ~/.bashrc  # or ~/.zshrc

Next Steps

Once installed, you can:

  1. Pull your first skill
  2. Configure agentic IDEs
  3. Start managing skills

For more detailed usage instructions, see the Commands Reference.

Commands Reference

Overview

SkillOps provides a comprehensive set of commands for managing AI agent skills across multiple Agentic IDEs (Claude, Antigravity, OpenCode, etc.). All commands follow a consistent pattern and provide rich interactive terminal experiences.

Skill Management

Project Configuration

skillops agentic

Open a checklist TUI to enable/disable Agentic IDE environments in your project root.

skillops agentic

Features:

  • Interactive checklist interface for managing multiple IDEs
  • Real-time status updates
  • Bulk enable/disable operations
  • Confirmation prompts for safety

Example:

cd /path/to/your/project
skillops agentic
# Opens TUI to select which IDEs to enable in this project

skillops agentic manage <name>

Interactively manage skills or remove the environment for a specific agentic IDE.

# Manage Claude IDE skills
skillops agentic manage claude

# Manage Windsurf IDE skills
skillops agentic manage windsurf

Features:

  • Toggle individual skills on/off
  • View skill details and descriptions
  • Remove all skills for the IDE
  • Interactive TUI for skill selection

skillops agentic remove-skill <agent> <skill>

Remove a specific skill symlink from an agentic IDE.

# Remove 'logger' skill from Claude
skillops agentic remove-skill claude logger

# Remove 'debug-helper' from Windsurf
skillops agentic remove-skill windsurf debug-helper

skillops agentic remove-skills <agent>

Remove all skill symlinks for a specific agentic IDE.

# Remove all skills from Claude
skillops agentic remove-skills claude

# Remove all skills from Windsurf
skillops agentic remove-skills windsurf

Skill Management

skillops pull <url>

Download a new skill repository from GitHub.

# Pull entire repository
skillops pull https://github.com/user/my-agent-skills

# Pull a specific skill (saves space)
skillops pull https://github.com/user/my-agent-skills --skill logger

Supported URL formats:

  • https://github.com/user/repo
  • github.com/user/repo
  • git@github.com:user/repo.git (if SSH key is configured)

Options:

  • --skill <name>: Download only a specific skill instead of the entire repository

Examples:

# Pull entire repository
skillops pull https://github.com/leodinhsa/awesome-skills

# Pull only 'git-helper' skill
skillops pull https://github.com/leodinhsa/awesome-skills --skill git-helper

skillops list

Show all downloaded skill names and their status across IDEs.

skillops list

Features:

  • Interactive TUI (Terminal User Interface)
  • Browse repository and skill lists
  • Quick copy skill names to clipboard using Space key
  • View active status of each skill

Status indicators:

  • Active: Skill is symlinked to one or more IDEs
  • Inactive: Skill is downloaded but not linked to any IDE

skillops remove <name>

Safely delete a pulled skill repository after checking for active links.

# Remove a skill (with safety check)
skillops remove copilot-docs

Safety features:

  • Checks for active symlinks before deletion
  • Lists affected IDEs
  • Requires confirmation for safety

skillops remove-all

Clear all local skill repositories.

# Remove all skills (with confirmation)
skillops remove-all

Warning: This will remove all downloaded skills from ~/.skillops/skills/ directory.

skillops update

Synchronize your skills with the latest versions from remote repositories.

# Update all skills
skillops update

# Update a specific skill
skillops update --skill logger

Features:

  • Automatically checks for updates from GitHub
  • Batch or individual skill updates
  • Preserves existing symlink configurations

Agentic Configuration

skillops config add-agentic -n <name> -p <path>

Register a new IDE type globally.

# Add a new IDE configuration
skillops config add-agentic -n "cursor" -p "~/.cursor/skills"

# Add VSCode configuration
skillops config add-agentic -n "vscode" -p "~/.vscode/extensions/skills"

skillops config update-agentic -n <name>

Update an existing IDE mapping with interactive path selection.

# Update Claude configuration
skillops config update-agentic -n claude

This opens an interactive prompt to change the skills directory path.

skillops config remove-agentic -n <name>

Remove a registered IDE mapping.

# Remove an IDE configuration
skillops config remove-agentic -n cursor

Complete Workflow Example

Here's a complete workflow from installation to managing skills:

# 1. Pull a skill repository
skillops pull https://github.com/github/copilot-docs

# 2. Check what's available
skillops list

# 3. Navigate to your project
cd /path/to/your/project

# 4. Configure IDEs for current project
skillops agentic
# Select which IDEs to enable (Claude, Windsurf, etc.)

# 5. Manage skills for specific IDE
skillops agentic manage claude
# Toggle skills on/off in the TUI

# 6. Remove unused skill
skillops remove old-skill

Setting Up a New IDE

# 1. Add the new IDE to global config
skillops config add-agentic -n "neovim" -p "~/.config/nvim/skills"

# 2. Navigate to your project
cd /path/to/your/project

# 3. Enable it in current project
skillops agentic

# 4. Add skills to it
skillops agentic manage neovim

Tips and Best Practices

  1. Use skillops list frequently to check the status of your skills
  2. Always run skillops agentic when setting up a new project
  3. Skills are identified by SKILL.md file in the repository root
  4. Keep your global config clean by removing unused IDE configurations
  5. Symlinks are used to avoid file duplication across projects

Configuration File

All configuration is stored in:

~/.skillops/config/agentics.yaml

This file contains:

  • Registered IDE types and their paths
  • Global settings
  • Skill repository locations

Configuration Guide

Overview

SkillOps stores all configuration in a YAML file at ~/.skillops/config/agentics.yaml. This file is automatically created when you first run SkillOps.

Configuration File Structure

agentics:
  - name: "claude"
    path: ".agents/skills"
  - name: "antigravity"
    path: ".agent/skills"
  - name: "windsurf"
    path: ".skillops/skills"
  - name: "cursor"
    path: ".cursor/skills"

Managing IDE Configurations

Adding a New IDE

To add support for a new IDE:

skillops config add-agentic -n "my-ide" -p ".my-ide/skills"

Parameters:

  • -n, --name: Name of the IDE (will be used in commands)
  • -p, --path: Relative path from project root to skills directory

Examples:

# Add support for Neovim
skillops config add-agentic -n "neovim" -p "~/.config/nvim/skills"

# Add support for VSCode
skillops config add-agentic -n "vscode" -p "~/.vscode/extensions/skills"

Updating IDE Configuration

To change the path of an existing IDE:

skillops config update-agentic -n "claude"

This command opens an interactive prompt for you to enter the new path.

Removing IDE Configuration

To remove an IDE from configuration:

skillops config remove-agentic -n "cursor"

Note: This only removes the configuration, not any existing skills or symlinks.

Project Configuration

Directory Structure

When you run skillops agentic in a project, SkillOps creates directories based on IDE configurations:

your-project/
├── .agents/              # Claude Desktop
│   └── skills/
│       ├── skill-1 -> ~/.skillops/skills/repo/skill-1
│       └── skill-2 -> ~/.skillops/skills/repo/skill-2
├── .agent/               # Antigravity
│   └── skills/
│       └── skill-1 -> ~/.skillops/skills/repo/skill-1
└── .skillops/            # Windsurf
    └── skills/
        └── skill-3 -> ~/.skillops/skills/repo/skill-3

Skill Identification

SkillOps identifies a directory as a skill if it contains a SKILL.md file in the repository root.

Skill Repository Structure:

my-skills-repo/
├── SKILL.md              # Required identifier file
├── README.md
├── skill-1/
│   └── main.py
└── skill-2/
    └── script.js

Advanced Configuration

Environment Variables

SkillOps supports the following environment variables:

  • SKILLOPS_CONFIG_DIR: Override config directory location (default: ~/.skillops/config)
  • SKILLOPS_SKILLS_DIR: Override global skills directory location (default: ~/.skillops/skills)

Example:

export SKILLOPS_CONFIG_DIR="/custom/config/path"
export SKILLOPS_SKILLS_DIR="/custom/skills/path"

Custom Paths

You can use both absolute and relative paths in configuration:

# Relative path (from project root)
skillops config add-agentic -n "local-ide" -p ".local/skills"

# Absolute path
skillops config add-agentic -n "global-ide" -p "~/.global-ide/skills"

Best Practices

Organizing Skills

  1. Group by Function: Organize skills by purpose (debugging, testing, documentation, etc.)
  2. Clear Naming: Use descriptive names for skills and repositories
  3. Documentation: Always include a SKILL.md file with clear descriptions

Configuration Management

  1. Keep Config Clean: Remove unused IDEs from configuration
  2. Use Consistent Paths: Follow naming conventions for IDE paths
  3. Backup Configuration: Regularly backup your agentics.yaml file

Project Management

  1. Selective IDEs: Only enable IDEs you actually use in each project
  2. Selective Skills: Only link necessary skills for each project
  3. Regular Updates: Run skillops update to keep skills current

Example Configurations

Web Development Setup

# Add IDEs for web development
skillops config add-agentic -n "vscode" -p ".vscode/skills"
skillops config add-agentic -n "cursor" -p ".cursor/skills"

# Pull web-related skills
skillops pull https://github.com/user/web-dev-skills
skillops pull https://github.com/user/react-skills

Data Science Setup

# Add IDEs for data science
skillops config add-agentic -n "jupyter" -p ".jupyter/skills"
skillops config add-agentic -n "pycharm" -p ".pycharm/skills"

# Pull data science skills
skillops pull https://github.com/user/data-science-skills
skillops pull https://github.com/user/ml-skills

Viewing Current Configuration

To view your current configuration:

# View configuration file
cat ~/.skillops/config/agentics.yaml

# Or use your favorite editor
vim ~/.skillops/config/agentics.yaml

Migrating Configuration

If you need to migrate configuration to a new machine:

# On old machine
cp -r ~/.skillops /path/to/backup/

# On new machine
cp -r /path/to/backup/.skillops ~/

Note: Ensure paths in the configuration are still valid on the new machine.

Workflow Examples

Complete Workflows

Setting Up a New Project with Claude and Antigravity

This workflow demonstrates how to set up a new project with multiple IDEs.

Step 1: Initialize the Environment

cd my-new-project
skillops agentic
# Select 'claude' and 'antigravity' from the checklist

Step 2: Pull Required Skills

skillops pull https://github.com/leodinhsa/awesome-skills --skill git-helper

Step 3: Link Skills to IDEs

skillops agentic manage claude
# Select 'git-helper' from the TUI and press Enter

Result:

  • .agents/skills/ directory created for Claude
  • .agent/skills/ directory created for Antigravity
  • git-helper skill symlinked to Claude

Daily Development Workflow

Morning Setup:

# Update all skills to latest versions
skillops update

# Check what skills are available
skillops list

Starting a New Feature:

# Navigate to project
cd ~/projects/my-app

# Check which IDEs are configured
ls -la | grep "^\."

# Add a new skill for the feature
skillops pull https://github.com/user/testing-skills --skill unit-test-helper
skillops agentic manage claude

End of Day:

# Review active skills
skillops list

# Remove skills no longer needed
skillops agentic remove-skill claude old-skill

Team Collaboration Workflow

Team Lead Setup:

# Create a shared skills repository
# (on GitHub: create repo 'team-skills')

# Pull team skills
skillops pull https://github.com/company/team-skills

# Document the setup
echo "Team Skills Setup" > SKILLS_SETUP.md
echo "Run: skillops pull https://github.com/company/team-skills" >> SKILLS_SETUP.md

Team Member Setup:

# Follow team documentation
skillops pull https://github.com/company/team-skills

# Configure for your IDE
cd project
skillops agentic
skillops agentic manage claude

Use Case Specific Workflows

Web Development

Initial Setup:

# Pull web development skills
skillops pull https://github.com/user/web-dev-skills
skillops pull https://github.com/user/react-skills
skillops pull https://github.com/user/css-skills

# Configure IDEs
cd ~/projects/web-app
skillops agentic
# Select: vscode, cursor

Managing Skills:

# Enable React skills for current project
skillops agentic manage vscode
# Select: react-component-generator, react-hooks-helper

# Enable CSS skills
skillops agentic manage vscode
# Select: tailwind-helper, css-optimizer

Backend Development

Initial Setup:

# Pull backend skills
skillops pull https://github.com/user/api-skills
skillops pull https://github.com/user/database-skills
skillops pull https://github.com/user/testing-skills

# Configure project
cd ~/projects/api-server
skillops agentic
# Select: claude, windsurf

Managing Skills:

# Enable API development skills
skillops agentic manage claude
# Select: api-generator, swagger-helper, auth-helper

# Enable database skills
skillops agentic manage claude
# Select: sql-optimizer, migration-helper

Data Science

Initial Setup:

# Pull data science skills
skillops pull https://github.com/user/data-science-skills
skillops pull https://github.com/user/ml-skills
skillops pull https://github.com/user/visualization-skills

# Configure Jupyter environment
skillops config add-agentic -n "jupyter" -p ".jupyter/skills"

Project Setup:

cd ~/projects/ml-project
skillops agentic
# Select: jupyter, vscode

# Enable ML skills
skillops agentic manage jupyter
# Select: data-cleaner, model-trainer, visualization-helper

DevOps

Initial Setup:

# Pull DevOps skills
skillops pull https://github.com/user/docker-skills
skillops pull https://github.com/user/kubernetes-skills
skillops pull https://github.com/user/ci-cd-skills

# Configure project
cd ~/projects/infrastructure
skillops agentic

Managing Skills:

# Enable Docker skills
skillops agentic manage claude
# Select: dockerfile-generator, docker-compose-helper

# Enable Kubernetes skills
skillops agentic manage claude
# Select: k8s-manifest-generator, helm-helper

Advanced Workflows

Multi-Project Management

Scenario: Working on multiple projects with different skill requirements

# Project 1: Frontend
cd ~/projects/frontend-app
skillops agentic
skillops agentic manage vscode
# Select: react-skills, css-skills

# Project 2: Backend
cd ~/projects/backend-api
skillops agentic
skillops agentic manage claude
# Select: api-skills, database-skills

# Project 3: Mobile
cd ~/projects/mobile-app
skillops agentic
skillops agentic manage cursor
# Select: react-native-skills, mobile-testing-skills

Skill Development Workflow

Creating Your Own Skills:

# Create a new repository for your skills
mkdir my-custom-skills
cd my-custom-skills

# Create SKILL.md identifier
cat > SKILL.md << EOF
# My Custom Skills

Collection of custom skills for my workflow.
EOF

# Create skill directories
mkdir -p custom-helper
echo "#!/bin/bash" > custom-helper/script.sh

# Initialize git and push to GitHub
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/user/my-custom-skills
git push -u origin main

# Pull into SkillOps
skillops pull https://github.com/user/my-custom-skills

Skill Testing Workflow

Testing New Skills:

# Create a test project
mkdir ~/test-project
cd ~/test-project

# Pull skill to test
skillops pull https://github.com/user/new-skill

# Enable in test project
skillops agentic
skillops agentic manage claude
# Select the new skill

# Test the skill
# ... use your IDE to test ...

# If good, deploy to real projects
cd ~/projects/real-project
skillops agentic manage claude
# Select the tested skill

Cleanup Workflow

Regular Maintenance:

# Review all skills
skillops list

# Remove unused skills
skillops remove old-skill-1
skillops remove old-skill-2

# Update remaining skills
skillops update

# Check disk usage
du -sh ~/.skillops/skills/*

Project Cleanup:

# Remove all skills from a project
cd ~/projects/old-project
skillops agentic remove-skills claude
skillops agentic remove-skills windsurf

# Or remove specific skills
skillops agentic remove-skill claude unused-skill

Troubleshooting Workflows

Fixing Broken Symlinks

# Find broken symlinks
find .agents/skills -type l ! -exec test -e {} \; -print

# Remove all broken symlinks
find .agents/skills -type l ! -exec test -e {} \; -delete

# Re-link skills
skillops agentic manage claude

Recovering from Mistakes

# Accidentally removed a skill
skillops pull https://github.com/user/important-skill

# Re-link to all projects
cd ~/projects/project1
skillops agentic manage claude

cd ~/projects/project2
skillops agentic manage claude

Migrating to New Machine

# On old machine
tar -czf skillops-backup.tar.gz ~/.skillops

# Transfer to new machine
scp skillops-backup.tar.gz newmachine:~/

# On new machine
cd ~
tar -xzf skillops-backup.tar.gz

# Verify
skillops list

Best Practices

  1. Start Small: Begin with one or two skills and gradually add more
  2. Regular Updates: Run skillops update weekly
  3. Clean Regularly: Remove unused skills monthly
  4. Document Setup: Keep a SKILLS_SETUP.md in your project
  5. Test First: Test new skills in a separate project before production use
  6. Backup Config: Regularly backup ~/.skillops/config/agentics.yaml
  7. Use Selective Pull: Use --skill flag to save space when you only need specific skills
  8. Review Regularly: Run skillops list to see what you have installed

Troubleshooting Guide

Common Issues and Solutions

Installation Issues

Command Not Found

Problem: After installation, running skillops shows "command not found"

Solutions:

  1. Check if SkillOps is in your PATH:
which skillops
echo $PATH
  1. Add to your shell profile:
# For bash
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
  1. Verify the binary location:
ls -la /usr/local/bin/skillops

Permission Denied

Problem: Cannot execute skillops binary

Solution:

# Make the binary executable
chmod +x /usr/local/bin/skillops

# If you need sudo access
sudo chmod +x /usr/local/bin/skillops

TUI (Terminal User Interface) Issues

Error: "open /dev/tty: no such device or address"

Problem: SkillOps cannot open interactive TUI

Causes:

  • Running in a non-interactive environment (CI/CD, scripts)
  • Terminal emulator doesn't support TTY

Solutions:

  1. Run in a real terminal (not through pipes or scripts)
  2. If using SSH, ensure you have a proper TTY:
ssh -t user@host skillops list
  1. Check if your terminal supports TTY:
tty
# Should output something like /dev/ttys001

TUI Display Issues

Problem: TUI interface looks broken or garbled

Solutions:

  1. Update your terminal emulator
  2. Set proper TERM environment variable:
export TERM=xterm-256color
  1. Try a different terminal emulator (iTerm2, Alacritty, etc.)

Skill Management Issues

Skill Not Found After Pull

Problem: Pulled a repository but skills don't appear in skillops list

Causes:

  • Repository doesn't contain SKILL.md file
  • Incorrect repository structure

Solutions:

  1. Check if SKILL.md exists in repository root:
ls ~/.skillops/skills/repo-name/SKILL.md
  1. Verify repository structure:
tree ~/.skillops/skills/repo-name
  1. Manually create SKILL.md if needed:
echo "# My Skill" > ~/.skillops/skills/repo-name/SKILL.md

Git Clone Failures

Problem: Cannot pull skills from GitHub

Solutions:

  1. Check internet connection
  2. Verify GitHub URL is correct
  3. For private repositories, ensure SSH keys are configured:
ssh -T git@github.com
  1. Try HTTPS instead of SSH:
# Instead of git@github.com:user/repo.git
skillops pull https://github.com/user/repo

Symlink Issues

Broken Symlinks

Problem: Symlinks point to non-existent locations

Causes:

  • Skill was removed from global directory
  • Directory was moved or renamed

Solutions:

  1. Check symlink status:
ls -la .agents/skills/
  1. Remove broken symlinks:
find .agents/skills -type l ! -exec test -e {} \; -delete
  1. Re-manage skills:
skillops agentic manage claude

Permission Issues with Symlinks

Problem: Cannot create symlinks in project directory

Solutions:

  1. Check directory permissions:
ls -la .agents/
  1. Fix permissions:
chmod 755 .agents/skills/
  1. On Windows, ensure Developer Mode is enabled or run as Administrator

Configuration Issues

Configuration File Not Found

Problem: SkillOps cannot find configuration file

Solutions:

  1. Create config directory:
mkdir -p ~/.skillops/config
  1. Run SkillOps to auto-generate config:
skillops list
  1. Manually create configuration:
cat > ~/.skillops/config/agentics.yaml << EOF
agentics:
  - name: "claude"
    path: ".agents/skills"
EOF

Invalid Configuration Format

Problem: Configuration file is corrupted or invalid

Solution:

  1. Backup current config:
cp ~/.skillops/config/agentics.yaml ~/.skillops/config/agentics.yaml.bak
  1. Validate YAML syntax:
# Using Python
python -c "import yaml; yaml.safe_load(open('~/.skillops/config/agentics.yaml'))"
  1. Reset to default configuration:
rm ~/.skillops/config/agentics.yaml
skillops list  # Will regenerate default config

Project-Specific Issues

Skills Not Appearing in IDE

Problem: Linked skills don't show up in IDE

Solutions:

  1. Verify symlinks exist:
ls -la .agents/skills/
  1. Restart your IDE
  2. Check IDE's skill directory configuration
  3. Verify IDE supports the skill format

Multiple Projects Conflict

Problem: Skills from one project affect another

Explanation: This shouldn't happen as SkillOps uses project-specific symlinks

Solutions:

  1. Verify each project has its own skill directories
  2. Check for global IDE configurations that might override project settings
  3. Ensure you're running skillops agentic in the correct project directory

Update Issues

Update Fails

Problem: skillops update fails to update skills

Solutions:

  1. Check internet connection
  2. Verify Git is installed:
git --version
  1. Manually update:
cd ~/.skillops/skills/repo-name
git pull origin main
  1. Remove and re-pull the skill:
skillops remove skill-name
skillops pull https://github.com/user/repo

Performance Issues

Slow Operations

Problem: SkillOps commands are slow

Solutions:

  1. Check disk space:
df -h ~/.skillops
  1. Clean up unused skills:
skillops remove-all  # Be careful!
  1. Check for large repositories:
du -sh ~/.skillops/skills/*

Getting Help

Verbose Output

Enable verbose logging for debugging:

# Set environment variable
export SKILLOPS_DEBUG=true
skillops list

Collecting Debug Information

When reporting issues, include:

  1. SkillOps version:
skillops --version
  1. Operating system:
uname -a
  1. Configuration:
cat ~/.skillops/config/agentics.yaml
  1. Directory structure:
tree -L 2 ~/.skillops

Community Support

  • GitHub Issues: Report bugs and request features
  • Documentation: Check the latest docs for updates
  • Examples: Look at example repositories for reference

Preventive Measures

Regular Maintenance

  1. Update skills regularly:
skillops update
  1. Clean up unused skills:
skillops list  # Review what you have
skillops remove unused-skill
  1. Backup configuration:
cp -r ~/.skillops ~/skillops-backup-$(date +%Y%m%d)

Best Practices

  1. Always run skillops list before making changes
  2. Use skillops agentic manage instead of manual symlink creation
  3. Keep skill repositories small and focused
  4. Document custom configurations
  5. Test in a single project before applying globally

Still Having Issues?

If you're still experiencing problems:

  1. Check the GitHub repository for known issues
  2. Search existing issues for similar problems
  3. Create a new issue with detailed information:
    • Steps to reproduce
    • Expected behavior
    • Actual behavior
    • System information
    • Configuration files
    • Error messages

Quick Start Guide

1

Install SkillOps

Download and install the CLI tool on your system

2

Pull Your First Skill

Use skillops pull to download a skill repository

3

Configure Your IDEs

Run skillops agentic to set up your project

4

Start Managing Skills

Use the interactive TUI to enable/disable skills across your IDEs