When Claude Skills Need Determinism, Use Skillflows

Natural‑Language Power and Its Cost

Claude Skills stores a SKILL.md file written in natural language that the model reads before acting. The file lists what to notice, which tool to use, and which conventions to follow, but it does not prescribe an exact execution order. The model therefore composes a path at runtime, allowing a single SKILL.md to handle thousands of variations.

This flexibility comes at the price of nondeterminism: the same input can follow different routes, which is problematic for auditing, caching, or compliance requirements.

Skillflows: A Declarative Task Graph

To address nondeterminism, a companion skillflow.json can be placed alongside SKILL.md. The JSON describes nodes (tools, LLM calls, routers) and their connections, forming an executable graph that the engine follows exactly each run.

{
  "name":"fill-pdf-form",
  "inputs":{"pdf_path":"string","data":"object"},
  "nodes":[
    {"id":"extract","type":"tool","tool":"pdf.read_fields","args":{"path":"{{inputs.pdf_path}}"},"out":"fields"},
    {"id":"map","type":"llm","model":"claude-...","prompt":"Map {{inputs.data}} onto {{extract.fields}} as JSON","output_schema":{},"out":"mapping"},
    {"id":"check","type":"router","expr":"mapping.complete","true":"fill","false":"ask_human"},
    {"id":"fill","type":"tool","tool":"pdf.fill","out":"result"}
  ]
}

Unlike the advisory SKILL.md, the skillflow graph is executable and guarantees the same path for identical inputs.

Benefits of Determinism

Deterministic execution : identical inputs always follow the same node sequence, simplifying debugging and fixing.

Auditability : each node’s input, transformation, and output are logged, satisfying regulatory or customer‑dispute investigations.

Cost reduction : tool nodes incur zero LLM tokens, LLM nodes receive narrow prompts, routing can use cheap models (e.g., Haiku), and the fixed path eliminates token‑heavy reasoning.

Consistency for users : repeated requests produce identical results, crucial for compliance checks and fair treatment.

Trade‑offs and Failure Modes

Skillflows sacrifice the expressive freedom of natural language. While natural language can encode any graph, the declarative graph adds enforcement. Over‑constraining every decision can turn a flexible agent into a brittle system that silently follows the wrong branch when input shapes differ or unexpected edge cases appear.

Silent failures occur when the graph’s topology does not match reality, e.g., wrong field type, slightly different data shape, or missing branches for unforeseen cases. A natural‑language agent might adapt, but a static graph cannot.

Maintenance Overhead

SKILL.md

is cheap to edit; a skillflow is code that must be written, tested, version‑controlled, and kept in sync with tool or API changes. For many skills the added cost does not pay off.

When to Use Skillflows

Skillflows shine for high‑frequency, mechanical, repeatable workflows that require:

deterministic outcomes,

full audit trails,

significant caching savings,

parallel execution, and

the need to treat loss of adaptive intelligence as a safety feature.

Typical candidates include tax‑form filling, fixed‑pipeline invoice processing, compliance checks needing audit logs, and scheduled data synchronizations.

Complementary Use, Not Replacement

The recommended pattern is to keep SKILL.md as the default description and introduce a skillflow only for those slices that have solidified into a deterministic pipeline. Within a single skill, use prose for judgment steps and a graph for the mechanical steps.

Agent Modification of Skillflows

Agents can adapt within the predefined graph (e.g., retry OCR on extraction failure) but should not freely amend the graph structure, as that would erase the enforcement purpose. Safe amendments involve predefined “holes” in the graph that agents can fill with sub‑plans while preserving the overall skeleton.

Decision Guideline

If a human expert would write a runbook expecting precise execution, use a graph; if the expert would write free‑form guidance, keep prose.

Framework Determines Product

Viewing Skillflows as a new node type rather than a replacement for Skills avoids the trap of forcing a rigid framework onto all tasks. The framework choice shapes whether Skillflows evolve into a useful defensive tool or a counterproductive cage.