spec

package
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 6, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package spec holds the SkillSpec intermediate representation — the source of truth every other eval component derives from. The generator writes a bundle from it, the contract compiler compiles matchers from it, and the suite generator drafts tasks from it. Nothing downstream parses the rendered SKILL.md to recover intent.

Index

Constants

View Source
const MaxDescription = 1024

MaxDescription is the Agent Skills spec limit on frontmatter description.

View Source
const MaxModules = 3

MaxModules caps bundled resource files. SkillsBench found focused skills beat exhaustive bundles, so this is a hard limit rather than a warning.

View Source
const MaxName = 64

MaxName is the Agent Skills spec limit on skill name length.

Variables

View Source
var ErrEmptyIntent = errors.New("spec: intent is empty")

ErrEmptyIntent is returned when there is nothing to interview about.

Functions

This section is empty.

Types

type DepsDecl

type DepsDecl struct {
	Apt []string `yaml:"apt,omitempty" json:"apt,omitempty"`
	Pip []string `yaml:"pip,omitempty" json:"pip,omitempty"`
	Npm []string `yaml:"npm,omitempty" json:"npm,omitempty"`
}

DepsDecl lists packages baked into the per-skill sandbox image layer.

type ModelTier

type ModelTier string

ModelTier names the capability floor the generator writes for.

"Tier" is heavily overloaded in this codebase: runner.Tier is eval depth (smoke/full/deep), ModelTier is model capability (floor/mid/strong), distractor difficulty is graded by distance from the skill (near/mid/far), and agent.Caps.EventTier grades how much fidelity an adapter's event stream carries (A/B/C). Four different axes, one overloaded word. runner.Member uses the field name Class rather than Tier for exactly this reason — its value is still a ModelTier, but the field name doesn't collide with runner.Tier sitting one struct away.

const (
	TierFloor  ModelTier = "floor"
	TierMid    ModelTier = "mid"
	TierStrong ModelTier = "strong"
)

type ResourceItem

type ResourceItem struct {
	Path    string `yaml:"path" json:"path"`
	Purpose string `yaml:"purpose,omitempty" json:"purpose,omitempty"`
}

ResourceItem is one planned bundle file.

type ResourcePlan

type ResourcePlan struct {
	Scripts    []ResourceItem `yaml:"scripts,omitempty" json:"scripts,omitempty"`
	References []ResourceItem `yaml:"references,omitempty" json:"references,omitempty"`
	Assets     []ResourceItem `yaml:"assets,omitempty" json:"assets,omitempty"`
}

ResourcePlan decides what becomes scripts/ vs references/ vs assets/.

func (ResourcePlan) Count

func (p ResourcePlan) Count() int

Count returns the total number of planned modules, for the MaxModules cap.

type Rule

type Rule struct {
	ID       string   `yaml:"id" json:"id"`
	Text     string   `yaml:"text" json:"text"`
	Kind     RuleKind `yaml:"kind" json:"kind"`
	Severity Severity `yaml:"severity" json:"severity"`
}

Rule is a MUST or MUST-NOT constraint.

type RuleKind

type RuleKind string

RuleKind distinguishes a positive obligation from a prohibition.

const (
	RuleMust    RuleKind = "must"
	RuleMustNot RuleKind = "must_not"
)

type Severity

type Severity string

Severity grades a constraint. It is carried through to the drift contract's forbid rules, where it weights ViolationScore.

const (
	SeverityCritical Severity = "critical"
	SeverityMajor    Severity = "major"
	SeverityMinor    Severity = "minor"
)

type SkillSpec

type SkillSpec struct {
	Name        string          `yaml:"name" json:"name"`
	Purpose     string          `yaml:"purpose" json:"purpose"`
	Description string          `yaml:"description" json:"description"`
	Triggers    []TriggerPhrase `yaml:"triggers" json:"triggers"`
	Steps       []Step          `yaml:"steps" json:"steps"`
	Constraints []Rule          `yaml:"constraints,omitempty" json:"constraints,omitempty"`
	Resources   ResourcePlan    `yaml:"resources,omitempty" json:"resources,omitempty"`
	Deps        DepsDecl        `yaml:"deps,omitempty" json:"deps,omitempty"`
	TargetTier  ModelTier       `yaml:"target_tier" json:"target_tier"`
}

SkillSpec is the IR.

func Interview

func Interview(ctx context.Context, g llm.Gateway, intent string) (*SkillSpec, error)

Interview turns a natural-language intent into a validated SkillSpec using two gateway calls: a structured draft, then a self-critique pass that is shown the draft together with its own validation errors.

The second call is a repair, not a re-roll — it is told exactly what was wrong. Re-asking the same question without that feedback tends to reproduce the same defect and spends a session to do it.

func Load

func Load(r io.Reader) (*SkillSpec, error)

Load parses a SkillSpec from YAML. Unknown fields are an error: a spec with a misspelled key would otherwise silently lose whatever that key described.

func (*SkillSpec) DirName

func (s *SkillSpec) DirName() string

DirName returns the on-disk directory name for the skill. Registry names may be namespaced with colons (superpowers:brainstorming) which the Agent Skills spec does not permit in a directory name, so the namespace is stripped.

func (*SkillSpec) Save

func (s *SkillSpec) Save(w io.Writer) error

Save writes the spec as block-style YAML with two-space indentation. A human reviews this output at the approval gate, so readability is a requirement.

func (*SkillSpec) Validate

func (s *SkillSpec) Validate() []error

Validate reports every structural problem with the IR, rather than stopping at the first — the interview's self-critique pass feeds the whole list back to the model in one call.

type Step

type Step struct {
	ID            string `yaml:"id" json:"id"`
	Action        string `yaml:"action" json:"action"`
	Postcondition string `yaml:"postcondition" json:"postcondition"`
	Validation    bool   `yaml:"validation,omitempty" json:"validation,omitempty"`
	Rationale     string `yaml:"rationale,omitempty" json:"rationale,omitempty"`
}

Step is one action in the skill's workflow. Every step carries a verifiable postcondition; Validation marks the steps that are checkpoints.

type TriggerPhrase

type TriggerPhrase struct {
	Text     string `yaml:"text" json:"text"`
	Negative bool   `yaml:"negative,omitempty" json:"negative,omitempty"`
}

TriggerPhrase is one example prompt. Negative phrases are hard negatives — adjacent-domain near-misses. Obviously-irrelevant negatives test nothing, so the interview prompt asks for near-misses explicitly.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL