skill

Documentation

Overview

Package skill defines the plugin/skill interface and registration system for extending Helix's tool set without touching core (WFL-03).

Index

• func InitAll(deps SkillDeps) error
• func Register(s Skill)
• func Reset()
• func ResolveTools(skillNames []string, includeTools []string, excludeTools []string) []*mcp.ToolDef
• type ContextSpec
  • func LoadContextSpecs(path string) ([]ContextSpec, error)
• type ModeSpec
  • func LoadModeSpecs(path string) ([]ModeSpec, error)
• type Skill
  • func All() []Skill
  • func Get(name string) (Skill, bool)
• type SkillDeps
• type ToolProvider
  • func ToolProviders() []ToolProvider
• type WorkflowProvider
  • func WorkflowProviders() []WorkflowProvider

Functions

func InitAll

func InitAll(deps SkillDeps) error

InitAll calls Init on every registered skill with the provided dependencies. Returns the first error encountered, or nil if all succeed.

func Register

func Register(s Skill)

Register adds a skill to the global registry. Intended to be called from init() in skill packages (Caddy-style registration). Duplicate names overwrite silently (last wins).

func Reset

func Reset()

Reset clears all registrations. Intended for testing only.

func ResolveTools

func ResolveTools(skillNames []string, includeTools []string, excludeTools []string) []*mcp.ToolDef

ResolveTools takes skill names, include/exclude lists, and the global registry, and returns the list of ToolDefs that should be active. It gathers all tools from named skills (via ToolProviders), adds includeTools by name from the registry, and removes excludeTools.

Types

type ContextSpec

type ContextSpec struct {
	Name         string   `yaml:"name"`
	Description  string   `yaml:"description"`
	Skills       []string `yaml:"skills"`        // skill names to activate
	Tools        []string `yaml:"tools"`         // individual tool names to include
	ExcludeTools []string `yaml:"exclude_tools"` // tools to exclude from active skills
}

ContextSpec defines a tool context loaded from YAML (D-12). Controls which skills and tools are active in a given environment.

func LoadContextSpecs

func LoadContextSpecs(path string) ([]ContextSpec, error)

LoadContextSpecs loads context definitions from a YAML file.

type ModeSpec

type ModeSpec struct {
	Name         string            `yaml:"name"`
	Description  string            `yaml:"description"`
	Skills       []string          `yaml:"skills"`
	Tools        []string          `yaml:"tools"`
	ExcludeTools []string          `yaml:"exclude_tools"`
	Prompts      map[string]string `yaml:"prompts"` // prompt overrides per tool
}

ModeSpec defines an operational mode loaded from YAML (D-12). Controls behavior patterns within a context.

func LoadModeSpecs

func LoadModeSpecs(path string) ([]ModeSpec, error)

LoadModeSpecs loads mode definitions from a YAML file.

type Skill

type Skill interface {
	// Name returns the unique identifier for this skill.
	Name() string
	// Description returns a human-readable description of this skill.
	Description() string
	// Init initializes the skill with shared dependencies.
	Init(deps SkillDeps) error
}

Skill is a reusable capability package (D-13). Skills register via init() and are discoverable at runtime.

func All

func All() []Skill

All returns all registered skills sorted by name.

func Get

func Get(name string) (Skill, bool)

Get returns a skill by name and whether it was found.

type SkillDeps

type SkillDeps struct {
	// ProjectDir is the .helix/ directory for project-scoped data.
	ProjectDir string
	// GlobalDir is the ~/.helix/ directory for global data.
	GlobalDir string
	// Logger is the structured logger for skill output.
	Logger *slog.Logger
}

SkillDeps provides dependencies that skills need during initialization.

type ToolProvider

type ToolProvider interface {
	Skill
	// Tools returns the MCP tool definitions this skill provides.
	Tools() []*mcp.ToolDef
}

ToolProvider is a Skill that contributes MCP tools (D-14 tool skill).

func ToolProviders

func ToolProviders() []ToolProvider

ToolProviders returns all registered skills that implement ToolProvider, sorted by name.

type WorkflowProvider

type WorkflowProvider interface {
	Skill
	// Prompts returns a map of prompt name to prompt template content.
	Prompts() map[string]string
}

WorkflowProvider is a Skill that contributes prompts/context (D-14 workflow skill).

func WorkflowProviders

func WorkflowProviders() []WorkflowProvider

WorkflowProviders returns all registered skills that implement WorkflowProvider, sorted by name.