omniskill

OmniSkill

Unified skill infrastructure for AI agents in Go.

Overview

OmniSkill provides a common interface for defining, registering, and invoking AI agent capabilities across multiple execution environments:

• skill/ - Core Skill and Tool interfaces, CommandTool for CLI wrapping
• role/ - Role interfaces for agent personas with behaviors, policies, and delegation
• roles/ - Reference role implementations (CodeReviewer, MeetingPM)
• loader/ - Skill loaders for SKILL.md markdown and Go formats
• installer/ - Dependency management for skill requirements, with version pinning
• clawhub/ - ClawHub marketplace integration for skill discovery
• pack/ - Skill pack interface, validation, publishing, and scaffolding
• registry/ - Skill registration and capability-based discovery
• migration/ - Adapters and validation for migrating bespoke tool layers to omniskill
• mcp/server/ - MCP server runtime with tools, prompts, resources, rate limiting
• mcp/client/ - MCP client for connecting to remote servers
• mcp/bridge/ - Mount remote MCP servers as local skills
• mcp/oauth2/ - OAuth 2.1 Authorization Server for authenticated MCP, or a pure resource server validating externally-issued tokens
• voicetools/ - Voice call control tools (transfer, hold, consult, conference)

Skills can be invoked via:

• Library mode - Direct in-process calls without protocol overhead
• MCP Server - Expose via Model Context Protocol (stdio, HTTP, SSE)
• MCP Client - Consume remote MCP servers as local skills

Installation

go get github.com/plexusone/omniskill

Quick Start

Define a Skill

package main

import (
    "context"
    "github.com/plexusone/omniskill/skill"
)

func main() {
    // Create a tool
    addTool := skill.NewTool("add", "Add two numbers",
        map[string]skill.Parameter{
            "a": {Type: "number", Required: true},
            "b": {Type: "number", Required: true},
        },
        func(ctx context.Context, params map[string]any) (any, error) {
            a := params["a"].(float64)
            b := params["b"].(float64)
            return map[string]any{"sum": a + b}, nil
        },
    )

    // Create a skill
    mathSkill := &skill.BaseSkill{
        SkillName:        "math",
        SkillDescription: "Mathematical operations",
        SkillTools:       []skill.Tool{addTool},
    }
}

Library Mode

Call tools directly without MCP overhead:

import (
    runtime "github.com/plexusone/omniskill/mcp/server"
    "github.com/modelcontextprotocol/go-sdk/mcp"
)

rt := runtime.New(&mcp.Implementation{
    Name:    "calculator",
    Version: "1.0.0",
}, nil)

rt.RegisterSkill(mathSkill)

// Direct invocation - no JSON-RPC, no transport
result, err := rt.CallTool(ctx, "add", map[string]any{"a": 1.0, "b": 2.0})

MCP Server Mode

Expose skills via MCP for Claude Desktop or other clients:

// stdio (for Claude Desktop)
rt.ServeStdio(ctx)

// HTTP with SSE
rt.ServeHTTP(ctx, &runtime.HTTPServerOptions{Addr: ":8080"})

// With OAuth2 authentication (for ChatGPT.com)
rt.ServeHTTP(ctx, &runtime.HTTPServerOptions{
    Addr: ":8080",
    OAuth2: &runtime.OAuth2Options{
        Users: map[string]string{"admin": "password"},
    },
})

// As a pure resource server validating externally-issued tokens
// (e.g. an enterprise IdP), instead of running a local authorization server
rt.ServeHTTP(ctx, &runtime.HTTPServerOptions{
    Addr: ":8080",
    ExternalAuth: &runtime.ExternalAuthOptions{
        Verifier:             myJWTVerifier, // implements oauth2.TokenVerifier
        AuthorizationServers: []string{"https://idp.example.com"},
    },
})

MCP Client Mode

Connect to remote MCP servers and use them as skills:

import (
    "os/exec"
    "github.com/plexusone/omniskill/mcp/client"
)

c := client.New("my-app", "1.0.0", nil)

// Connect to MCP server
cmd := exec.Command("npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp")
session, err := c.ConnectCommand(ctx, cmd)
defer session.Close()

// Wrap as skill
fsSkill := session.AsSkill(client.WithSkillName("filesystem"))

// Use like any local skill
for _, tool := range fsSkill.Tools() {
    fmt.Println(tool.Name())
}

Registry

Central skill registration and discovery:

import "github.com/plexusone/omniskill/registry"

reg := registry.New()
reg.Register(mathSkill)
reg.Register(fsSkill)

// Discover all tools
for _, tool := range reg.ListTools() {
    fmt.Printf("%s: %s\n", tool.Name(), tool.Description())
}

// Initialize all skills
reg.Init(ctx)
defer reg.Close()

Auto-Registration

Skills registered with the runtime can auto-register with a registry:

