A skill is not a long prompt

A prompt describes one request. A skill describes how a class of requests is handled repeatedly, verifiably and safely under defined conditions.

When a language model solves a task well once, the obvious move is to save the prompt. Every exception adds more text: format rules, sources, examples, tool hints, error handling and special cases. The result becomes a universal prompt expected to know everything and govern every situation.

That appears thorough but is architecturally weak. Long instructions compete with user data for context. Important rules disappear among details. Stale facts remain embedded. Global project text influences tasks it was never meant to constrain. A useful guide becomes hidden technical debt.

A skill addresses this through separation, not simply more text.

Prompts, project rules, resources, tools and skills differ

A prompt states current intent. A project rule defines cross-cutting conventions such as folder structure, quality level or prohibited actions. A resource supplies knowledge or data. A tool performs a function. A skill combines these elements into a reusable procedure.

This distinction prevents overload. A price list belongs in an updateable data source, not permanently in the core instruction. A parser belongs in a tested script, not as pseudocode inside a prompt. Brand colours belong in an asset or style reference. The user request stays small because components are loaded deliberately.

The open Agent Skills specification makes this concrete: a skill is a folder with a SKILL.md, optionally accompanied by scripts/, references/ and assets/. The file format is only the container. Quality comes from the contract formed by its contents.

The description is a router

Before using a skill, an agent must recognise that it applies. Name and description are therefore not marketing copy; they form the routing interface. A good description says what the skill solves, when to activate it and when not to.

Descriptions that are too broad cause false activation. „Helps with documents“ competes with every document skill. Definitions that are too narrow miss variants. An observable boundary is better: „Creates and revises multilingual DOCX worksheets, renders every page and checks layout and accessibility; not for spreadsheets or presentations.“

Routing needs tests: positive requests, difficult boundaries and explicit negatives. If two skills claim the same request, the system needs priority rules, composition or a clarifying question. Silent arbitrary selection is not robust architecture.

Progressive disclosure protects context

An agent need not load every instruction, reference and script for every installed skill at startup. The Agent Skills specification recommends three levels: metadata for discovery, core instructions on activation and supporting files only as required.

Progressive disclosure is more than token economy. It reduces interference. A legal review workflow does not influence image work unless relevant. A rarely needed API reference does not displace current user input. Detail remains available when the task actually needs it.

Core instructions should therefore navigate rather than duplicate a complete manual. They define sequence, selection rules, quality gates and references. Long tables, domain guidance, templates and example corpora stay separate. Each reference remains focused and directly reachable.

A skill needs a work contract

A production skill answers at least nine questions:

1 · Trigger: Which intent and inputs activate it?

2 · Preconditions: Which files, rights, programs or data must exist?

3 · Procedure: Which steps run in what order?

4 · Decisions: Where may the model judge, and where do deterministic rules apply?

5 · Tools: Which functions are allowed, with what scope?

6 · Output: Which files, fields, formats and qualities are expected?

7 · Verification: Which tests must pass before completion?

8 · Failure: When does it retry, roll back, escalate or stop?

9 · Boundaries: What must it explicitly never do?

This contract turns tacit experience into testable behaviour. „Create a good document“ becomes file type, language, length, source rules, rendering checks, permitted tools and acceptance criteria. Flexibility remains where several answers are useful; safety boundaries and output schema remain stable.

Separate procedural knowledge from changing facts

Skills mainly contain procedural knowledge: how work is done. Model lists, prices, laws, benchmarks and product features change continuously. If they are hard-coded into core instructions, the skill ages without a visible signal.

Volatile facts belong in dated references, databases or verifiable retrieval. Every record needs source, date, scope and update ownership. The skill describes how data are selected and checked; it does not pretend stored knowledge stays current forever.

This matters for model routing. „Use model X for analysis and model Y for extraction“ may soon be obsolete. A capability matrix is more durable: required context, tool support, latency, privacy, cost and measured output quality. Routing uses current evaluated data and falls back safely when evidence is insufficient.

Scripts carry determinism

Not every step should remain natural language. Validating filenames and schemas, calculating hashes, setting table widths and running tests are deterministic operations. A script can perform them reproducibly and return explicit errors.

The model determines when a step is needed and interprets its result. The script guarantees the mechanical operation. This division reduces fabrication and makes repeated runs comparable.

Scripts still require engineering: documented dependencies, bounded inputs, useful errors, idempotence, tests and safe defaults. A skill is not permission to execute arbitrary code. Executable files increase attack surface and must be reviewed as software.