Intelligence and method are easy to confuse. A capable model can explain a domain, inspect a file, or choose a tool. It does not automatically know how a team reviews a release, which checks are mandatory, or what to do when an input is missing.
That gap is procedural knowledge: not only facts, but the sequence, judgment, examples, constraints, and recovery steps that make work repeatable.
Agent Skills give that knowledge a small, inspectable container. A skill is a directory with a SKILL.md file and, when useful, references, templates, assets, and executable scripts. An agent can discover the skill, load its instructions when relevant, and reach for its deeper material only as the task requires it.
For a small product studio, that distinction matters. The reusable part of the work is often a standard around the product: how public facts are verified, releases are checked, exports are inspected, and privacy boundaries are reviewed. A skill is interesting when it can preserve one of those methods without pretending that every product needs an agent or that every host behaves the same way.
The missing layer was not another model
The ingredients are not new. Teams have long maintained runbooks, prompt libraries, scripts, examples, templates, and internal documentation. Calling a skill “a folder containing prompts and files” is substantially correct.
The change is the operational contract around those ingredients. The Agent Skills specification defines a minimal, readable format: a named directory, a SKILL.md manifest with discovery metadata, and optional supporting files. Anthropic's original description adds the runtime idea: agents see a small catalog, select a relevant skill, and progressively load its contents. OpenAI's Skills API describes the same core unit as a versioned bundle for codifying processes and conventions.
This gives working knowledge a place between a one-off instruction and a custom agent. The model can remain general, the tools narrow, and the method change without retraining either one.
Seven terms, seven responsibilities
Much of the confusion around skills comes from using “agent,” “tool,” and “prompt” as interchangeable labels. They are different layers.
| Layer | The question it answers | Its responsibility |
|---|---|---|
| Prompt | What should happen now? | Supplies the current task, context, or instruction. A prompt may be reused, but it does not by itself define a portable working package. |
| Model | What general capability is available? | Interprets language, reasons over context, and generates decisions or output. Installing a skill does not change its weights. |
| Agent | What should happen next? | Runs a model in a loop and lets it choose steps, tools, and context dynamically. |
| Skill | How do we usually perform this kind of work? | Packages procedure, examples, references, templates, and optional scripts for a focused task. |
| Tool | What action can be invoked? | Exposes a callable operation such as searching, reading a file, running a command, or updating a record. |
| MCP server | How are external capabilities and context exposed? | Uses the Model Context Protocol to offer tools, resources, and prompt templates through a standard connection. |
| Harness | How is the run controlled? | Owns the agent loop, model calls, tool routing, permissions, state, approvals, tracing, validation, and recovery. |
Anthropic's definition of workflows and agents makes one boundary especially useful: a workflow follows paths predetermined in code, while an agent dynamically directs its own process. OpenAI describes the harness as the control plane around that behavior in its Sandbox Agents guide.
MCP is another important boundary. The Model Context Protocol specification standardizes access to tools, resources, and prompts. It can give an agent access to a document system or a database. A skill can teach the agent which sources to consult, in what order, under which constraints, and how to check the result. The connection is not the method.
In one line: a tool gives an agent an action; a skill gives it a method; MCP provides a connection; the harness governs the work.
Progressive disclosure is the core mechanism
A long system prompt can hold extensive guidance, but every task pays the cost of carrying it. It also becomes harder to separate universal rules from situation-specific instructions.
Skills use progressive disclosure instead. At the first level, the agent receives only the name and description of available skills. If a description matches the task, it loads the complete SKILL.md. That file can then point to a form guide, a schema, a canonical example, or a script, each loaded or executed only when needed. Both the Anthropic architecture and OpenAI's Codex guidance document this pattern.
This is context engineering, not model training. Specialized material arrives just in time while unrelated material stays out of active context. Context is still finite: hosts impose budgets, descriptions may be shortened at scale, and agents can follow weak reference paths. Progressive disclosure reduces pressure; it does not remove it.
Put judgment in the model and invariants in code
A skill may include executable scripts. This matters because not every part of agentic work should be generative.
Anthropic's PDF example combines instructions and form-specific references with a Python script that extracts fields deterministically. The model decides what the task requires; ordinary code performs an operation that should not vary from one run to the next. The script can run without placing its entire source or the whole document in model context.
The broader rule is simple: let the model handle interpretation and judgment; let code handle invariants. File validation, sorting, schema checks, format conversion, and exact calculations do not improve because a language model can imitate them. A skill can place probabilistic and deterministic components together without confusing them.
Portability does not mean identical behavior
The shared format is significant. Claude Code follows the Agent Skills open standard, and OpenAI states that its Skills are compatible with it. Instructions can therefore travel as ordinary files instead of being trapped inside one chat or one proprietary builder.
But format portability is not behavioral equivalence.
Claude Code adds features such as invocation controls, subagent execution, and dynamic context injection beyond the core specification. Hosts differ in filesystem access, available tools, permission models, dependency handling, and context management. Models differ in how they interpret the same instruction. A compatible skill can carry its core method across products; it cannot guarantee identical activation, execution, or output.
That distinction should remain visible. “Write once, run everywhere” would overstate what the format provides. “Inspect once, adapt deliberately” is closer to the current reality.
Two cases worth studying
The PDF skill is one concrete case: a general model already understands PDF content, while the skill adds the procedural and executable material needed to manipulate forms reliably. It demonstrates specialization without claiming that the underlying model has learned new weights.
OpenAI describes another case in its Agents SDK repository maintenance. Focused skills run the required formatting, linting, type checks, and tests after code changes; inspect documentation drift before editing; keep package-manager pins aligned; and prepare consistent pull-request summaries. Repository instructions specify when those skills are mandatory.
These deliberately unglamorous examples preserve operational decisions that would otherwise be rediscovered, forgotten, or applied unevenly. The skill is not an autonomous maintainer. It is a reviewable method available to a maintainer and an agent.
A skill can also make a mistake reusable
Packaging a method does not prove that the method is good. A vague description can fail to trigger. An overly broad one can activate on the wrong task. Conflicting skills can pull an agent in different directions. A long or deeply nested skill can hide the instruction that actually matters.
There is also a trust boundary. Skills may contain dependencies, network destinations, and executable code. Anthropic warns that a malicious skill can introduce vulnerabilities, exfiltrate data, or direct unintended actions. An unknown skill deserves the same suspicion as an unfamiliar script.
Consequential controls do not belong only in prose. Least-privilege credentials, sandboxing, validation, approval gates, audit logs, and recovery belong in the harness. A skill may request approval; the harness should prevent the update until approval exists.
And many tasks do not need a skill at all. A short prompt is enough for a one-off answer. A deterministic program is better for a fixed transformation. A predefined workflow is often preferable when predictability matters more than flexible planning. The architecture choice still comes first: the smallest sufficient mechanism is a sound default.
Skills should be evaluated like software
One pleasing result does not validate a skill. Compare representative tasks with and without it, across ordinary inputs and edge cases.
OpenAI's evaluation guidance separates useful checks into outcomes, process, style, and efficiency. Did the task complete? Did the agent invoke the right procedure and commands? Did the artifact follow the required conventions? Did it avoid unnecessary loops and token use? Those questions turn a skill from a persuasive prompt into something that can regress, be tested, and improve.
For any skill we would trust at BorealBit, the standard should be modest and strict:
- one focused job with clear activation boundaries;
- references drawn from the real process, not generic filler;
- deterministic checks wherever an invariant exists;
- the minimum tools and permissions necessary;
- human approval before consequential external actions;
- representative evaluations with and without the skill;
- ordinary files that a person can inspect and review.
That is a design position, not a claim that every process has already been encoded or proven. The useful work begins with observing a repeated task, finding its actual failure modes, and testing whether a skill improves them.
The method becomes an artifact
Skills should not make an agent appear more capable than it is. They should make its method easier to inspect, test, share, and revise.
Models will change. Agent products will add different controls. Tool protocols will evolve. A clear method—kept in readable files, paired with deterministic checks, and evaluated against real tasks—can move more deliberately.
The breakthrough is not that an agent suddenly knows more. It is that the knowledge of how work should be done can become an artifact of the work itself.