Agent Skill vs Instructions: When Plain Instructions Are Not Enough

Instructions tell an agent what to do in a particular context. An agent skill packages instructions into a reusable workflow with a name, trigger, inputs, references, optional scripts, completion evidence, stop rules, and a maintenance path.

All agent skills contain instructions. Not all instructions deserve to become skills.

The practical test is simple: use instructions when you need to steer one interaction, one role, or one policy. Use a skill when the work repeats and the procedure itself needs to be discovered, run, reviewed, and improved. If you are comparing the adjacent boundary between skills and prompts, Skillfully's Agent Skills vs Prompts covers that narrower wording question. This article focuses on a broader one: when a pile of rules, project guidance, and examples should become a real operating procedure.

The word "instructions" has a specific meaning in modern agent systems. OpenAI's Model Spec describes a chain of command for resolving conflicts across higher- and lower-authority instructions. OpenAI's explainer on the Model Spec frames that chain of command as the mechanism for deciding which instruction applies when OpenAI, developers, users, tools, or retrieved content disagree, and OpenAI's instruction-hierarchy research connects the same priority order to prompt-injection robustness.

That matters because instructions are not all the same. A system or platform instruction is not equivalent to a user request. A developer instruction is not equivalent to text found on a web page. Tool output and quoted content may contain words that look like commands, but they are evidence unless a higher-authority instruction delegates authority to them.

A skill solves a different problem. OpenAI's Codex skills documentation describes a skill as a package of instructions, resources, and optional scripts that helps Codex follow a workflow reliably. Anthropic's Agent Skills overview uses the same broad idea: custom skills package domain expertise and organizational knowledge, and Claude loads them through a staged model of metadata, instructions, and deeper resources.

So the boundary is not "short text versus long text." The boundary is:

• instructions define what the agent should obey or consider
• skills define how a repeatable job should be carried out

An AGENTS.md file can tell a coding agent to run npm test before finalizing work. A .github/copilot-instructions.md file can tell GitHub Copilot to prefer one library over another. A Cursor rule can tell the agent which React patterns are acceptable in a repository. Those are instructions. They become skill-like only when they name a specific job, define a repeatable workflow, and include the evidence needed to know whether the job was completed.

Plain instructions are still the right tool for a lot of work. OpenAI's prompt engineering guide is about writing effective instructions so a model consistently generates the output you want in a particular interaction. That is useful, and it should not be over-packaged.

Use plain instructions when the task is immediate, narrow, and easy to inspect:

• "Summarize this document in five bullets."
• "Use JSON with title, summary, and risk fields."
• "Do not expose implementation details in the customer-facing response."
• "In this repo, use date-fns instead of moment."
• "For this answer, assume the reader is a senior backend engineer."

These instructions can be excellent because they are cheap to write, easy to override, and close to the task. You do not need a skill to rewrite one paragraph, answer one support question, or set a one-time tone preference.

VS Code's custom instructions documentation makes this tradeoff concrete for coding agents. It supports always-on repository instructions, path-specific instruction files, AGENTS.md, and CLAUDE.md. Those files are useful because they prevent users from restating the same local conventions in every chat request. They are still usually instruction layers, not full workflow packages.

Instructions become fragile when they are asked to carry workflow responsibility that belongs somewhere else.

The warning signs are familiar:

• The same paragraph is copied into many prompts, issues, docs, or chat threads.
• The agent must inspect the same files, URLs, logs, or dashboards every time.
• The final answer is hard to judge without knowing the intended process.
• Missing prerequisites cause bad output instead of a clean stop.
• Different teammates have slightly different versions of the same rules.
• The instruction keeps growing because every failure mode adds another exception.

At that point the problem is not that the instruction needs more words. The problem is that the team has discovered a repeatable job without packaging it as one.

For example, "review this migration guide" is a normal instruction. "Review every SDK migration guide before publication by checking package versions, prerequisites, API diffs, copy-paste commands, rollback notes, and broken links, then return blocking issues with replacement text" is a workflow. If the docs team runs that process every release, it should be a skill, not a recurring paragraph in Slack.

The same pattern shows up in product, support, sales, and operations. "Make this concise" is an instruction. "Turn a support transcript into an escalation brief with account facts, policy citations, suggested customer response, unresolved questions, and a confidence rating" is a skill-shaped workflow because the result can be reviewed and improved.

A skill adds operational structure around instructions:

• a named repeatable job
• a trigger that helps the agent know when to use it
• required inputs and source priority
• references, examples, templates, or assets
• optional scripts for fragile or repetitive steps
• stop rules for missing context or unsafe scope
• completion evidence that can be checked after the run
• feedback or revision hooks when the workflow should improve

That structure changes the artifact from "remember this rule" to "follow this operating procedure."

OpenAI Codex skills use progressive disclosure: Codex initially sees a skill's name, description, and file path, then loads the full SKILL.md only when the skill is selected. Anthropic's skill authoring best practices make a similar point: metadata helps discovery, the main file should stay concise, and deeper resources should be loaded only when needed. The open Agent Skills specification formalizes the package shape as SKILL.md plus optional scripts/, references/, and assets/. That is why a strong skill is not merely a long instruction file. It is a small package designed for discovery, execution, and maintenance.

If you are writing one from scratch, Skillfully's How to Write an Agent Skill That Actually Works gives the full authoring workflow. The core is the same here: define the job, choose trusted inputs, write visible completion evidence, set stop rules, and release a narrow version you can improve.

The modern ecosystem already shows the distinction.

OpenAI Codex skills are explicit workflow packages: a directory with SKILL.md plus optional scripts/, references/, and assets/. The skill can be invoked directly or chosen implicitly from its description. That makes the description part of the discovery contract, not marketing copy.

