Skills vs Context Files: When to Use Each

The loading model is the whole story, so it is worth being precise.

A context file is read in full at the start of the session and stays in context for every turn. If it is 150 lines, those 150 lines are present whether the task is a typo fix or a database migration.

A skill loads in stages. Anthropic's documentation calls this progressive disclosure and describes three levels (Claude platform docs):

As read on 2026-10-17, the same page put the metadata cost at about 100 tokens per skill and noted that scripts bundled in a skill run through bash, so "the script code itself never enters context," only its output. That makes a skill a cheap place to keep a lot of material. A skill can hold a full API reference or a long database schema, and none of it costs anything until the agent reads it.

The trade-off is reliability of loading. The VS Code documentation is direct about it: discovery "makes skills available to the model but does not guarantee that it invokes a skill for every relevant prompt" (VS Code). A context file is always present. A skill is present only if the model chooses to open it.

Put guidance in the context file when it applies to almost every task and is short enough that loading it every time costs little. The Claude Academy lesson lists three kinds (Claude Academy):

• Project-wide standards that always apply.
• Constraints such as "never modify the database schema."
• Framework preferences and coding style.

Add to that the commands the agent needs on every task: how to install, build, test and lint. A Hacker News discussion of a study on whether AGENTS.md files help coding agents reached a similar conclusion from practitioners. Commenters reported that the useful parts were basic commands and context about running the project, such as which build tool to use and how to run the tests, rather than long descriptions of the code (Hacker News). One commenter summed up the value as not letting the agent "fumble about trying to find the right thing every time you ask it anything."

There is a second, quieter reason to keep the context file stable and short. Teams that build agents care about cache reuse. The Manus team describes the cache hit rate as the most important metric for a production agent and advises keeping the prompt prefix stable, because "even a single-token difference can invalidate the cache from that token onward" (Manus). A context file sits at the front of every session, so a lean, rarely edited file is both cheaper and faster.

Put guidance in a skill when it matters for some tasks and not others, or when it is long. The Claude Academy lesson lists task-specific expertise, knowledge that is only relevant sometimes, and "detailed procedures that would clutter every conversation." Its example is a pull request review checklist, which has no reason to be in context while the agent is writing a feature and should appear when someone asks for a review.

Skills are also the right home for anything that is better run than read. Anthropic's documentation describes a skill as a directory that can hold instructions, executable code and reference materials, and it notes that a bundled script gives "deterministic operations without loading their code into context" (Claude platform docs). If a task involves filling a form, validating a file or calling an internal API in a fixed way, a script inside a skill does it the same way every time.

Typical skills on a software team:

• How to write and run end-to-end tests with the team's browser framework.
• How to cut a release, including the version bump and changelog format.
• How to call an internal service, with its schema in a reference file.
• How to debug a failing CI pipeline.
• How to review a pull request against the team's checklist.

Each one is long, procedural and needed only now and then. Quanta Intelligence publishes playbooks built this way for common business and engineering tasks, and the same shape works for any skill a team writes for itself.

Take every line you are tempted to add to the context file and ask four questions in order.

1. Must it never be violated? Then it does not belong in either file. A context file or skill is guidance the model weighs. A hard rule, such as "never write to the production database", belongs in a permission setting, a hook or a CI check that the tool enforces. The Claude Academy lesson separates hooks, which fire on events such as a file save or a tool call, from skills, which are request-driven.
2. Does it apply to nearly every task? Keep it in the context file, and keep it to a line or two.
3. Is it long, procedural, or tied to one kind of task? Make it a skill.
4. Does the agent need to call an outside system? Then the knowledge may need a tool, such as an MCP server, and a skill can explain how to use it. The Claude Academy lesson describes MCP servers as "a different category entirely from skills," because they provide tools and integrations rather than knowledge.

The table below shows the result for some common items.

Anthropic's engineering team describes the idea behind skills as "just in time" context: the agent keeps lightweight references, such as file paths, and loads the content at runtime only when it needs it (Anthropic). That saves space, but it hands the loading decision to the model. Use that as a guide. The more it matters that guidance is applied, the less you should leave its loading to the model.

A skill the agent never opens is dead weight. The agent decides whether to open it by reading the description, so the description does most of the work.

Anthropic's documentation says the description "must say both what the Skill does and when to use it" (Claude platform docs). The VS Code documentation adds two practical rules: the name may contain only lowercase letters, numbers and hyphens and must match the folder name, and a name with invalid characters causes the skill "to silently fail to load" (VS Code). Aurimas Griciūnas, writing about progressive disclosure, notes that the model selects skills by reasoning over the descriptions, so "description quality directly determining routing accuracy" (SwirlAI).

A good skill file looks like this:

---
name: e2e-testing
description: Write, run and debug the browser end-to-end tests in tests/e2e.
  Use when the user asks to add a UI test, when a UI change needs
  verification, or when the e2e job fails in CI.
---

# End-to-end testing

1. Start the app with `pnpm dev:test` (uses the seeded test database).
2. Run one spec with `pnpm e2e tests/e2e/<file>.spec.ts`.
3. On failure, open the trace with `pnpm e2e:trace` and read the first failing step.

Selectors: use data-testid attributes only. See SELECTORS.md for the list.
Never run the suite against staging; see CONSTRAINTS.md.

Four habits make skills reliable:

• Name the triggers. List the requests and situations that should load the skill, in the words a user would use.
• Keep SKILL.md short and link out. Put the procedure in the body and the long reference material in separate files the body points to.
• Bundle scripts for fixed operations. A script runs the same way every time, and only its output costs context.
• Allow manual invocation. Several tools let you call a skill by name as a slash command. VS Code exposes a disable-model-invocation setting for skills you only want to run on demand.

The context file has become a manual. If the file has grown past a few screens, it holds procedures that belong in skills. Move each procedure into its own skill and leave one line in the context file that names it, such as "For releases, use the release skill."

The same rule lives in both places. When a context file and a skill disagree, the agent may follow either. Keep each fact in one place. The context file can point to a skill, but it should not repeat the skill's content.

A critical rule lives only in a skill. If breaking the rule causes damage, it cannot depend on the model choosing to load a file. Move it to the context file at minimum, and to an enforced setting if it must never fail.

The skill description is vague. "Helps with testing" will rarely trigger. "Write and run the Playwright tests in tests/e2e; use when adding a UI test or when the e2e job fails" will.

Nobody reviews either file. A commenter in the Hacker News thread put it well: the file "should not be static," and teams should regularly review their skills, rules and memory together "to ensure there's no conflict across them all" (Hacker News). Review both kinds of file in pull requests, the same way you review code.

The eesel team's comparison offers a simple way to remember the split: AGENTS.md is a rulebook the agent reads, and a skill is a capability it loads when needed (eesel AI). Most projects need both, kept small and kept apart.