Instructions vs. Skills: What Belongs Where?

Coding agents become more useful when they stop relearning the same context in every conversation. The obvious response is to write that context down. The difficult question is where.

Should a rule go into AGENTS.md or CLAUDE.md? Should it become a skill? Does it belong in the prompt for one task? Or should it be enforced by a test, formatter, permission rule, or script instead of being explained to an agent at all?

The simplest useful distinction is this:

Instructions describe the environment the agent is always working inside. Skills describe a job the agent sometimes needs to perform.

Instructions are durable context and constraints: how the repository is organized, which commands are canonical, what must never change casually, and what “done” means across many tasks. Skills are reusable packages for a narrower activity: reviewing an API migration, preparing a release, generating a frontend handoff, investigating a failed CI run, or producing a document in a required format.

That boundary is not about whether the content is written in Markdown. Both mechanisms often are. It is about scope, loading, and intent.

Instructions and skills solve different context problems

Question	Instructions	Skills
Primary purpose	Establish persistent context, constraints, and working agreements	Package a reusable capability, workflow, or body of reference material
When loaded	At session or project initialization, or when entering a scoped directory	On demand, through explicit invocation or relevance matching
Expected scope	Broadly applicable across many tasks in the repository	Relevant to a particular class of task
Typical content	Repository map, build commands, architectural boundaries, universal verification rules	Checklists, multi-step procedures, templates, domain references, scripts, examples
Main failure mode	Polluting every task with irrelevant or contradictory context	Triggering at the wrong time or hiding essential project rules behind optional activation
Maintenance question	“Does almost every agent task still need to know this?”	“Is this workflow repeatable, focused, and discoverable?”

The loading distinction is central. OpenAI describes skills as reusable workflows that use progressive disclosure: Codex first sees a skill’s name and description, then reads its full SKILL.md when the skill is selected. A skill can also include scripts, references, and assets without placing all of them into every task’s context. OpenAI’s skill documentation explains this loading model .

Claude Code makes the same practical distinction. Its documentation recommends CLAUDE.md for information Claude should always know and skills for occasional reference material or repeatable workflows. The comparison is explicit: CLAUDE.md loads every session, while a skill loads when invoked or relevant. Anthropic’s feature guide summarizes the boundary .

The mechanism is therefore less like “short instructions versus long instructions” and more like “operating context versus routed capability.” A six-line release procedure may still be a skill because it is irrelevant to normal feature work. A longer repository map may belong in project instructions if nearly every task depends on it, although concision still matters.

Put information in instructions when it is nearly universal

Instructions earn space in always-on context when omitting them would predictably make many different tasks less safe or less efficient.

Good instruction content includes:

the package manager and verified commands for focused tests, type checking, linting, and builds;
a small repository map when directory names do not reveal architectural responsibilities;
hard project boundaries, such as “database migrations must be backward compatible” or “generated API types must not be edited by hand”;
conventions that cannot be inferred reliably from nearby code;
the minimum verification expected after a change;
scope-specific facts placed close to the subtree they govern.

For example:

# Project instructions

- Use pnpm; do not create npm or Yarn lockfiles.
- Run pnpm test -- <changed-test> during iteration.
- Files under src/generated are produced by pnpm api:generate. Do not edit them manually.
- Changes to public API responses require a compatibility note under docs/handoffs.

Each line applies to many plausible tasks, is concrete enough to change behavior, and would be expensive for an agent to rediscover.

Instructions should not become a repository encyclopedia. The agent can read README.md, architecture documents, package manifests, and source files when they are relevant. Always-on instructions should route the agent toward those sources, not duplicate them.

They are also not enforcement. Anthropic explicitly describes CLAUDE.md as context rather than guaranteed configuration; a hook or permission mechanism is needed when an action must be blocked regardless of model judgment. The same engineering principle applies across agents: if violating a rule would be dangerous and a machine can detect the violation, enforce it outside the prompt. Anthropic documents this distinction for Claude Code .

Put information in a skill when it defines a repeatable job

A skill is the better home when the content becomes useful only after the task enters a recognizable mode.

Strong skill use cases include:

