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.

Runtime controls tool permissions

A skill may declare the tools it needs, but it cannot grant itself authority. The host decides which functions exist, what data they reach and when human confirmation is required.

MCP separates resources, prompts and executable tools. Its tool guidance includes input validation, access controls, rate limiting, output validation, timeouts and audit logs. Sensitive actions should be visible and confirmable. These controls belong to runtime enforcement, not only a friendly sentence in skill instructions.

Use least privilege. A research skill needs read access, not deletion. A document skill needs a bounded output folder, not the whole filesystem. A deployment skill can produce a preview before receiving publication authority. The blast radius remains limited even when a model, prompt or source is manipulated.

Skills are software-supply-chain artifacts

Third-party skills may contain instructions, scripts and dependencies. A harmless description can differ from actual behaviour. References can contain indirect prompt injection; scripts can transmit data or modify files. Installation is a trust decision.

Review provenance, licence, contents, network access, dependencies, tool requirements and history before adoption. Pin versions; hashes or signed releases can support integrity. Updates do not flow directly into production. Critical skills need an owner, review requirement and rollback path.

OWASP describes excessive agency as risk arising when LLM systems receive too much functionality, permission or autonomy. A well-written skill reduces this only when runtime capability is genuinely constrained. Good prose is not a sandbox.

Evaluation, not length, creates quality

A skill is evaluated through tasks. A test set includes ordinary cases, boundaries, missing input, conflicting sources, invalid formats, tool failure and attack attempts. Measure activation, result quality, rule adherence, tool selection, cost, latency and safe failure.

Separate layers. Routing evaluation tests whether the correct skill activates. Process evaluation checks sequence and tool use. Artifact evaluation checks output. Security evaluation probes permission boundaries and manipulated inputs. Regression testing ensures a change does not destroy earlier capability.

A long skill can be worse than a short one when priorities are unclear. A short skill can be insufficient when failures are omitted. The question is not line count but how reliably the contracted state is reached under realistic conditions.

Versioning makes learning controlled

Skills change with tools, data and requirements. Each release needs a changelog, compatible runtime, known limitations and linked evaluation results. Major changes run first against saved cases. Previous versions remain reproducible where retention and security permit.

Do not append every incident as another warning sentence. Locate the layer: bad trigger, missing reference, ambiguous rule, broken tool, weak test or wrong permission. Change the smallest appropriate layer. This prevents the core instruction becoming a graveyard of historical exceptions.

A skill is mature when another agent or team can understand, execute, verify and safely reject it. It does not merely preserve one successful prompt. It makes a way of working portable.

Worksheet: Build a skill contract

Choose a recurring task and design its skill in eight steps.

1. Set scope. Define purpose, positive triggers, boundaries and non-goals.

2. Define inputs. Specify required data, formats, rights and validation.

3. Decompose process. Separate model judgement, deterministic scripts and human approval.

4. Organise resources. Move volatile facts, references and assets outside core instructions.

5. Limit tools. Give every step only the minimum function and reach.

6. Write the output contract. Define artifacts, schema, quality and completion state.

7. Build failure paths. Specify retry, stop, rollback, abstention and escalation.

8. Create evaluation. Collect positive, negative, boundary, failure and attack cases.

All materials to download — the topic overview and the worksheet:

Scope: Platforms implement the term "skill" differently. This article uses the open Agent Skills file model as a concrete reference while addressing the general architecture of reusable procedural work modules. A skill guarantees neither model quality nor safe execution; the runtime, permission system and host remain separate control layers.