Unified skill infrastructure for AI agents in Go.
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
go get github.com/plexusone/omniskillpackage 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},
}
}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})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"},
},
})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())
}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()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 reggithub.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
The role/ package defines interfaces for high-level agent personas that compose skills and define behavior. Roles separate organizational responsibilities from runtime implementations.
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", ""),
},
}
}Roles can implement additional interfaces for enhanced capabilities:
| Interface | Purpose |
|---|---|
SkillRequirer |
Roles with optional skills |
BehaviorProvider |
Context-aware behaviors (meeting, chat, autonomous) |
MetricsProvider |
KPIs and success metrics |
DelegationProvider |
Sub-agent orchestration |
PolicyProvider |
Governance rules |
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.
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)| Tool | Description |
|---|---|
transfer_call |
Transfer call to another number or agent queue |
hold_call |
Place caller on hold with optional music |
unhold_call |
Resume call from hold |
consult_agent |
Query specialist AI without transferring |
add_to_conference |
Add participants to conference call |
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@latestimport "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.
| Feature | Library Mode | MCP Server | MCP Client |
|---|---|---|---|
| Direct tool calls | ✓ | - | - |
| JSON-RPC overhead | None | Yes | Yes |
| Claude Desktop | - | ✓ | - |
| Remote servers | - | - | ✓ |
| Skill interface | ✓ | ✓ | ✓ |
- Define Once, Use Everywhere - Skills work in library mode, as MCP servers, or wrapping MCP clients
- Protocol at the Edge - MCP is for external communication; internal calls bypass JSON-RPC
- Type Safety - Generic handlers with automatic JSON schema inference
- Composable - Skills can wrap other skills or remote MCP sessions
MIT License - see LICENSE file for details.