OpenSkill CLI Documentation

OpenSkill is a command-line tool for creating and managing Claude skills with AI-powered content generation. It simplifies the process of building reusable skill definitions that enhance Claude's capabilities.

GoCLIAI-Powered

Installation

macOS (Apple Silicon)

curl -L https://github.com/rakshit-gen/openskill/releases/download/v0.1.0/openskill_darwin_arm64.tar.gz | tar xz
sudo mv openskill /usr/local/bin/

macOS (Intel)

curl -L https://github.com/rakshit-gen/openskill/releases/download/v0.1.0/openskill_darwin_amd64.tar.gz | tar xz
sudo mv openskill /usr/local/bin/

Linux (x86_64)

curl -L https://github.com/rakshit-gen/openskill/releases/download/v0.1.0/openskill_linux_amd64.tar.gz | tar xz
sudo mv openskill /usr/local/bin/

Linux (ARM64)

curl -L https://github.com/rakshit-gen/openskill/releases/download/v0.1.0/openskill_linux_arm64.tar.gz | tar xz
sudo mv openskill /usr/local/bin/

From Source

git clone https://github.com/rakshit-gen/openskill.git
cd openskill
make build
sudo mv build/openskill /usr/local/bin/

Configuration

OpenSkill supports multiple AI providers for skill generation: Groq, OpenAI, Anthropic, and Ollama (local).

Supported Providers

Provider	Default Model	API Key
groq	llama-3.3-70b-versatile	console.groq.com
openai	gpt-4o-mini	platform.openai.com
anthropic	claude-3-5-sonnet-20241022	console.anthropic.com
ollama	llama3.2	No API key (local)

Set Your Provider

# Set provider (default: groq)
openskill config set provider groq    # or: openai, anthropic, ollama

# Set API key for your provider
openskill config set api-key

Provider-Specific Setup

# Groq (default - free & fast)
openskill config set provider groq
openskill config set groq-api-key YOUR_KEY

# OpenAI
openskill config set provider openai
openskill config set openai-api-key YOUR_KEY

# Anthropic
openskill config set provider anthropic
openskill config set anthropic-api-key YOUR_KEY

# Ollama (local - no API key needed)
openskill config set provider ollama
openskill config set ollama-model llama3.2

View Configuration

openskill config list

Environment Variables

Environment variables take precedence over config file:

OPENSKILL_PROVIDER=groq       # Provider selection
GROQ_API_KEY=your_key         # Groq API key
OPENAI_API_KEY=your_key       # OpenAI API key
ANTHROPIC_API_KEY=your_key    # Anthropic API key
OPENSKILL_MODEL=gpt-4o        # Override model
OLLAMA_HOST=http://localhost:11434  # Custom Ollama endpoint

Commands

OpenSkill provides comprehensive commands for managing your skills:

openskill initInitialize OpenSkill in your project

openskill addCreate a new skill with optional AI generation

openskill listList all available skills

openskill showDisplay detailed information about a skill

openskill editModify an existing skill

openskill removeDelete a skill

openskill validateValidate a skill's YAML structure

openskill historyShow version history of a skill

openskill rollbackRestore a skill to a previous version

openskill configManage OpenSkill configuration

openskill init

Initialize OpenSkill in your project. This is the recommended first command to run when setting up OpenSkill in a new project.

Usage

openskill init

What It Does

Creates the .claude/skills/ directory
Optionally configures your Groq API key
Creates an example skill to get you started
Displays helpful guidance on using skills with Claude

Example Output

$ openskill init

  ╔═══════════════════════════════════════════════════════════╗
  ║   ⚡ OpenSkill - Claude Skill Manager                     ║
  ╚═══════════════════════════════════════════════════════════╝

  [1/3] Setting up skills directory...
        ✓ Created .claude/skills/

  [2/3] Checking API configuration...
        ✓ API key configured (gsk_...xxxx)

  [3/3] Creating example skill...
        ✓ Created example/SKILL.md

  ╔═══════════════════════════════════════════════════════════╗
  ║                    Setup Complete!                        ║
  ╚═══════════════════════════════════════════════════════════╝

openskill add

Create a new skill. By default, uses AI to generate comprehensive descriptions and rules.

Usage

openskill add <name> -d <description> [flags]

Flags

Flag	Description
-d, --desc	Skill description (required)
-r, --rule	Add a rule (manual mode only, can be repeated)
--manual	Skip AI generation, use provided values

Examples

# AI-powered skill creation
openskill add "code-review" -d "Reviews code for best practices"

# Manual skill creation
openskill add "bug-finder" -d "Finds bugs" --manual -r "Check nulls" -r "Check edge cases"

openskill list

Display all skills in the current directory.

Usage

openskill list

Output

$ openskill list
  code-review     Reviews code for best practices
  bug-finder      Finds bugs in code
  test-writer     Generates unit tests

openskill show

Display detailed information about a specific skill.

Usage

openskill show <name>

Example

$ openskill show "code-review"

Name: code-review
Description: Comprehensive code review focusing on security, performance, and maintainability
Rules:
  1. Check for security vulnerabilities (XSS, SQL injection, etc.)
  2. Verify proper error handling and edge cases
  3. Ensure code follows project conventions
  4. Review test coverage and quality

openskill edit

Modify an existing skill's description or rules.

Usage

openskill edit <name> [flags]

Flags

Flag	Description
-d, --desc	New description
-r, --rule	Replace rules (can be repeated)

Examples

# Update description
openskill edit "code-review" -d "New description"

# Replace rules
openskill edit "code-review" -r "New rule 1" -r "New rule 2"

openskill remove

Delete a skill from the skills directory.

Usage

openskill remove <name>

Example

$ openskill remove "old-skill"
✓ Removed skill: old-skill

openskill validate

Validate a skill's YAML structure and content before using it with Claude.

Usage

openskill validate <name>

What It Checks

YAML syntax validation
Required fields (name, description)
Rule format and content quality
Best practices recommendations

Example

$ openskill validate "code-review"

  ✓ Skill 'code-review' is valid

  Skill Summary:
  ─────────────
  Name:        code-review
  Description: Reviews code for best practices and security...
  Rules:       5 defined

Validation with Warnings

$ openskill validate "quick-skill"

  ⚠ Validation Passed with Warnings: quick-skill

  Warnings:
  └─ Description is very short - add more detail for clarity
  └─ Rule 1 is very short - be more specific

openskill history

Show the version history of a skill. Each time you edit a skill, the previous version is automatically saved.

Usage

openskill history <name>

Example

$ openskill history "code-review"

  Version History: code-review
  ════════════════════════════════════════════

  ● current     2025-01-15 14:32:00  (active)
  ○ v2          2025-01-14 10:15:00
  ○ v1          2025-01-13 09:00:00

  To restore a version: openskill rollback code-review <version>

openskill rollback

Restore a skill to a previous version. The current version is automatically saved to history before the rollback.

Usage

openskill rollback <name> <version>

Example

$ openskill rollback "code-review" v1

  ✓ Restored 'code-review' to version 1

  The previous version has been saved to history.
  Use 'openskill show code-review' to view the restored skill.

openskill config

Manage OpenSkill configuration. Settings are stored in ~/.openskill/config.yaml and persist across terminal sessions.

Subcommands

Command	Description
set <key> [value]	Set a configuration value
get <key>	Get a configuration value
list	List all configuration values

Configuration Keys

Key	Description
api-key	Your Groq API key for AI features
model	LLM model to use (default: llama-3.3-70b-versatile)

Examples

# Set API key (prompts for secure input)
openskill config set api-key

# Set API key directly
openskill config set api-key gsk_your_key_here

# Change the LLM model
openskill config set model llama-3.1-8b-instant

# View current configuration
openskill config list

# Get a specific value
openskill config get api-key

Environment Variables

Environment variables take precedence over config file values:

GROQ_API_KEY - Overrides api-key
OPENSKILL_MODEL - Overrides model

Skill Format

Skills are Markdown files with YAML frontmatter, stored in directories under .claude/skills/. Each skill is a folder containing a SKILL.md file.

Directory Structure

.claude/
└── skills/
    ├── code-review/
    │   └── SKILL.md
    ├── bug-finder/
    │   └── SKILL.md
    └── test-writer/
        └── SKILL.md

SKILL.md Format

Each skill file starts with YAML frontmatter (metadata) followed by Markdown content:

---
name: code-review
description: Comprehensive code review focusing on security and maintainability
---

# code-review

Comprehensive code review focusing on security, performance,
and maintainability best practices.

## Rules

- Check for security vulnerabilities (XSS, SQL injection, etc.)
- Verify proper error handling and edge cases
- Ensure code follows project conventions
- Review test coverage and quality

Why This Format?

Claude natively discovers and reads SKILL.md files
YAML frontmatter provides metadata for skill discovery
Markdown body allows rich, structured instructions
Directory-based structure supports additional files per skill

Skill Composition

OpenSkill supports skill composition through extends and includes fields, allowing you to build complex skills from simpler components.

Extending Skills

Use extends in the frontmatter to inherit from a parent skill:

---
name: security-review
description: Security-focused code review
extends: code-review
---

# security-review

Security-focused code review that extends the base code-review skill.

## Rules

- Focus specifically on OWASP Top 10 vulnerabilities
- Check authentication and authorization flows
- Verify input validation and sanitization

Including Multiple Skills

Use includes to merge multiple skills together:

---
name: full-review
description: Comprehensive review combining multiple aspects
includes:
  - code-review
  - security-review
  - performance-review
---

# full-review

Comprehensive review combining multiple skill aspects.

## Rules

- Provide a summary score for each review area

Composition Benefits

Build specialized skills from general ones
Avoid duplicating common rules across skills
Create skill libraries that can be reused
Compose complex behaviors from simple building blocks

AI Generation

OpenSkill uses Groq's LLM to automatically generate comprehensive skill content from simple descriptions.

How It Works

You provide a skill name and brief description
OpenSkill sends the info to Groq's API
The AI generates a detailed description and relevant rules
The enhanced skill is saved to your skills directory

Fallback Behavior

If the API is unavailable or you use --manual, OpenSkill falls back to using your provided description and rules directly.

Examples

Creating a Code Review Skill

$ openskill add "code-review" -d "Reviews code for best practices"

Generating skill with AI...

✓ Added skill: code-review
  Description: Comprehensive code review focusing on security, performance, and maintainability
  Rules:
    1. Check for security vulnerabilities (XSS, SQL injection, etc.)
    2. Verify proper error handling and edge cases
    3. Ensure code follows project conventions
    4. Review test coverage and quality

Creating a Documentation Skill

$ openskill add "doc-writer" -d "Writes technical documentation"

Generating skill with AI...

✓ Added skill: doc-writer
  Description: Creates clear, comprehensive technical documentation for code and APIs
  Rules:
    1. Include code examples for all functions
    2. Document parameters and return values
    3. Add usage examples and edge cases
    4. Keep language clear and concise

Workflow Example

# Create a skill
openskill add "api-designer" -d "Designs RESTful APIs"

# View all skills
openskill list

# Check skill details
openskill show "api-designer"

# Update the skill
openskill edit "api-designer" -r "Follow REST conventions" -r "Use proper HTTP methods"

# Remove if no longer needed
openskill remove "api-designer"