Instructions, Skills and Plugins

What enters context, what loads on demand, and what can execute code when using project instructions, skills, plugins, hooks, and MCP.

Updated 6 Oct 2026

Instructions, skills, plugins, hooks, and MCP often appear together because they extend what an agent can do, but they do not have the same effect. The useful questions are what enters context, what code can execute, and which behavior belongs to the harness.

Project instructions

repo/
├── AGENTS.md
├── src/
│   └── AGENTS.md
└── tests/

A project instruction file gives the model rules while it works in a repository. Codex uses AGENTS.md; Claude Code uses CLAUDE.md, and OpenCode supports rules in AGENTS.md. Search paths, inheritance, and exact precedence vary between harnesses.

A rule such as “run tests before finishing” guides the agent’s decision. If that check must be mandatory, the test runner or CI needs to enforce it deterministically: Markdown describes expected behavior but does not run the test by itself.

Length matters too. Instructions loaded routinely consume context, so broadly applicable rules fit at the project root while narrower guidance belongs closer to the relevant code when the harness supports that hierarchy.

Skills: guidance and resources on demand

A skill usually packages guidance for a particular task together with optional resources:

my-skill/
├── SKILL.md
├── references/
│   └── methodology.md
├── scripts/
│   └── validate.py
└── assets/
    └── template.md

SKILL.md explains when to use the skill and how to work. References keep deeper material outside the main path, while scripts can provide deterministic checks. Putting validate.py in the folder does not execute it automatically: the agent needs instructions to use it and a suitable execution tool and runtime.

Codex documents progressive loading where skill names and descriptions are exposed first and the full SKILL.md is loaded after selection. Claude Code and OpenCode follow similar ideas with their own discovery, invocation, and scope rules.

The useful pattern is to keep initial context small and load depth when the task needs it:

discovery → name and description → SKILL.md → required references or scripts

A skill’s guidance can be portable between compatible products. Its scripts still depend on paths, dependencies, permissions, and tools available in the environment where they run.

Plugins, hooks, and MCP

Plugin describes an installable package, but its contents can vary widely. It may bundle skills, MCP server configuration, or extensions that execute code inside a harness.

The Agent Plugins Specification 1.0 defines a portable floor with plugin.json, skills under skills/, and MCP configuration in mcp.json:

my-plugin/
├── plugin.json
├── skills/
│   └── review/
│       └── SKILL.md
└── mcp.json

The specification covers discovery and packaging of those pieces. It does not define how each client presents a skill to the model, which permissions it applies, or how hooks work. Version 1.1 remains a working draft, so compatibility also depends on the version a client supports.

A hook executes code when a harness-defined event occurs, for example after a tool call. That part is much less portable because it depends on the host API, event model, and execution environment.

An MCP server can expose tools or resources to a compatible client. Packaging its configuration inside a plugin can make installation easier, while the real capability still depends on the server, its credentials, and the permissions used to connect.

Portability

When moving a setup between agents, it helps to separate each piece by its effect:

Instructions are text the harness must discover and place in context.
A skill adds instructions and resources that can be loaded when needed.
A tool performs an operation through a defined interface.
A hook executes code at a lifecycle point defined by the harness.
A plugin packages one or more of those pieces.
MCP standardizes an interface for exposing external capabilities, while the service behind it still has its own dependencies and authorization.

Copying a folder can move the portable content. Behavior that depends on a specific runtime or host hooks needs to be adapted to the new harness.