Release preparation: run a defined checklist, update a changelog, validate artifacts, and produce a release summary.
CI failure diagnosis: collect the correct logs, classify the failure, reproduce it locally, and report evidence in a consistent structure.
Security review: inspect a diff using a threat model and produce severity-ranked findings without burdening routine coding tasks.
Artifact creation: generate PDFs, presentations, spreadsheets, or handoff documents using templates and mandatory visual verification.
Framework-specific migration: load versioned reference material and follow a staged procedure only when that migration is requested.
Team-specific review: apply a domain checklist for database queries, accessibility, observability, or API compatibility.
Tool workflow: combine instructions with scripts or external integrations for a job that has stable inputs and outputs.

A good skill has a narrow contract. Its description says both what it does and when it should activate. Its body uses imperative steps, identifies required inputs, defines the output, and gives the agent an observable stopping condition.

---
name: prepare-release-notes
description: Create release notes from commits between two refs. Use when asked to prepare a product release or changelog entry.
---

1. Confirm the start and end refs.
2. Group user-visible commits into Added, Changed, Fixed, and Removed.
3. Exclude merge commits and internal-only maintenance.
4. Link each item to its pull request when available.
5. Return the draft and list any ambiguous commits separately.

This procedure does not need to occupy the context of a bug fix, a component refactor, or a database query. It should be discoverable, then loaded when the task matches.

Skills can contain reference knowledge as well as procedures. That is useful when an API guide, style system, template, or compliance checklist is too specialized for permanent instructions. Keep the main SKILL.md focused and route to supporting files only when needed. Both OpenAI and Anthropic document skill directories with optional references, scripts, and other supporting resources.

Sometimes the right answer is neither

Instructions and skills are not the destination for every useful sentence.

Use a one-off prompt for one-off intent

“Compare these two implementation approaches and do not edit files” belongs in the current request. Turning it into permanent guidance would make unrelated work more cautious; turning it into a skill would create a reusable asset with no demonstrated reuse.

Promote a prompt only after a pattern repeats and its stable parts become clear. The first successful workflow is evidence, not yet an API.

Use documentation for knowledge humans also need

A detailed architecture decision, onboarding guide, incident history, or domain explanation belongs in normal project documentation. Instructions can point to it when relevant. A skill can define how to use it during a specialized workflow. Neither should become the only place where important team knowledge exists.

Use tooling for deterministic rules

If a formatter can format it, a linter can reject it, a type checker can prove it, or a test can verify it, prefer that mechanism. “Use two spaces” is weaker than a checked-in formatter configuration. “Never commit secrets” is weaker than secret scanning and protected credentials. “Do not call this deprecated API” is weaker than a lint rule or compile-time restriction.

The instruction may still name the command the agent must run, but it should not duplicate the machine-readable rulebook.

Use permissions or hooks for hard safety boundaries

An instruction can guide judgment; it cannot guarantee compliance. Destructive commands, production deployment, access to sensitive data, and external side effects should be controlled by the agent host, sandbox, approval policy, credentials, or hooks. Put the policy explanation in instructions only if it helps the agent plan around the boundary.

A decision rule that works across agents

Ask these questions in order:

Can a deterministic tool enforce it? Use a test, type, linter, formatter, script, permission, or hook.
Is it needed only for this request? Put it in the prompt.
Must the agent know it for almost every task in this scope? Put a concise version in project instructions.
Does it describe a repeatable, recognizable activity? Create a focused skill.
Is it detailed knowledge for humans and agents? Put it in normal documentation, then link to it from the relevant instruction or skill.

Frequency alone is not enough. A release may happen every day and still be a skill because most agent tasks are not releases. A database safety constraint may matter only occasionally but still belong in instructions because the cost of missing it is high whenever database code is touched. Consider breadth, risk, and activation signal together.

Good and bad practices

Bad practice	Why it fails	Better approach
Put every useful fact into `AGENTS.md` or `CLAUDE.md`	Irrelevant context competes with the current task and becomes stale	Keep a small universal core; route to documentation and skills
Turn one successful prompt into a skill immediately	The reusable contract and edge cases are still unknown	Reuse the prompt manually, then extract the stable workflow
Write “follow best practices”	It is vague, unverifiable, and may conflict with repository conventions	Name the specific constraint and its verification command
Copy the same long procedure into several instruction files	Copies drift and every session pays the context cost	Keep one canonical skill or document and use thin tool-specific adapters
Hide a universal safety rule inside an optional skill	The skill may not activate when the rule matters	Put the rule in scoped instructions and enforce it mechanically when possible
Make a skill description broad to improve discovery	It triggers on unrelated work and creates surprising behavior	State precise positive triggers and clear boundaries
Encode formatter, lint, or schema rules in prose	The model must simulate deterministic tooling imperfectly	Configure the tool and tell the agent which check to run
Treat skills as a dumping ground for long context	A selected skill can still overwhelm the task	Keep `SKILL.md` concise and split supporting references by need

