Documentation
¶
Overview ¶
Package spec holds the SkillSpec IR that generation, suite drafting, and scoring all derive from.
Index ¶
Constants ¶
const MaxDescription = 1024
MaxDescription is the Agent Skills spec limit on frontmatter description.
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.
const MaxName = 64
MaxName is the Agent Skills spec limit on skill name length.
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 ¶
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.
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.
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 ¶
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 ¶
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
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 ¶
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.
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.