Watch the short video companion
Read or comment on the complete paper: English edition | French edition
I spent a long time building AI workflows before admitting something painfully simple: a folder full of instructions is not automatically a tool.
A SKILL.md
can be brilliant. An AGENTS.md
can save a repository. A plugin manifest can package a clean idea. None of them, by themselves, can validate a file, inspect live state, call a service, reject malformed input, or prove that an action happened.
That distinction matters because agent ecosystems are expanding faster than their vocabulary. We use skill, plugin, tool, hook, resource, and MCP server as if they were interchangeable. They are not.
My rule after this research is direct:
A skill should teach the agent how to use a capability. A real plugin should make that capability available. When the task requires action, the plugin needs a motor.
This article became a case study inside my own workshop.
I inspected a memory plugin that was not fake. It already had executable tools, a server surface, tests, and useful routes. Yet its activation instructions pushed Codex toward selecting and dispatching a large agent job before establishing whether memory was needed at all.
Nothing was syntactically broken. The architecture was simply asking activation to do too much.
Activating a plugin should make capabilities available. It should not behave like a dispatch order.
That difference sounds small until the workspace grows. One skill becomes ten. Every correction becomes a permanent rule. Every successful workflow becomes another Markdown file. Soon the model spends the beginning of each task reading the workshop labels instead of touching the work.
I call this context debt.
The debt appears as hesitation, instruction conflicts, stale rules, broad triggers, and repeated searching. The model is not necessarily weaker. We may have consumed its useful attention before it reached the problem.
Instruction is language. Instrumentation is contact with reality.
This does not make instructions weak. Instructions carry intent, style, constraints, and professional standards. A focused skill can prevent expensive wandering.
The problem begins when a guide impersonates an instrument.
If the system cannot run the operation, inspect its result, fail honestly, and show evidence, the skill may still be a useful manual. It is not the motor.
The cleanest architecture I can defend today looks like this:
A skill is focused guidance. It explains when to use a method, how to operate a tool, what risks matter, and what evidence the result must contain.
A plugin is a distribution unit. It can bundle skills, executable tools, MCP servers, hooks, apps, metadata, and assets. Packaging does not prove that every advertised capability exists.
A tool performs a bounded operation. It has inputs, outputs, failure behavior, and evidence. It may be a script, CLI, validator, API adapter, browser bridge, or server handler.
The Model Context Protocol tool boundary makes capabilities discoverable and callable through schemas. MCP creates a clean door; engineering still decides what the door opens into.
A hook runs at a lifecycle moment: before an edit, after a tool call, before a commit, or during validation. Hooks should be narrow because hidden automation is still authority.
If the operation touches an account, API, private file, OAuth session, or write action, a guard must decide what is allowed, under which scope, and with which audit trail.
The short version is worth remembering:
A skill teaches. A plugin packages. A tool acts. MCP exposes. A hook enforces timing. A guard protects authority.
A motor does not need to be impressive. It needs to be real.
Imagine a manuscript validator exposed as a tool. Its contract could be as small as:
{
"operation": "validate_manuscript",
"input": {
"document": "article.md",
"profile": "devto"
},
"result": {
"status": "passed",
"checks": 12,
"warnings": 1,
"artifact": "validation-report.json"
}
}
The important part is not JSON. The important part is that the operation can be executed, the bad input can be rejected, the output can be inspected, and the result can be reproduced.
A motor can be:
One tested motor beats ten prompt wrappers.
MCP is important precisely because it separates model reasoning from external capability. But a schema is not a security certificate, and a server name is not evidence of correctness.
A serious MCP tool still needs:
The official MCP specification gives us a protocol boundary. It does not eliminate the engineering work behind that boundary.
This is why the word plugin should never end the inspection. Ask what the plugin actually exposes. Ask which process handles the call. Ask what proves success. Ask what happens when the network fails, the token expires, the input is empty, or the user refuses permission.
The model should request authority less often than the system uses it.
When a task needs an API key, OAuth token, JWT, cookie, or private account, the ideal flow is not:
user secret -> prompt -> model context -> tool call
It is:
model intent
-> capability request
-> authorization guard
-> scoped credential use
-> bounded tool result
-> audit trace
The model needs to know what it may request. It usually does not need to know the secret itself.
OpenAI's documentation on MCP servers and plugin authentication points toward explicit tool and authority boundaries. That direction matters for beginners because unsafe patterns become habits quickly. If the normal tutorial begins by pasting tokens, cookies, headers, and .env
values into chat, we are teaching the wrong abstraction.
Teach scopes, consent, review, and bounded authority. Keep raw secrets in the systems designed to hold them.
Beginners can mistake structure for capability. A plugin folder looks official, a manifest looks architectural, and a detailed skill sounds operational. The inspection questions should stay simple:
Advanced users have the opposite problem. We know enough to create structure everywhere. We build skills for tone, agents for domains, hooks for habits, folders for memory, and plugins for workflows. Every layer solves a local pain. Together they can create global congestion.
The advanced skill is sometimes deletion.
Retire stale guidance. Merge overlapping skills. Tighten triggers. Move long theory into documentation. Separate activation from execution. Keep active instructions short and attached to living tools.
Here is the repair path I now use:
There is nothing anti-AI about this discipline. It is how we make agent power observable, reviewable, and maintainable.
A real plugin does not need to be huge. It needs to tell the truth.
It should say what it can do, what it cannot do, what authority it needs, what evidence it returns, and how it fails. If the motor is only a scaffold, return scaffold_only
. If an operation did not occur, do not let polished prose imply that it did.
Skills matter. Plugins matter. MCP matters. But none of them become stronger when we blur their roles.
Build the motor. Break its bad inputs. Inspect the result. Protect the secret. Document the boundary. Keep the human responsible for the consequential decision.
That is less magical than promising a universal agent plugin. It is also far more powerful, because it works for real.
What is the smallest plugin motor you have built that produced evidence you could actually verify?