A Systems Design for Stable Cross-Model Agent Skills

Skills that behave inconsistently across models, agent frameworks, and machines are a common agent-engineering problem, and they are easy to misdiagnose. On the surface it looks like “we switched to a weaker model.” In practice, skill text often encodes undeclared assumptions: a particular tool-call format, working-directory and path-separator conventions, commands and runtimes that are already installed, or output that must follow a hard-to-parse natural-language layout. Strong models can sometimes improvise around those assumptions. Weaker models, or tighter local models, get stuck on steps unrelated to the actual goal. Even when a strong model recovers, it still burns extra context, tool round-trips, and latency.

Treating this as “the prompt was not detailed enough” does not scale to distribution. A more robust view is: a skill is a distributable, self-contained knowledge pack that improves an agent’s ability to complete a class of tasks at the prompt layer, without changing model weights. Models are heterogeneous processors with uneven capability. Agent frameworks and their tool layers are the runtime. Stability is therefore a systems problem, not a matter of writing style in a single conversation.

What skills are solving

Compared with fine-tuning, skills are not bound to one set of weights, are cheap to compose, and are well suited to capturing domain workflows, tool usage, and delivery formats for reuse. Public skill samples fall into three rough categories, each with different sensitivity to environment.

Tool-reference skills are about half. They teach how to call a specific API, command, or parameter combination—essentially usage notes loaded into context. They fail most easily: a small difference in interface names, auth, return fields, or error codes can send later steps down the wrong path.

Process-guidance skills are about 30%. They specify stepwise flows and reasoning strategy, for example collapsing troubleshooting into reproduce, locate, fix, and verify. Models usually understand the steps, but if a step depends on an undeclared log location, test command, or permission, the flow breaks in the middle and shows up as repeated retries.

Content-generation skills are about 20%. They ask for documents, code, or reports in a particular format. Quality depends more on the model’s generation ability. Even when generation is adequate, missing machine-readable structure still causes downstream parse failures.

Samples also show that most skills have an explicit process structure—numbered steps and conditionals—and most embed command or call fragments. Skills already resemble programs, yet they are still loosely stitched in natural language, without compile-time checks or runtime contracts. Download distribution is highly long-tailed: only a few head skills are used repeatedly. Building stability into the skill itself is cheaper than asking every consumer to hand-edit prompts.

Where instability comes from

Cross-model instability is usually an unprobed capability boundary. The skill assumes the model will reliably multi-step plan, strictly follow formats, or correctly escape special characters. Strong models fill the gaps; weaker models fail on branching, counting, or formatting, so the same instructions “work” or “don’t work.”

Cross-runtime instability is usually undeclared tool and context conventions. Frameworks differ in tool descriptions, working-directory injection, file I/O, and error return. If a skill hard-codes one framework’s habits into its steps, formats collapse in another environment, or explanatory text is treated as executable output.

Cross-machine instability is usually unisolated dependencies and paths. Interpreter versions, system libraries, credentials, and relative paths that exist on the author’s machine do not exist on another. The model then loops through error, guessed install, and error again—spending tool calls without making task progress.

The common thread: failure happens off the critical path. The model can often do the actual task; it gets stuck because the skill never stated checkable conditions for required capability, required environment, and what “done” means.

Reorganizing skills like a compiler and a VM

When a compiler faces many source languages and many target machines, it does not bind source directly to one processor. It parses, lowers through an intermediate representation, applies target-specific degradation, and checks at runtime. Skills can use the same layering. The “instructions” remain mostly natural language, plus a little structured metadata.

The front end turns the skill body into explicit structure instead of a long essay. At minimum, separate: task goal, preconditions, inputs and outputs, steps, tool requirements, environment dependencies, and stop conditions on failure. Numbered steps and branches should not be buried in paragraphs. Embedded commands should be templates, not scripts assumed to run on any machine. Placeholders, working directory, and expected exit semantics need to be marked separately.

The intermediate representation strips framework dialect. Steps describe the action and the success criterion, not how a button or field looks in one product. Tool needs are expressed as capabilities—“read a specified text file,” “run a read-only check in a restricted directory”—not a vendor-specific call name. The same IR can then map onto each runtime’s tool implementations.

The back end degrades for the current model and environment. If the model is weak at long implicit planning, expand branches into shorter checkpoints. If a tool is missing, switch to a read-only alternative or fail explicitly with the gap named, rather than letting the model invent installs of unknown components. Degradation policy should be written into the skill so the runtime does not invent a new flow.

