Instructions as Files

A new developer joins, and spends a week finding out how to run the tests. Coding agents have the same problem, every session. So a simple idea has spread quickly. Write down what an agent needs to know, in a file, in your repository.

• A new developer's first week
• Agents repeat it every session
• Write it down in a file

An instructions file

This file sits at the top of a project. It says how to build and test, gives important rules, and describes the style. It's plain text, and agents read it when they start. Many coding agents read a file like this, and it's often called agents dot MD. Keep it short, since it costs tokens in every session.

# Velo Supply repository

## Build and test
- Install: pip install -r requirements.txt
- Test: pytest -q

## Rules
- All refund logic lives in payments/, and it needs tests.
- Never change database migrations by hand.

## Style
- Use type hints on all public functions.

Skills

A skill goes further. It's a folder that holds instructions for one task. Only its name and description get loaded at the start. The full text is read only when it's needed. That idea's called progressive disclosure. It means that an agent can have hundreds of skills, without filling up its context. Our earlier lesson on tokens is why this matters.

---
name: refund-review
description: Use when reviewing a refund request over fifty dollars.
---

# Refund review

1. Read the order and the customer's history.
2. Check the warranty rules in policy/warranty.md.
3. Write a one-paragraph recommendation for a human.
4. Never issue the refund yourself.

Context on demand

Notice a pattern here. Tool search, skills, and retrieval all do the same thing. Don't load everything up front. Give the agent a small index, and let it fetch what it needs. That's the single biggest idea in modern context engineering, and it's the reason that today's agents can work on huge projects.

Summary