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.

The moment my own plugin exposed the problem

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 not instrumentation

Instruction is language. Instrumentation is contact with reality.

  • An instruction says, "validate the manuscript."
  • A motor runs the validator and returns evidence.
  • An instruction says, "respect this schema."
  • A motor rejects malformed input.
  • An instruction says, "never expose secrets."
  • An authorization layer prevents secrets from entering model-visible context.
  • An instruction describes a workflow.
  • Instrumentation proves which steps occurred.

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.

Skill, plugin, tool, hook: name the layer

The cleanest architecture I can defend today looks like this:

A skill teaches

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 packages

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 acts

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.

MCP exposes

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 enforces timing

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.

An auth guard protects 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.

What a motor actually looks like

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"
  }
}

Enter fullscreen mode Exit fullscreen mode

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:

  • a Python validator;
  • a deterministic transformation script;
  • a CLI that extracts metadata;
  • a browser tool that inspects rendered state;
  • an MCP server exposing one narrow operation;
  • a hook that blocks unsafe output;
  • an adapter that calls a service without leaking credentials.

One tested motor beats ten prompt wrappers.

MCP is not a magic door

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:

  • a narrow operation;
  • validated inputs;
  • structured outputs;
  • honest errors;
  • an authorization boundary;
  • observable logs or artifacts;
  • clear ownership and lifecycle;
  • human review for consequential writes.

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.

Secrets should not become model knowledge

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

Enter fullscreen mode Exit fullscreen mode

It is:

model intent
  -> capability request
  -> authorization guard
  -> scoped credential use
  -> bounded tool result
  -> audit trace

Enter fullscreen mode Exit fullscreen mode

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.

The beginner trap and the advanced-user trap

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:

  1. What does this skill teach?
  2. What executable operation does it call?
  3. What input does the operation accept?
  4. What output proves success?
  5. What happens on failure?
  6. Does it require authority or secrets?
  7. Where are the tests?

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.

Build one small real tool

Here is the repair path I now use:

  1. Choose one repetitive operation. Not a platform. Not a marketplace. One operation.
  2. Build the smallest deterministic motor. Make it useful before making it universal.
  3. Return structured output. The agent should not need to guess what success looks like.
  4. Test positive and negative cases. Empty input and failure paths matter.
  5. Expose the operation honestly. Use a CLI, hook, API adapter, or MCP server.
  6. Protect authority. Keep credentials and permission decisions outside ordinary model context.
  7. Write the skill after the motor works. Teach the agent how and when to use the real tool.
  8. Package the plugin when reuse is proven. Distribution comes after capability.

There is nothing anti-AI about this discipline. It is how we make agent power observable, reviewable, and maintainable.

The standard I want to keep

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?

Five references to go deeper