Pixir.Skills (pixir v0.1.0)

Copy Markdown View Source

Progressive-disclosure Skill discovery and loading (ADR 0010).

Skills are instruction packages rooted outside the ordinary Workspace file tool authority. This module is the narrow Skills surface: list bounded metadata first, then load a selected SKILL.md or supporting file from registered roots.

Summary

Types

skill()
workflow_template()

Functions

activation_data(skill, content, activated_by)

Build durable activation data for a loaded main SKILL.md.

activations_for_prompt(workspace, prompt, opts \\ [])

Resolve explicit user-invoked Skills to activation data.

discover(workspace \\ File.cwd!(), opts \\ [])

Discover registered Skills for a workspace, resolving duplicate names by scope.

get(name, workspace \\ File.cwd!(), opts \\ [])

Resolve a Skill name from the selected discovery set.

index_hash(workspace \\ File.cwd!(), opts \\ [])

Stable hash for the bounded Skills index rendered into a Turn prompt.

instantiate_workflow_template(ref, args, workspace \\ File.cwd!(), opts \\ [])

Instantiate a Skill Workflow Template into a concrete Workflow spec.

invoked_names(text)

Find explicit $skill-name and leading /skill-name mentions in user text.

main_file?(path)

Whether a viewed path is the Skill's main instruction file.

render_activation(data)

Render a durable activation as a Provider input fragment.

render_index(workspace \\ File.cwd!(), opts \\ [])

Render a compact Skills index for the Turn system prompt.

view(name, rel_path \\ "SKILL.md", workspace \\ File.cwd!(), opts \\ [])

Read SKILL.md or a supporting file from a registered Skill.

workflow_template(ref, workspace \\ File.cwd!(), opts \\ [])

Resolve a Workflow Template by skill/template, skill:template, or unique id.

workflow_templates(workspace \\ File.cwd!(), opts \\ [])

Discover Workflow Templates shipped by registered Skills.

Types

skill()

@type skill() :: %{
  :name => String.t(),
  :description => String.t(),
  :scope => String.t(),
  :source => String.t(),
  :root => String.t(),
  :dir => String.t(),
  :path => String.t(),
  :short_path => String.t(),
  optional(:disable_model_invocation) => boolean()
}

workflow_template()

@type workflow_template() :: %{
  id: String.t(),
  template_id: String.t(),
  version: pos_integer(),
  name: String.t(),
  description: String.t(),
  skill: String.t(),
  scope: String.t(),
  source: String.t(),
  path: String.t(),
  short_path: String.t(),
  parameters: map(),
  workflow: map()
}

Functions

activation_data(skill, content, activated_by)

@spec activation_data(skill(), String.t(), String.t()) :: map()

Build durable activation data for a loaded main SKILL.md.

activations_for_prompt(workspace, prompt, opts \\ [])

@spec activations_for_prompt(String.t(), String.t(), keyword()) :: [map()]

Resolve explicit user-invoked Skills to activation data.

discover(workspace \\ File.cwd!(), opts \\ [])

@spec discover(
  String.t(),
  keyword()
) :: {:ok, %{skills: [skill()], warnings: [map()]}}

Discover registered Skills for a workspace, resolving duplicate names by scope.

get(name, workspace \\ File.cwd!(), opts \\ [])

@spec get(String.t(), String.t(), keyword()) :: {:ok, skill()} | {:error, map()}

Resolve a Skill name from the selected discovery set.

index_hash(workspace \\ File.cwd!(), opts \\ [])

@spec index_hash(
  String.t(),
  keyword()
) :: String.t()

Stable hash for the bounded Skills index rendered into a Turn prompt.

This is intentionally a deterministic pure helper returning String.t() directly. It unwraps Pixir.Provider.Cache.stable_hash/1 because index rendering already controls the input shape. Fallible public operations keep the usual {:ok, term} | {:error, term} shape.

instantiate_workflow_template(ref, args, workspace \\ File.cwd!(), opts \\ [])

@spec instantiate_workflow_template(String.t(), map(), String.t(), keyword()) ::
  {:ok, %{template: map(), workflow: map()}} | {:error, map()}

Instantiate a Skill Workflow Template into a concrete Workflow spec.

The instantiated workflow is still executed by Pixir.Workflows; this function only validates template arguments and substitutes placeholders in the template resource.

invoked_names(text)

@spec invoked_names(String.t()) :: [String.t()]

Find explicit $skill-name and leading /skill-name mentions in user text.

main_file?(path)

@spec main_file?(String.t()) :: boolean()

Whether a viewed path is the Skill's main instruction file.

render_activation(data)

@spec render_activation(map()) :: String.t()

Render a durable activation as a Provider input fragment.

render_index(workspace \\ File.cwd!(), opts \\ [])

@spec render_index(
  String.t(),
  keyword()
) :: String.t()

Render a compact Skills index for the Turn system prompt.

view(name, rel_path \\ "SKILL.md", workspace \\ File.cwd!(), opts \\ [])

@spec view(String.t(), String.t(), String.t(), keyword()) ::
  {:ok,
   %{
     skill: skill(),
     path: String.t(),
     abs_path: String.t(),
     content: String.t()
   }}
  | {:error, map()}

Read SKILL.md or a supporting file from a registered Skill.

workflow_template(ref, workspace \\ File.cwd!(), opts \\ [])

@spec workflow_template(String.t(), String.t(), keyword()) ::
  {:ok, workflow_template()} | {:error, map()}

Resolve a Workflow Template by skill/template, skill:template, or unique id.

workflow_templates(workspace \\ File.cwd!(), opts \\ [])

@spec workflow_templates(
  String.t(),
  keyword()
) :: {:ok, %{templates: [workflow_template()], warnings: [map()]}}

Discover Workflow Templates shipped by registered Skills.

Templates live under workflows/*.json inside a Skill. Discovery reads only template metadata/resources and never executes Skill scripts or records Skill Activations.