Good systems also remove guidance. When the repository structure changes, delete the old map. When CI begins enforcing a rule, shorten the prose. When a skill grows to cover several unrelated jobs, split it. Context configuration is code-adjacent infrastructure: it needs ownership, review, tests through representative tasks, and occasional pruning.

Where this lives in Codex and Claude Code

The conceptual split is portable, but discovery paths are product-specific.

Codex

Codex uses AGENTS.md as its native project-instruction file. It can layer global guidance with repository and nested-directory instructions, so broad rules belong at the root and narrower rules belong near the code they govern. The detailed precedence rules are covered in our guide to AGENTS.md across coding agents and in OpenAI’s official AGENTS.md documentation .

Repository skills live under .agents/skills/<skill-name>/SKILL.md. Personal and administrative scopes are also available. Codex initially indexes skill metadata and loads the full instructions when a skill is explicitly invoked or its description matches the task.

repository/
├── AGENTS.md
├── .agents/
│   └── skills/
│       ├── diagnose-ci/
│       │   └── SKILL.md
│       └── prepare-release/
│           ├── SKILL.md
│           └── references/
└── src/

Claude Code

Claude Code’s native project-instruction file is CLAUDE.md. If a repository already has shared AGENTS.md guidance, Anthropic documents a small CLAUDE.md that imports it with @AGENTS.md, followed by any genuinely Claude-specific additions. The official memory guide shows this interoperability pattern .

Project skills live under .claude/skills/<skill-name>/SKILL.md. Claude can invoke them based on the description, and users can invoke them directly by name. Claude Code adds product-specific controls, but the core SKILL.md format follows the Agent Skills open standard.

repository/
├── AGENTS.md
├── CLAUDE.md                 # imports AGENTS.md; adds only Claude-specific guidance
├── .claude/
│   └── skills/
│       ├── diagnose-ci/
│       │   └── SKILL.md
│       └── prepare-release/
│           └── SKILL.md
└── src/

Supporting several agents does not require pretending their discovery paths are identical. Keep the meaning portable: one shared instruction core, thin product-specific adapters, and focused skills installed where each host expects them. If you share the same skill content across tools, choose one canonical source and test the linking or packaging strategy in every supported environment instead of maintaining hand-edited copies.

How to split an overloaded instruction file

When AGENTS.md or CLAUDE.md has become a manual, migrate it by classification rather than by line count:

Keep verified commands, repository boundaries, universal constraints, and default verification in the instruction file.
Move language-, package-, or directory-specific rules closer to their scope when the host supports scoped instructions.
Move named procedures such as deploy, release, audit, migrate, and handoff into separate skills.
Move explanations, architecture history, and large reference tables into normal documentation.
Replace prose rules with deterministic checks where possible.
Delete duplicated, obsolete, obvious, or contradictory guidance.
Test representative tasks: one that should use only instructions, one that should activate a skill, and one that should activate neither.

Do not optimize for the smallest possible instruction file. Optimize for the smallest file that reliably supplies the context many tasks cannot infer. Do not create the largest possible skill library either. Optimize for a set of capabilities whose activation is predictable and whose outputs can be verified.

The practical answer

Use instructions for the agent’s operating environment. Use skills for its reusable jobs. Use prompts for current intent, documentation for shared knowledge, and tooling for rules that machines can enforce.

If a section starts with “Whenever you work in this repository…”, it is probably an instruction. If it starts with “When asked to perform this workflow…”, it is probably a skill. If it starts with “For this task only…”, keep it in the prompt. If it can be expressed as a failing check, make it a check.

The best agent configuration is not the one that remembers the most. It is the one that loads the right information at the right time and leaves as little important behavior as possible to memory alone.