config

Documentation

Index

• Variables
• type AgentSpec
  • func (a *AgentSpec) ResponseSchemaJSON() json.RawMessage
• type DocType
• type Document
  • func LoadDir(dir string) ([]*Document, error)
  • func Parse(raw []byte) (*Document, error)
  • func ParseFile(path string) (*Document, error)
  • func (d *Document) Meta() Meta
• type Issue
  • func Validate(doc *Document) []Issue
  • func ValidateDocs(docs []*Document) []Issue
  • func (i Issue) Error() string
• type MCPInstall
• type MCPServerSpec
• type MCPTransport
• type Meta
• type SkillSpec
• type ToolRuntime
• type ToolSpec

Variables

var ErrMissingFrontmatter = errors.New("missing YAML frontmatter")

ErrMissingFrontmatter is returned when a file has no YAML frontmatter block.

var ErrUnknownType = errors.New("unknown document type")

ErrUnknownType is returned when frontmatter declares an unknown type.

Types

type AgentSpec

type AgentSpec struct {
	Meta            `yaml:",inline"`
	Model           string   `yaml:"model"`
	FallbackModels  []string `yaml:"fallback,omitempty"`
	Tools           []string `yaml:"tools,omitempty"`
	MCP             []string `yaml:"mcp,omitempty"`
	Skills          []string `yaml:"skills,omitempty"`
	Subagents       []string `yaml:"subagents,omitempty"`
	Powers          []string `yaml:"powers,omitempty"`
	Temperature     *float64 `yaml:"temperature,omitempty"`
	MaxTokens       *int     `yaml:"max_tokens,omitempty"`
	ThinkingPhrases []string `yaml:"thinking_phrases,omitempty"`
	PIIGuard        string   `yaml:"pii_guard,omitempty"`
	ResponseSchema  any      `yaml:"response_schema,omitempty"`
}

AgentSpec describes a runnable agent.

func (*AgentSpec) ResponseSchemaJSON

func (a *AgentSpec) ResponseSchemaJSON() json.RawMessage

ResponseSchemaJSON returns the response_schema as JSON bytes suitable for passing to providers. Returns nil if no schema is set.

type DocType

type DocType string

DocType identifies the kind of MD document.

const (
	TypeAgent     DocType = "agent"
	TypeSkill     DocType = "skill"
	TypeTool      DocType = "tool"
	TypeMCPServer DocType = "mcp_server"
)

type Document

type Document struct {
	Path string
	Body string
	Spec any
}

Document is the parsed result of a single MD file. Spec holds a pointer to the typed spec matching Meta.Type.

func LoadDir

func LoadDir(dir string) ([]*Document, error)

LoadDir walks dir recursively and parses every .md file. Parse errors are returned as a joined error so callers see all problems at once.

func Parse

func Parse(raw []byte) (*Document, error)

Parse parses the bytes of a single MD file with YAML frontmatter.

func ParseFile

func ParseFile(path string) (*Document, error)

ParseFile reads and parses a single MD file at path.

func (*Document) Meta

func (d *Document) Meta() Meta

Meta returns the embedded Meta from the document's typed spec.

type Issue

type Issue struct {
	Path    string
	Field   string
	Message string
}

Issue is a single validation problem found in a Document.

func Validate

func Validate(doc *Document) []Issue

Validate checks a single document and returns all issues found.

func ValidateDocs

func ValidateDocs(docs []*Document) []Issue

ValidateDocs validates a collection of documents and additionally checks cross-references: agent.tools / agent.mcp / agent.skills / agent.subagents must resolve to known documents in the same set, with the right type.

func (Issue) Error

func (i Issue) Error() string

type MCPInstall

type MCPInstall struct {
	Pip  string `yaml:"pip,omitempty"`
	Npm  string `yaml:"npm,omitempty"`
	Brew string `yaml:"brew,omitempty"`
}

MCPInstall describes how to install the MCP server binary.

type MCPServerSpec

type MCPServerSpec struct {
	Meta          `yaml:",inline"`
	Transport     MCPTransport      `yaml:"transport"`
	Command       []string          `yaml:"command,omitempty"`
	URL           string            `yaml:"url,omitempty"`
	Env           map[string]string `yaml:"env,omitempty"`
	ToolPrefix    string            `yaml:"tool_prefix,omitempty"`
	AllowedAgents []string          `yaml:"allowed_agents,omitempty"`
	Install       *MCPInstall       `yaml:"install,omitempty"`
}

MCPServerSpec describes an MCP server the agent can connect to.

type MCPTransport

type MCPTransport string

MCPTransport identifies how the MCP client connects to the server.

const (
	TransportStdio MCPTransport = "stdio"
	TransportSSE   MCPTransport = "sse"
	TransportHTTP  MCPTransport = "http"
)

type Meta

type Meta struct {
	Name        string  `yaml:"name"`
	Type        DocType `yaml:"type"`
	Description string  `yaml:"description,omitempty"`
	Version     int     `yaml:"version,omitempty"`
}

Meta is the common frontmatter present on every document.

type SkillSpec

type SkillSpec struct {
	Meta  `yaml:",inline"`
	Tools []string `yaml:"tools,omitempty"`
}

SkillSpec describes a reusable instruction block composed into an agent.

type ToolRuntime

type ToolRuntime string

ToolRuntime identifies how a tool is executed.

const (
	RuntimeBuiltin ToolRuntime = "builtin"
	RuntimeMCP     ToolRuntime = "mcp"
	RuntimeShell   ToolRuntime = "shell"
)

type ToolSpec

type ToolSpec struct {
	Meta    `yaml:",inline"`
	Runtime ToolRuntime       `yaml:"runtime"`
	Command []string          `yaml:"command,omitempty"`
	Env     map[string]string `yaml:"env,omitempty"`
}

ToolSpec describes a tool definition (builtin pointer, MCP reference, or external shell command).