Skip to main content
Version: v2.0

Instructions

The instructions are the part of an agent's configuration usually used to describe its job. This page covers what belongs in them, where they live, and how to use them.

Instructions give the agent the context it should always know​

Imagine that your marketing launch agent is preparing a brief for Team Workspaces. It should not need you to repeat your audience, product position, or company voice each time.

A useful first set of instructions might say:

# Role

You are the marketing launch agent for Acme.

## Audience

Write for operations leaders at enterprise software companies.

## Working style

Lead with the customer problem. Support claims with product notes or campaign data.
Ask before publishing or sending anything outside the team.

This is standing context. It should guide a launch brief, a positioning review, and a quick answer about the product.

What are agent instructions?​

The instructions, sometimes called the system prompt, are sent to the model at the start of every session. They live in a file named AGENTS.md.

An agent without instructions is a general agent, similar to ChatGPT or Google AI. Adding instructions turns that general agent into a custom agent.

What goes in the instructions?​

The instructions hold the context the agent must always have.

Good instructions answer questions the agent faces throughout its work:

  • What job is the agent here to do?
  • Who does it work with and for?
  • What goals and limits should guide its choices?
  • How should it communicate?
  • How should it organize its work?

Keep instructions short​

It might be tempting to put everything in the instructions, including feedback and notes, because you assume more context will improve the agent's performance. That is not the case.

Instructions go to the model on every turn. Long instructions send more tokens to the model each time. This increases the cost of running the agent and can also decrease its performance. LLMs can perform worse with larger contexts. The more information you provide, the greater the chance the model misses an important point (just like humans).

So always limit the size of the instructions and use progressive disclosure.

Progressive disclosure works like a book index. Say you are building a custom outreach agent, and one step is writing the final email. Instead of adding the email templates to the instructions, write When writing emails, read the templates in <file>. Put the templates themselves in the agent's folder. The instructions stay short, but the context remains available. When the agent reaches that step, it follows the instruction and reads the templates. Skills provide a similar way to use progressive disclosure.

One pattern follows from this: the instructions work as a map to everything else. A single line such as "the style guide is in writing/style.md, read it before drafting" spends a few always-loaded words and buys a whole document that costs nothing until it is needed.

How to build and improve your instructions​

Instructions describe how the agent should act. They are the working manual it follows. A well-built manual creates a useful agent. However, you often do not know how the agent should work at first. When you build your first GTM agent, you do not yet know everything it will do or the mistakes it will make.

Building the instructions is similar to training someone for a new job. Start with something simple: a few lines explaining what the agent is for and who it works with. Then work with it and improve the instructions over time. Here are some examples:

Say you are building a GTM agent and use it for an SEO task for the first time. When you finish, tell it to update its instructions with what it learned and use progressive disclosure. It can add a few lines to the instructions and write a file about the SEO task in its folder. Next time, it will know how to approach the task.

You continue working with the agent on SEO articles, but it keeps writing AI slop. You work with it, add some skills, and give feedback until the quality is good. Then tell it to learn from that feedback (Reflect). It will update its instructions, and its work will be better next time.

Write your agent's instructions covers the editor, a worked first version, and how to fold a correction back in.