Code-First Skill Orchestration

You write a long system prompt. It has conditional logic scattered through prose paragraphs: "if the issue looks well-specified, do a lean plan; if it's missing context, do a full analysis first; if it has acceptance criteria but no file paths..."

The LLM follows it for a while. Then it starts drifting. It skips a condition. It bleeds instructions from one branch into another. It "interprets" a step instead of following it. You add more detail to the prompt. It gets worse, not better, because now there's more to ignore.

The behavior is untestable. You can't assert that the LLM will always take the right branch. You can't reproduce a failure. You can't even see which branch it took without reading the full output and reasoning backward.

The problem isn't the LLM's capability. It's that branching logic expressed in prose is a terrible control flow mechanism. I rewrote the same system prompt three times before realizing the fix wasn't better wording. It was moving the branching out of prose entirely.

SKILL.md files that orchestrate deterministic tools. The skill calls tools via bash, reads their JSON output, and tells the LLM what to do next. Decision-making stays in the tools. Sequencing stays in the skill. The LLM just executes.

Skills are markdown instructions the LLM follows step by step. The format comes from the open Agent Skills standard: a file with phases, steps, and tool invocations that the LLM reads and executes.

What makes a skill code-first is where the decisions live. In a typical skill, the LLM reads the instructions and figures out what to do. In a code-first skill, the decisions are already made by the tools the skill calls. The skill's job is sequencing, not thinking.

The skill defines the workflow. The tools do the work. The LLM follows the workflow and applies judgment only where the skill explicitly asks for it.

How the skill consumes tool output depends on what the tool returns. Because every tool describes its own output shape (see Self-Describing Tools), the skill reads documented fields instead of guessing at them. The three levels mirror the tool spectrum.

The LLM has discretion. It reads the raw signals, applies judgment, and picks an approach. This is useful when the situation genuinely needs interpretation, when the data is one signal among many.

The classification is deterministic (the tool decided based on signal scoring). The procedures live in the skill. The LLM reads the complexity and follows the matching section. This works well when the number of routes is small and the procedures are short enough to fit in a skill file.

Zero LLM branching. The tool decided everything: the complexity level, the planning procedure, the specific steps. The LLM is a pure executor. The skill is a thin shell.

This is the pattern I reach for most. The tool is a prompt factory: it generates the exact instructions the LLM should follow, based on deterministic analysis. If something breaks, you trace it to a line of code, not to a prompt that "usually works."

Real workflows involve multiple tools in sequence. Each tool's output feeds the next step.

Each tool is deterministic. The skill sequences them. The LLM carries context between phases but doesn't make routing decisions.

Tools can also serve as guardrails within a workflow.

Loop guards prevent infinite retry cycles:

The guard is deterministic. After 3 attempts, it returns { "halt": true }. The LLM doesn't decide whether to keep trying.

Scope guards prevent the agent from drifting into unrelated files:

The tool compares modified files against the expected scope from the issue analysis. If the agent touched files outside that scope, the guard catches it. No judgment call, just a set comparison.

Having the whole workflow in one readable file is a big win. You can trace the execution path, verify each tool's output independently, and onboard someone new by pointing them at a markdown file instead of explaining a prompt chain.

The cost is maintenance: each workflow needs a SKILL.md that stays in sync with its tools. And the pattern depends on the LLM actually following the instructions. Strong models (Claude, GPT-4) do this well. Smaller models drift. That's a feature choice, not a bug: you're trading flexibility for reliability on purpose.

Deterministic Tools covers the producer side: how to build the CLI tools that skills consume.