13. Skills can provide Workflow Templates as installed practices

Copy Markdown View Source

Date: 2026-06-04 Status: Accepted Implementation status: Implemented

Context

ADR 0010 defines Skills as progressively disclosed instruction packages with durable per-Turn activations. ADR 0011 defines Subagents as supervised child Sessions. ADR 0012 defines Workflows as deterministic structural orchestration over those Subagents.

The missing relationship is how a reusable agent practice becomes executable without collapsing the concepts together. A Skill can teach judgment, priors, terminology, examples, and failure modes. A Workflow can run an explicit dependency graph. A Tool or script can perform deterministic operations. Treating any one of those as the whole system creates bad coupling:

  • a Skill that directly mutates files on activation violates ADR 0010;
  • a Workflow that relies only on prose loses ADR 0012's structural edge guarantees;
  • a script that secretly encodes orchestration becomes an unlogged second runtime;
  • a Subagent role that tries to embody a whole practice pollutes prompts and makes reuse hard to audit.

The useful pattern from the hybrid Claude Code orchestrator is not its JS Workflow runtime. It is the split between an installed practice and an executable shape: the practice says how to reason, what evidence matters, and which failure modes are known; the runtime executes a bounded graph.

Decision

Pixir treats a Workflow Template as a reusable, parameterized Workflow shape that may be supplied by a Skill or by Pixir itself.

A Skill may include Workflow Templates as progressively disclosed resources, usually under a supporting path such as workflows/<name>.json. They are not listed eagerly by skills_list; the model first discovers the Skill by bounded metadata, loads the Skill or referenced supporting file through skill_view, and then asks run_workflow to instantiate the referenced template. A template can define:

  • optional schema version, defaulting to 1;
  • required and optional parameters;
  • suggested Agent roles for steps;
  • step dependency edges;
  • read/write posture defaults;
  • expected Checkpoint Bundle shape;
  • verification or review conventions;
  • known failure modes and safe next actions.

A Workflow Template is not running state, not a Tool, and not a Skill Activation by itself. It becomes a concrete Workflow only when a Session instantiates it with task-specific arguments and executes it through Pixir's normal permissioned Tool surface, initially run_workflow.

Skill Activation remains per ADR 0010:

  • loading SKILL.md records the activation snapshot;
  • reading a template or supporting reference is progressive disclosure, not activation;
  • scripts shipped with a Skill are never auto-run merely because the Skill was loaded;
  • executing a script remains an ordinary Tool operation subject to permissions, dry-run, structured errors, and workspace confinement.

The runtime ownership stays unchanged:

  • Skills teach the practice.
  • Workflow Templates describe reusable orchestration shapes.
  • Workflows execute structural graphs.
  • Subagents do bounded stochastic work.
  • Tools and scripts perform deterministic operations.
  • The Log remains the source of truth for durable facts.

Consequences

  • Pixir can package practices such as visual QA, benchmark execution, high-rigor review, release preparation, and multi-agent implementation as reusable Skill-backed Workflow Templates instead of one-off prompts.
  • The same practice can be used from terminal, ACP, or T3 Code because execution still goes through Pixir's Workflow and Tool surfaces.
  • Skills become more powerful without becoming hidden executors.
  • Workflow Template discoverability should stay Skill-shaped: bounded Skill metadata in skills_list, supporting file reads via skill_view, and validation at run_workflow instantiation time. This keeps the prompt and tool output compact while preserving ADR 0005 dry-run and structured-error behavior.
  • Unsupported template versions fail during instantiation as structured :invalid_args; they do not run partially.
  • If a future implementation persists template instantiations or workflow-level decisions, that is a deliberate Event/Log schema change under ADR 0004.

Non-goals

  • Do not import Claude Code's Workflow({scriptPath, args}) mechanics.
  • Do not auto-run templates on Skill Activation.
  • Do not make Skills sticky Session state.
  • Do not replace run_workflow with a second orchestration runtime.

Verification Direction

The first implementation should be verifiable without network calls:

mix test test/pixir/skills_test.exs test/pixir/workflows_test.exs
mix pixir.smoke.workflows --dry-run --json

It should prove that a template can be discovered through the Skill's progressive disclosure path, instantiated into a normal Workflow spec, dry-run, and executed through the existing Pixir.Workflows path without bypassing permissions or Workspace confinement.

References

  • ADR 0004: unified Event envelope and canonical vs ephemeral events.
  • ADR 0005: tool ergonomics, dry-run, self-describing help, structured errors.
  • ADR 0010: Agent Skills use progressive disclosure with durable activations.
  • ADR 0011: BEAM-native Subagents as supervised child Sessions.
  • ADR 0012: structural Workflows over Subagents.