reg := registry.New()
rt := runtime.New(impl, &runtime.Options{
    Registry: reg,  // Enable auto-registration
})

rt.RegisterSkill(mathSkill)  // Also registers with reg

Package Structure

github.com/plexusone/omniskill
├── skill/       # Core Skill and Tool interfaces, CommandTool
├── role/        # Role interfaces and specification types
│   ├── role.go        # Role interface, BaseRole, optional interfaces
│   ├── spec.go        # RoleSpec, Responsibility, SkillRequirements
│   ├── behavior.go    # Behavior, BehaviorContext, BehaviorTrigger
│   ├── policy.go      # Policy, PolicyRule, PolicyEnforcement
│   ├── metric.go      # MetricDefinition, MetricType, MetricTarget
│   ├── delegation.go  # DelegationConfig, DelegationRule
│   └── workflow.go    # Workflow interface, WorkflowResult, Artifact
├── roles/       # Reference role implementations (CodeReviewer, MeetingPM)
├── loader/      # Skill loaders for SKILL.md and Go formats
├── installer/   # Dependency management for skills, with version pinning
├── clawhub/     # ClawHub marketplace integration
│   ├── hub.go       # API client
│   ├── manifest.go  # CLAWHUB.json parsing
│   ├── resolver.go  # Dependency resolution
│   └── security.go  # Security scanning
├── pack/        # Skill pack interface: validation, publishing, scaffolding
├── registry/    # Skill registration and capability-based discovery
├── migration/   # Adapters and validation for migrating bespoke tool layers
├── voicetools/  # Voice call control tools
│   ├── context.go     # CallContext, Call, Transport interfaces
│   ├── registry.go    # NewVoiceSkill() registration
│   ├── transfer.go    # transfer_call tool
│   ├── hold.go        # hold_call, unhold_call tools
│   ├── consult.go     # consult_agent tool
│   └── conference.go  # add_to_conference tool
├── mcp/
│   ├── server/  # MCP server runtime (rate limiting, tool auth, logging)
│   ├── client/  # MCP client for remote servers
│   ├── bridge/  # Mount remote MCP servers as local skills
│   └── oauth2/  # OAuth 2.1 authorization server (RFC 7009 revocation, external resource-server mode)
└── doc.go

Roles

The role/ package defines interfaces for high-level agent personas that compose skills and define behavior. Roles separate organizational responsibilities from runtime implementations.

Role Interface

import "github.com/plexusone/omniskill/role"

type MyRole struct {
    role.BaseRole
}

func (r *MyRole) Spec() *role.RoleSpec {
    return &role.RoleSpec{
        ID:          "my-role",
        Name:        "My Role",
        Description: "Does something useful",
        Skills: role.SkillRequirements{
            Required: []role.SkillRef{
                {Name: "skill-a", Purpose: "For doing A"},
            },
        },
        Behaviors: []role.Behavior{
            // Context-aware behaviors
        },
        Metrics: []role.MetricDefinition{
            role.NewCounterMetric("tasks-completed", "Tasks Completed", ""),
        },
    }
}

Optional Interfaces

Roles can implement additional interfaces for enhanced capabilities:

Roles also implement Version() string (via role.BaseRole or directly), matching the skill.Skill interface's versioning convention.

The roles/ package ships reference implementations built on role.BaseRole - CodeReviewer (configurable strictness) and MeetingPM - usable directly or as templates for custom roles.

See Role Interface Reference for complete documentation.

Voice Tools

The voicetools package provides AI agent tools for controlling voice calls:

import (
    "github.com/plexusone/omniskill/voicetools"
)

// Create call context with transport and agent registry
callCtx := voicetools.NewCallContext(call, transport, agentRegistry)

// Create voice skill with all call control tools
voiceSkill := voicetools.NewVoiceSkill(callCtx)

// Register with MCP server
rt.RegisterSkill(voiceSkill)

Available Tools

GitHub

The GitHub skill was extracted to a separate repository in v0.10.0 to keep omniskill's dependency footprint light:

go get github.com/plexusone/omniskill-github@latest

import "github.com/plexusone/omniskill-github/skill"

ghSkill := skill.NewGitHubSkill(os.Getenv("GITHUB_TOKEN"))

if err := ghSkill.Init(ctx); err != nil {
    log.Fatal(err)
}
defer ghSkill.Close()

rt.RegisterSkill(ghSkill)

See omniskill-github for tool reference and documentation.

Documentation

• Getting Started
• Concepts
• MCP Server
• MCP Client
• API Reference

Feature Comparison

Design Philosophy

1. Define Once, Use Everywhere - Skills work in library mode, as MCP servers, or wrapping MCP clients
2. Protocol at the Edge - MCP is for external communication; internal calls bypass JSON-RPC
3. Type Safety - Generic handlers with automatic JSON schema inference
4. Composable - Skills can wrap other skills or remote MCP sessions

License

MIT License - see LICENSE file for details.