markdown

Documentation

Overview

Package markdown provides parsing and structs for markdown frontmatter.

Index

• type BaseFrontMatter
• type CommandFrontMatter
  • func (c *CommandFrontMatter) UnmarshalJSON(data []byte) error
• type Markdown
  • func FromContent[T any](frontMatter T, content string) Markdown[T]
  • func ParseMarkdownFile[T any](path string, frontMatter *T) (Markdown[T], error)
• type ParseError
  • func (e *ParseError) Error() string
• type RuleFrontMatter
  • func (r *RuleFrontMatter) UnmarshalJSON(data []byte) error
• type RuleMarkdown
• type SkillFrontMatter
  • func (s *SkillFrontMatter) UnmarshalJSON(data []byte) error
• type TaskFrontMatter
  • func (t *TaskFrontMatter) UnmarshalJSON(data []byte) error
• type TaskMarkdown

Types

type BaseFrontMatter

type BaseFrontMatter struct {
	// Name is the skill identifier
	// Must be 1-64 characters, lowercase alphanumeric and hyphens only
	Name string `json:"name,omitempty" yaml:"name,omitempty"`

	// Description explains what the prompt does and when to use it
	// Must be 1-1024 characters
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Content captures any frontmatter fields not explicitly declared in the struct.
	// With yaml:",inline", goccy/go-yaml populates this map with all unknown keys,
	// while known fields on the embedding struct (e.g. TaskNames, License) are set
	// directly on those fields. This ensures outer-struct fields are not shadowed.
	Content map[string]any `json:"-" yaml:",inline"`
}

BaseFrontMatter represents parsed YAML frontmatter from markdown files.

type CommandFrontMatter

type CommandFrontMatter struct {
	BaseFrontMatter `yaml:",inline"`

	// ExpandParams controls whether parameter expansion should occur
	// Defaults to true if not specified
	ExpandParams *bool `json:"expand,omitempty" yaml:"expand,omitempty"`

	// Selectors contains additional custom selectors for filtering rules
	// When a command is used in a task, its selectors are combined with task selectors
	Selectors map[string]any `json:"selectors,omitempty" yaml:"selectors,omitempty"`
}

CommandFrontMatter represents the frontmatter fields for command files. Previously this was an empty placeholder struct, but now supports the expand field to control parameter expansion behavior in command content.

func (*CommandFrontMatter) UnmarshalJSON

func (c *CommandFrontMatter) UnmarshalJSON(data []byte) error

UnmarshalJSON custom unmarshaler that populates both typed fields and Content map.

type Markdown

type Markdown[T any] struct {
	FrontMatter T               // Parsed YAML frontmatter
	Content     string          // Markdown body, excluding frontmatter
	Structure   ast.Node        // Document AST from goldmark parse
	Task        taskparser.Task // Parsed task structure (slash commands and text blocks)
	Tokens      int             // Estimated token count
}

Markdown represents a markdown file with frontmatter and content.

func FromContent

func FromContent[T any](frontMatter T, content string) Markdown[T]

FromContent creates a Markdown from processed content string (e.g. after parameter expansion). The content is parsed to produce the Structure AST.

func ParseMarkdownFile

func ParseMarkdownFile[T any](path string, frontMatter *T) (Markdown[T], error)

ParseMarkdownFile parses a markdown file into frontmatter and content using goldmark. Errors include file path and, where available, line and column position.

type ParseError

type ParseError struct {
	File    string
	Line    int // 1-indexed; 0 means unknown
	Column  int // 1-indexed; 0 means unknown
	Message string
}

ParseError is a markdown parsing error with file, line, and column position.

func (*ParseError) Error

func (e *ParseError) Error() string

type RuleFrontMatter

type RuleFrontMatter struct {
	BaseFrontMatter `yaml:",inline"`

	// TaskNames specifies which task(s) this rule applies to
	// Array of task names for OR logic
	TaskNames []string `json:"task_names,omitempty" yaml:"task_names,omitempty"`

	// Languages specifies which programming language(s) this rule applies to
	// Array of languages for OR logic (e.g., ["go", "python"])
	Languages []string `json:"languages,omitempty" yaml:"languages,omitempty"`

	// Agent specifies which AI agent this rule is intended for
	Agent string `json:"agent,omitempty" yaml:"agent,omitempty"`

	// MCPServer specifies a single MCP server configuration
	// Metadata only, does not filter
	MCPServer mcp.MCPServerConfig `json:"mcp_server,omitzero" yaml:"mcp_server,omitzero"`

	// ExpandParams controls whether parameter expansion should occur
	// Defaults to true if not specified
	ExpandParams *bool `json:"expand,omitempty" yaml:"expand,omitempty"`

	// Bootstrap contains a shell script to execute before including the rule
	// This is preferred over file-based bootstrap scripts
	Bootstrap string `json:"bootstrap,omitempty" yaml:"bootstrap,omitempty"`
}

