Instructions

Every time OpenCode starts a new session, it looks for a file called AGENTS.md and reads whatever instructions you’ve written there. Think of it as a set of standing orders for your AI assistant — preferences, rules, and context that apply to everything it does.

AGENTS.md has emerged as the closest thing to an industry standard for AI instruction files. Many AI coding tools — not just OpenCode — look for a file with this name and use its contents as standing instructions. By writing an AGENTS.md, you’re creating something portable that works across tools.

Global vs. project

There are two kinds of AGENTS.md files:

• Global (~/.config/opencode/AGENTS.md) — Applies to every OpenCode session on your machine. This is your personal preferences file. It’s not committed to Git or shared with anyone.
• Project (AGENTS.md in a project’s root directory) — Applies only when you’re working in that project. This one you typically commit to Git so your whole team benefits from the same instructions.

Both can exist at the same time. When they do, OpenCode reads both — global rules first, then project rules on top.

In this lesson, we’re creating the global one.

Create your AGENTS.md

OpenCode will create the file and populate it with starter content. Approve any permission prompts that appear.

What to put in it

Here’s an example of what a global AGENTS.md might look like. Notice it’s not just technical rules: it includes personal context, communication preferences, and writing style alongside coding conventions:

## About me

- My name is Ren. I'm a frontend developer based in Melbourne.
- My GitHub username is `rendev` and my email is `ren@example.com`.
- I primarily work in TypeScript and Python.

## Communication

- Be concise. Don't oversell changes or use fancy words like
  "comprehensive", "utilize", "streamline", or "leverage".
- Never use em dashes. Use commas, colons, or separate sentences instead.
- If your last message included URLs, list them at the end so I can
  open them easily.

## Writing

- When writing pull request descriptions, start with "This PR..." and
  keep it to 2-3 sentences.
- When writing markdown, avoid headings smaller than H2 and don't
  use bold for emphasis.

## Working with Git

- Always use semantic commit prefixes (feat:, fix:, docs:, etc.).
- Never push to the main branch. Always push to a feature branch.
- Run the project's lint script before committing, if one exists.

This is just a starting point. Your instructions can cover anything: how you like to communicate, your preferred tools, personal context the agent should know, writing style, safety rules, or coding conventions. The more specific your instructions, the better OpenCode will work for you.

Edit it anytime

Your AGENTS.md is a plain text file. Ask OpenCode to update it whenever you want to add, change, or remove rules. Changes take effect on the next session.

For example:

Add a rule to my global AGENTS.md: always use semantic commit messages when making git commits.

Initializing a project AGENTS.md

When you start working on a project with OpenCode, you can generate a project-specific AGENTS.md using the /init command. This scans your codebase and creates an AGENTS.md that describes your project’s structure, conventions, and tech stack.

/init

The project AGENTS.md is meant to be committed to Git. It helps OpenCode (and your teammates’ OpenCode sessions) understand the project better.

For more details, see the rules documentation.

Once your global AGENTS.md exists at ~/.config/opencode/AGENTS.md, this lesson is complete.