The runtime validates instead of trusting a final blob of natural language. Each step accepts only the previous step’s structured result after checks. Format mismatch, path escape, missing dependency, or repeated errors of the same class should stop and return diagnostic information. Weak models then do not retry forever on bad format; strong models do not spend tokens guessing the author’s subtext.

Contracts to put in the skill

A framework-agnostic header can state the contract rather than advertise capability. For example:

Goal: locate failing cases in a given repository and produce a minimal fix plus verification commands
Preconditions: can read files and run read-only checks; write scope is the task directory only
Inputs: failure symptoms, relevant paths, directories allowed to change
Environment: required runtimes and version ranges; if missing, stop and list the gaps
Outputs: structured result with conclusion, changed files, verification method, open issues
Forbidden: guessing and installing system-level dependencies; accessing paths outside the task directory; faking a passed verification

Write steps as checkpoints, not as click sequences for one UI:

1. Reproduce: use only commands or test entry points given in the input; record exit info and key logs; do not change code.
2. Locate: read only files directly related to the failure; if information is insufficient, list what is missing and stop.
3. Fix: changes limited to allowed directories; explain how each change maps to the failure cause.
4. Verify: repeat the same entry point as step 1; do not mark verified unless it was actually run.

Prefer stable output fields so any model can fill them and any environment can parse them. Ordinary names are enough: conclusion, evidence, changes, verification, risks. Do not rely on heading levels, table lines, or phrases like “as shown below” to carry structure—those are the first things lost in rewriting and truncation.

Probe capability before a long flow

Before a multi-step task, use a small probe for three things: whether the model can follow the given fields; whether the environment exposes the tools the skill declared; whether declared dependencies actually exist. Probes should be short, decidable, and side-effect free. Load the full process only after they pass; otherwise degrade or stop.

This moves failure earlier. Previously you discovered a bad assumption only after format collapse or repeated command errors in the second half. Now the first step can distinguish “this model is a poor fit for the flow,” “the environment lacks tools,” and “dependencies are unmet.” Users then know whether to change how they run, or to complete the environment, instead of rewriting the same prompt.

Probes must not become fingerprinting or restriction bypass. They only answer whether declared preconditions hold. They should not collect system information unrelated to the task, attempt privilege escalation, or scan paths outside the task scope.

Dependencies, paths, and idempotency

Cross-machine stability means turning the author’s accidental machine state into a declared minimum set. Write dependencies as version ranges and purposes, not “install whatever first.” Separate read-only steps from writes; constrain writes to the task directory. Relative paths are relative to the task root, not the executor’s current directory. Steps that need network or credentials should be labeled; if credentials are missing, stop—do not pretend a call succeeded with placeholders.

Steps should be as idempotent as possible: repeating reproduce and verify should not create new damage. Fix steps should state what already changed, so retries do not stack on a half-finished previous attempt. When errors are returned to the model, truncate to the parts relevant to the criterion so unrelated logs do not fill context and trigger random repairs.

How to evaluate whether it is actually more stable

Do not judge from one successful demo on one strong model. Cover at least models of different capability tiers, two or more tool-integration styles, and a “clean” environment. Metrics can be simple: whether the task completed, whether output parses under fixed rules, tool-call count, retries caused by missing dependencies, and whether out-of-scope paths or unverified “success” claims appeared. Compare failure types of the same skill before and after contracts, rather than inventing a single speed or accuracy number.

If failures cluster on format, strengthen output fields and stepwise validation. If they cluster on tool names, the IR still leaks one environment’s dialect. If they cluster on dependencies, the environment contract was not checked at the start. Classify, then change the skill—more effective than piling on more prompt text.

Trade-offs when shipping

Not every skill needs a full VM-style pipeline. One-off, tool-free, environment-free short notes can stay simple. Once a skill is distributed, embeds commands, or is reused across frameworks, prioritize preconditions, capabilities, dependencies, and completion criteria. Process can still be written in readable natural language; the parts machines must check should stay small and stable.

The value of a skill is capturing how a class of tasks is done as composable knowledge, not freezing one successful conversation into a script that only works on the author’s machine. Compiler-and-VM layering turns implicit assumptions into explicit contracts: degrade when model capability is insufficient, fail early when the environment does not match, and do not advance when output is invalid. Stability then stops depending on one-off improvisation and becomes an engineering property you can check, migrate, and revise.