Anthropic Agent Skills include pre-built document skills for PowerPoint, Excel, Word, and PDF work. Those are not just style preferences. They package domain procedures for creating, editing, and analyzing files, with runtime constraints that differ across Claude API, Claude Code, and claude.ai.

VS Code now documents both sides of the boundary. Its Agent Skills documentation describes skills as portable folders of instructions, scripts, and resources that Copilot can load on demand for specialized tasks. Its custom-instructions docs describe always-on and path-specific guidance for coding standards. GitHub's repository instructions docs apply the same distinction to GitHub Copilot. "All API routes must validate auth first" is a repository instruction. "Prepare release notes by inspecting merged PRs, classifying user-facing changes, drafting copy, checking links, and returning a publish checklist" is skill-shaped.

Cursor's rules documentation covers persistent Project, Team, and User Rules, plus AGENTS.md. Cursor rules are a natural place for coding standards, architectural constraints, and local preferences. A Cursor rule can say, "Use server actions only in this directory." A skill should say, "When converting a feature spec into implementation tasks, inspect these docs, produce this task shape, run these checks, and stop if the acceptance criteria are missing." For more on that distinction, see Skillfully's Agent Skill vs Rules and Agent Skill for Cursor.

The community AGENTS.md format makes the same point in a vendor-neutral way: it gives coding agents setup commands, tests, and conventions in a predictable file. OpenAI's AGENTS.md guide for Codex describes layered global, project, and nested guidance. That is valuable instruction infrastructure. It becomes a skill only when those commands and conventions are wrapped around a named job with a workflow and completion standard.

Start with a plain instruction:

Review this migration guide and make it clearer for developers.

Improve the instruction:

Review the migration guide for missing prerequisites, unsafe copy-paste commands,
version assumptions, API differences, rollback gaps, and broken links. Return a
table of issues with severity and suggested replacement text.

Now turn it into a skill:

Use this skill when reviewing SDK migration guides before publication.

Required inputs: the migration guide, target SDK version, source release notes,
and at least one example app or test command.

Workflow:
1. Verify the target SDK version is named. Stop if it is missing.
2. Compare prerequisites against the release notes.
3. Check every command for copy-paste safety and rollback risk.
4. Identify API differences that need before/after examples.
5. Test links and classify issues as blocking, important, or polish.

Return: a severity table, exact section references, replacement text for
blocking issues, and the verification steps a maintainer should run.

The skill is not better because it is longer. It is better because it defines a repeatable job. It names required inputs, establishes source order, prevents a common failure mode, and produces evidence a docs lead can inspect.

Dimension	Plain instruction	Agent skill	Tradeoff
Scope	One request, rule, preference, or output constraint	Repeatable job with a beginning, middle, and end	Skills add overhead, so use them only when the job repeats
Authority	Often system, developer, user, repo, or tool-adjacent guidance	Usually loaded as task-specific procedure within the agent environment	Skills still must obey higher-priority instructions
Context	Supplied inline or through always-on files	Can include references, templates, scripts, and examples	Skills reduce repeated context but require maintenance
Discovery	Included directly or always applied	Selected explicitly or implicitly from metadata	Skill descriptions must be specific enough to trigger correctly
Completion	Often implied by the answer	Defined as visible evidence	Evidence makes quality review possible
Maintenance	Edited informally	Versioned, tested, published, and improved	Skills age like product artifacts

The authority row is important. A skill is not a magic override. If a user asks a skill to ignore repository safety rules, the agent should still follow the higher-priority instruction layer. Skill authors should design skills to cooperate with system, developer, repository, and user instructions rather than pretending the skill sits above them.

Use the smallest package that makes the work reliable.

1. Keep single-use requests as instructions.
2. Move repeated project conventions into repository instructions, AGENTS.md, VS Code instructions, Cursor rules, or equivalent local guidance.
3. Promote a repeated job into a skill when it has stable inputs, a recognizable trigger, and checkable completion evidence.
4. Add references only when the agent needs the same background material repeatedly.
5. Add scripts only when a step is fragile, mechanical, or expensive to perform by hand.
6. Add feedback when the skill will be reused enough that learning from real runs matters.

That sequence avoids the common failure mode of turning every preference into a skill. A team style rule does not need a skill. A weekly account-brief workflow might. A codebase convention belongs in instructions. A repeatable code-review process with severity classes, file inspection order, verification commands, and final reporting shape belongs in a skill. Skillfully's Measuring Agent Skill Quality is useful once you reach that last stage, because repeated workflows deserve repeated evidence.

The first mistake is calling any long instruction a skill. Length is not the test. Reuse is the test. A 50-word skill can be strong if it names a precise job and proof of completion. A 2,000-word instruction can still be weak if it never tells the agent where to start or when to stop.

The second mistake is putting authority rules in the wrong place. Safety policies, product constraints, and repository-wide conventions often belong in system, developer, or project instruction layers. A skill can reference them, but it should not be the only place they exist.

The third mistake is hiding the trigger. If the description says "helps with documents," the agent may not know when to use it. If it says "review SDK migration guides before publication; use when checking prerequisites, API diffs, commands, rollback notes, and links," the discovery path is much clearer.

The fourth mistake is skipping stop rules. A skill that depends on a version number, account record, transcript, repo path, or policy document should say what to do when that input is missing. Otherwise the agent improvises, and the final answer may look confident while resting on a bad assumption.

Instructions steer behavior. Skills package repeatable work.

Keep plain instructions for immediate tasks, local preferences, and authority-bearing rules. Write an agent skill when the same job repeats, the workflow matters, the agent needs stable context, and the result should be checked or improved over time.

The best version is usually not the longest version. It is the version that gives the agent a clear job, the right sources, a reliable path through the work, and visible evidence that the work is done.