RuleFrontMatter represents the standard frontmatter fields for rule files.

func (*RuleFrontMatter) UnmarshalJSON

func (r *RuleFrontMatter) UnmarshalJSON(data []byte) error

UnmarshalJSON custom unmarshaler that populates both typed fields and Content map.

type RuleMarkdown

type RuleMarkdown = Markdown[RuleFrontMatter]

RuleMarkdown is a Markdown with RuleFrontMatter.

type SkillFrontMatter

type SkillFrontMatter struct {
	BaseFrontMatter `yaml:",inline"`

	// License specifies the license applied to the skill (optional)
	License string `json:"license,omitempty" yaml:"license,omitempty"`

	// Compatibility indicates environment requirements (optional)
	// Max 500 characters
	Compatibility string `json:"compatibility,omitempty" yaml:"compatibility,omitempty"`

	// Metadata contains arbitrary key-value pairs (optional)
	Metadata map[string]string `json:"metadata,omitempty" yaml:"metadata,omitempty"`

	// AllowedTools is a space-delimited list of pre-approved tools (optional, experimental)
	AllowedTools string `json:"allowed_tools,omitempty" yaml:"allowed_tools,omitempty"`
}

SkillFrontMatter represents the standard frontmatter fields for skill files.

func (*SkillFrontMatter) UnmarshalJSON

func (s *SkillFrontMatter) UnmarshalJSON(data []byte) error

UnmarshalJSON custom unmarshaler that populates both typed fields and Content map.

type TaskFrontMatter

type TaskFrontMatter struct {
	BaseFrontMatter `yaml:",inline"`

	// Agent specifies the default agent if not specified via -a flag
	// This is not used for selecting tasks or rules, only as a default
	Agent string `json:"agent,omitempty" yaml:"agent,omitempty"`

	// Languages specifies the programming language(s) for filtering rules
	// Array of languages for OR logic (e.g., ["go", "python"])
	Languages []string `json:"languages,omitempty" yaml:"languages,omitempty"`

	// Model specifies the AI model identifier
	// Does not filter rules, metadata only
	Model string `json:"model,omitempty" yaml:"model,omitempty"`

	// SingleShot indicates whether the task runs once or multiple times
	// Does not filter rules, metadata only
	SingleShot bool `json:"single_shot,omitempty" yaml:"single_shot,omitempty"`

	// Timeout specifies the task timeout in time.Duration format (e.g., "10m", "1h")
	// Does not filter rules, metadata only
	Timeout string `json:"timeout,omitempty" yaml:"timeout,omitempty"`

	// Resume indicates if this task should be resumed
	Resume bool `json:"resume,omitempty" yaml:"resume,omitempty"`

	// Selectors contains additional custom selectors for filtering rules
	Selectors map[string]any `json:"selectors,omitempty" yaml:"selectors,omitempty"`

	// ExpandParams controls whether parameter expansion should occur
	// Defaults to true if not specified
	ExpandParams *bool `json:"expand,omitempty" yaml:"expand,omitempty"`

	// IncludeUnmatched controls whether rules/skills that don't explicitly match
	// any active selector are included by default. Defaults to true (current behaviour).
	// Set to false to require an explicit selector match (strict/opt-in mode).
	IncludeUnmatched *bool `json:"include_unmatched,omitempty" yaml:"include_unmatched,omitempty"`
}

TaskFrontMatter represents the standard frontmatter fields for task files.

func (*TaskFrontMatter) UnmarshalJSON

func (t *TaskFrontMatter) UnmarshalJSON(data []byte) error

UnmarshalJSON custom unmarshaler that populates both typed fields and Content map.

type TaskMarkdown

type TaskMarkdown = Markdown[TaskFrontMatter]

TaskMarkdown is a Markdown with TaskFrontMatter.