spec

package
v0.13.0 Latest Latest
Warning

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

Go to latest
Published: Sep 2, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package spec holds the SkillSpec IR that generation, suite drafting, and scoring all derive from.

Index

Constants

View Source
const MaxDescription = 1024

MaxDescription is the Agent Skills spec limit on frontmatter description.

View Source
const MaxModules = 3

MaxModules caps scripts/ + assets/. references/ is capped separately by MaxReferences because a reference split out of an over-long body adds no capability.

View Source
const MaxName = 64

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

View Source
const MaxReferences = 6

MaxReferences caps references/, independently of MaxModules. Higher because body offloading is per-section and a realistic skill can need five moves.

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.

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) CapacityCount added in v0.11.0

func (p ResourcePlan) CapacityCount() int

CapacityCount returns the scripts/ + assets/ count, checked against MaxModules.

func (ResourcePlan) Count

func (p ResourcePlan) Count() int

Count returns the total number of planned files.

func (ResourcePlan) ReferenceCount added in v0.11.0

func (p ResourcePlan) ReferenceCount() int

ReferenceCount returns the references/ count, checked against MaxReferences.

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.

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 Recover added in v0.11.0

func Recover(ctx context.Context, g llm.Gateway, skillName, bundleDir string) (*SkillSpec, error)

Recover reconstructs a SkillSpec from a published bundle. It exists because a published bundle never carries spec.yaml — lint.Excluded strips it as authoring scaffolding — so a skill that did not come through whetstone has no IR for the suite generator or contract.Compile to work from.

One gateway call, plus a repair call only when the draft fails validation. Interview's unconditional second call is a design critique, which is the wrong objective here: fidelity to an existing skill is what matters.

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.

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 near-misses.

Jump to

Keyboard shortcuts

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