Introduction

GoSkills is a Go package designed to parse and run Claude Skill packages. It adheres to the specifications found in the official Claude documentation, allowing you to build intelligent agents that can utilize a wide range of skills.

Installation

To use GoSkills in your project, you can install it via go get:

go get github.com/smallnest/goskills

You can also install the CLI tools using Homebrew:

brew tap smallnest/goskills
brew install goskills

GoSkills Runner

The GoSkills Runner (goskills) is the primary tool for executing Claude skills with LLM integration. It simulates the Claude skill-use workflow by discovering available skills, selecting the most appropriate one, and executing it.

Basic Usage

Set your OpenAI API key and run the runner:

export OPENAI_API_KEY="YOUR_KEY"
./goskills run "create an algorithm that generates abstract art"

Features

Configuration Options

# Use custom model and API base
export OPENAI_API_KEY="YOUR_KEY"
export OPENAI_API_BASE="https://api.deepseek.com/v1"
export OPENAI_MODEL="deepseek-v3"
./goskills run "your prompt here"

Command-Line Options

# Available options
--skills-dir DIR     # Specify skills directory (default: ./skills)
--model MODEL         # Custom model name
--api-base URL       # Custom API base URL
--auto-approve        # Skip human approval for tool execution
--verbose             # Enable verbose output
--loop                # Run in continuous loop mode

Example Usage

# Basic skill execution
./goskills run "create a React component for a todo app"

# With custom model
./goskills run --model deepseek-v3 --api-base https://api.deepseek.com/v1 "your prompt"

# Auto-approve tool execution
./goskills run --auto-approve "use markitdown to parse https://example.com"

# Loop mode for continuous interaction
./goskills run --loop "interactive mode"

GoSkills CLI

The GoSkills CLI (goskills-cli) is used for inspecting and managing your local Claude skills.

Available Commands

Examples

# List all skills in a directory
./goskills-cli list ./skills

# Parse a specific skill
./goskills-cli parse ./skills/my-skill

# Search for skills
./goskills-cli search ./skills "web app"

# Show skill details
./goskills-cli detail ./skills/data-analysis

# List files in skill package
./goskills-cli files ./skills/my-skill

Library Usage

For programmatic integration, GoSkills provides a Go library that you can import into your projects:

package main

import (
    "fmt"
    "log"
    "github.com/smallnest/goskills"
)

func main() {
    // Parse a single skill package
    skillDirectory := "./skills/my-skill"
    skillPackage, err := goskills.ParseSkillPackage(skillDirectory)
    if err != nil {
        log.Fatalf("Failed to parse skill package: %v", err)
    }
    fmt.Printf("Skill: %s\n", skillPackage.Meta.Name)
    fmt.Printf("Description: %s\n", skillPackage.Meta.Description)

    // Parse multiple skills in a directory
    packages, err := goskills.ParseSkillPackages("./skills")
    if err != nil {
        log.Fatalf("Failed to parse skill packages: %v", err)
    }
    fmt.Printf("Found %d skills\n", len(packages))
}

Key Functions

Advanced Configuration

You can use other models like DeepSeek, Qianfan, or any OpenAI-compatible API by specifying the configuration:

export OPENAI_API_KEY="YOUR_KEY"
export OPENAI_API_BASE="https://api.deepseek.com/v1"
export OPENAI_MODEL="deepseek-v3"
export TAVILY_API_KEY="YOUR_TAVILY_KEY"  # For search features

# Run with custom configuration
./goskills run --auto-approve "your advanced prompt here"

MCP Support

GoSkills has built-in support for the Model Context Protocol (MCP), allowing you to connect to external tools and data sources. MCP servers extend the capabilities of GoSkills by providing additional tools beyond the built-in set.

Configuration

Create a mcp.json configuration file to define your MCP servers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "path/to/database.db"]
    }
  }
}

Environment Variables

Built-in Tools

GoSkills includes a comprehensive set of built-in tools that work with MCP: