English | 简体中文

A Go package to parse Claude Skill packages from a directory structure. This parser is designed according to the specifications found in the official Claude documentation.

• Parses SKILL.md for skill metadata and instructions.
• Extracts YAML frontmatter into a Go struct (SkillMeta).
• Captures the Markdown body of the skill.
• Discovers resource files in scripts/, references/, and assets/ directories.
• Packaged as a reusable Go module.
• Includes command-line interfaces for managing and inspecting skills.
• Includes a deep research agent.

To use this package in your project, you can use go get:

go get github.com/smallnest/goskills

This project includes a standalone Deep Research Agent (agent-web) that demonstrates the power of composable AI skills.

• Planner-Executor-SubAgents Architecture: A robust design for complex task solving.
• Web Interface: A modern web interface for a great user experience.
• No External Frameworks: Pure Go implementation, easy to understand and extend.

Demo：https://agent.rpcx.io

Quick Start:

export OPENAI_API_KEY="YOUR_KEY"
export TAVILY_API_KEY="YOUR_TAVILY_KEY"
make
./agent-web -v

For more details, see agent.md.

This project provides two separate command-line tools:

Located in cmd/skill-cli, this tool helps you inspect and manage your local Claude skills.

You can build the executable from the project root:

go build -o goskills-cli ./cmd/skill-cli

Here are the available commands for goskills-cli:

Lists all valid skills in a given directory.

./goskills-cli list ./examples/skills

Parses a single skill and displays a summary of its structure.

./goskills-cli parse ./examples/skills/artifacts-builder

Displays the full, detailed information for a single skill, including the complete body content.

./goskills-cli detail ./examples/skills/artifacts-builder

Lists all the files that make up a skill package.

./goskills-cli files ./examples/skills/artifacts-builder

Searches for skills by name or description within a directory. The search is case-insensitive.

./goskills-cli search ./examples/skills "web app"

Located in cmd/skill-runner, this tool simulates the Claude skill-use workflow by integrating with Large Language Models (LLMs) like OpenAI's models.

You can build the executable from the project root:

go build -o goskills ./cmd/skill-runner

Here are the available commands for goskills:

Processes a user request by first discovering available skills, then asking an LLM to select the most appropriate one, and finally executing the selected skill by feeding its content to the LLM as a system prompt.

Requires the OPENAI_API_KEY environment variable to be set.

# Example with default OpenAI model (gpt-4o)
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
./goskills run "create an algorithm that generates abstract art"

# Example with a custom OpenAI-compatible model and API base URL using environment variables
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
export OPENAI_API_BASE="https://qianfan.baidubce.com/v2"
export OPENAI_MODEL="deepseek-v3"
./goskills run "create an algorithm that generates abstract art"

# Example with a custom OpenAI-compatible model and API base URL using command-line flags
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
./goskills run --model deepseek-v3 --api-base https://qianfan.baidubce.com/v2 "create an algorithm that generates abstract art"

# Example with a custom OpenAI-compatible model and API base URL using command-line flags, auto-approve without human-in-the-loop
./goskills run --auto-approve --model deepseek-v3 --api-base https://qianfan.baidubce.com/v2 "使用markitdown 工具解析网页 https://baike.baidu.com/item/%E5%AD%94%E5%AD%90/1584"

# Example with a custom OpenAI-compatible model and API base URL using command-line flags, in a loop mode and not exit automatically
./goskills run --auto-approve --model deepseek-v3 --api-base https://qianfan.baidubce.com/v2 --skills-dir=./examples/skills "使用markitdown 工具解析网 页 https://baike.baidu.com/item/%E5%AD%94%E5%AD%90/1584" -l

Here is an example of how to use the ParseSkillPackage function from the goskills library to parse a skill directory.

package main

import (
	"fmt"
	"log"

	"github.com/smallnest/goskills"
)

func main() {
	// Path to the skill directory you want to parse
	skillDirectory := "./examples/skills/artifacts-builder"

	skillPackage, err := goskills.ParseSkillPackage(skillDirectory)
	if err != nil {
		log.Fatalf("Failed to parse skill package: %v", err)
	}

	// Print the parsed information
	fmt.Printf("Successfully Parsed Skill: %s\n", skillPackage.Meta.Name)
	// ... and so on
}

To find and parse all valid skill packages within a directory and its subdirectories, you can use the ParseSkillPackages function. It recursively scans the given path, identifies all directories containing a SKILL.md file, and returns a slice of successfully parsed *SkillPackage objects.

package main

import (
	"fmt"
	"log"

	"github.com/smallnest/goskills"
)

func main() {
	// Directory containing all your skills
	skillsRootDirectory := "./examples/skills"

	packages, err := goskills.ParseSkillPackages(skillsRootDirectory)
	if err != nil {
		log.Fatalf("Failed to parse skill packages: %v", err)
	}

	fmt.Printf("Found %d skill(s):\n", len(packages))
	for _, pkg := range packages {
		fmt.Printf("- Path: %s, Name: %s\n", pkg.Path, pkg.Meta.Name)
	}
}

brew install smallnest/goskills/goskills

or

# add tap
brew tap smallnest/goskills

# install goskills
brew install goskills