Agent Files vs Agent Skills: Use Local Context First

I am replacing many task-specific Agent Skills with something simpler: an Agent File placed next to the work it governs. In this article, Agent File means a project instruction file such as AGENTS.md that explains the local business logic, operating rules, available resources, and definition of done.

The goal is not to eliminate skills. It is to avoid packaging ordinary context as a formal capability before the work proves that the extra structure is useful.

What is an Agent File?

AGENTS.md is an open, Markdown-based convention for giving coding agents project context and instructions. The closest file in the directory tree takes precedence, which makes it possible to keep detailed guidance near the files it affects.^[1]

marketing/
  AGENTS.md
  campaigns/
  content/
  analytics/

customer-support/
  AGENTS.md
  knowledge-base/
  tickets/

finance/
  AGENTS.md
  invoices/
  reports/

When an agent works in marketing, it can read the marketing instructions. When it moves into finance, it receives the finance rules. The file acts as local, just-in-time context instead of a globally reusable workflow.

Why local context can reduce token overhead

Well-designed Agent Skills do not load every instruction at startup. The Agent Skills specification uses progressive disclosure: agents first receive skill metadata, load the full SKILL.md only after activation, and pull supporting resources as needed.^[2]

That design is efficient, but a large skill library still has a catalog cost. The official client implementation guide estimates roughly 50–100 tokens of name and description metadata per discovered skill. It also gives the model more candidates to route between before the real task begins.^[3]

• Smaller working context: the agent sees the rules for the current directory rather than a broad capability catalog.
• Lower routing overhead: fewer irrelevant choices means less context and less chance of activating the wrong workflow.
• Simpler maintenance: local rules change with the project and can be reviewed in the same repository.

These savings are conditional, not automatic. A concise, correctly triggered skill may be cheaper than a huge Agent File, while a deeply nested instruction hierarchy can be confusing. Measure the actual context delivered by your agent runtime instead of treating either format as universally efficient.

Most business rules do not need a formal skill

Many so-called skills are primarily a prompt, a sequence of suggested steps, a few tool notes, and a definition of done. For content operations, research, project management, customer support, documentation, and internal analysis, local instructions may provide enough structure.

• What this directory is responsible for.
• What outcome the agent should achieve.
• What the nearby files, data, and tools mean.
• Which actions require human approval and which constraints must always hold.
• How the agent and reviewer can verify the final result.

Agent Files and Agent Skills solve different problems

Use an Agent File for situated judgment

An Agent File says: here is the local environment, the business intent, the boundaries, and the desired result. Inspect the work and decide how to complete it. This suits tasks where the path can vary and the model's judgment is part of the value.

Use an Agent Skill for reusable capability

An Agent Skill says: here is a discoverable capability and the procedure for using it. The open specification requires a SKILL.md and allows bundled scripts, references, and assets, making skills well suited to repeatable workflows that must travel across projects or agents.^[2]

When an Agent Skill is still the right choice

• The operation needs deterministic scripts or a stable input and output contract.
• The same capability must work across many repositories, teams, or agent clients.
• The workflow needs explicit permissions, isolation, auditability, or formal testing.
• The action is high risk or difficult to reverse, such as payments, refunds, authentication, database migrations, infrastructure deployment, or security changes.

A practical decision rule

1. Start with an Agent File that states the goal, boundaries, available resources, approvals, and acceptance criteria.
2. Run real tasks and observe where the agent repeatedly invents the same procedure or makes the same avoidable mistake.
3. Measure the context and token cost in the actual runtime rather than assuming one architecture is cheaper.
4. Promote only the repeated, portable, or high-risk portion into a skill, script, or controlled tool.
5. Keep project-specific business meaning in the local file so the reusable capability does not become coupled to one team's context.

The architectural shift

Traditional software engineering predefines behavior because software cannot infer business intent. Modern agents can inspect directory structures, read nearby files, use tools, evaluate results, and adjust their approach. That creates room for a more outcome-oriented architecture.

Give the AI the goal, local context, permissions, constraints, and acceptance criteria. Let it reason about the path. Turn the parts that genuinely require reuse, repeatability, and control into skills.