Documentation
¶
Overview ¶
Package skills provides shared skill discovery, frontmatter parsing, tier classification, and execution logic used by both the CLI (cmd_skill.go) and the HTTP handler (internal/engine/serve_skills.go).
The package is stateless: all functions accept the skill directories (or workspace root) as parameters so callers control workspace resolution and there are no global side-effects.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func InferTier ¶
func InferTier(skillPath string, fm Frontmatter) int
InferTier determines the tier of a skill from its directory layout and parsed front-matter.
- Tier 0: prose-only SKILL.md (default)
- Tier 1: helper scripts present but no declared exec
- Tier 2: exec field set in frontmatter and bin/<exec> exists
- Tier 3: tier-2 + schema field set
Types ¶
type ExecResult ¶
type ExecResult struct {
Name string `json:"name"`
ExitCode int `json:"exit_code"`
Stdout string `json:"stdout"`
Stderr string `json:"stderr"`
DurationMS int64 `json:"duration_ms"`
Error string `json:"error,omitempty"`
}
ExecResult is the structured outcome of running a skill.
func Exec ¶
func Exec(ctx context.Context, skill *Record, inputJSON, timeoutStr, workspaceRoot string) (*ExecResult, error)
Exec runs a tier-2 or tier-3 skill and returns the structured result.
Parameters:
- ctx: parent context; Exec derives a child context with the resolved timeout.
- skill: the Record to execute.
- inputJSON: raw JSON payload forwarded to the skill via stdin (empty = no stdin).
- timeoutStr: duration string overriding the default 5-minute timeout (empty = use default).
- workspaceRoot: propagated as COGOS_WORKSPACE env var (empty = omitted).
Tier-0 and tier-1 skills are rejected with a structured error prefix so callers can map them to appropriate HTTP status codes.
Non-zero exit codes are captured in ExecResult.ExitCode and do NOT cause Exec to return a non-nil error.
type Frontmatter ¶
type Frontmatter struct {
Name string `yaml:"name"`
Version string `yaml:"version"`
Description string `yaml:"description"`
Exec string `yaml:"exec"`
Schema string `yaml:"schema"`
Requires []string `yaml:"requires"`
Timeout string `yaml:"timeout"` // e.g. "5m"
}
Frontmatter holds the YAML front-matter fields parsed from a SKILL.md file. The front-matter block is optional; callers receive a zero-value struct when no front-matter is present.
func ParseFrontmatter ¶
func ParseFrontmatter(data []byte) (Frontmatter, string, string)
ParseFrontmatter extracts YAML front-matter from raw SKILL.md bytes. It also pulls a title and description from the first Markdown heading and leading paragraph, used as fallbacks when the YAML block is absent or incomplete.
Returns: (frontmatter, title, firstParagraph).
type Record ¶
type Record struct {
Name string `json:"name"`
Version string `json:"version"`
Tier int `json:"tier"`
Description string `json:"description"`
Exec *string `json:"exec"` // null for tier-0/1
Schema *string `json:"schema"` // null unless tier-3
Path string `json:"path"`
Requires []string `json:"requires"`
Gated bool `json:"gated,omitempty"` // true when capability-filtered
}
Record is the canonical skill descriptor used by both surfaces. Its JSON shape is the contract returned by `cog skill list --json` and GET /v1/skills.
func Discover ¶
Discover walks dirs in order and returns a deduplicated list of Records. Later directories in the slice override earlier ones for skills with the same name (workspace-level skills win over user-level skills when the caller passes user-level dirs first).
Non-existent directories are silently skipped; other I/O errors are returned.
func FindByName ¶
FindByName looks up a single skill by name across dirs. Returns an error when the skill is not found.
func LoadRecord ¶
LoadRecord reads a skill directory and returns a populated Record, or an error if the directory does not contain a valid SKILL.md.
Source Files