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:

## Communication

- Be concise and direct. Avoid unnecessary filler.
- Explain what you're about to do before making changes.
- If you're unsure about something, ask instead of guessing.

## Safety

- Ask before deleting any files or directories.
- Don't modify .env files without explicit permission.
- Don't push to git without asking first.

## Style

- Use TypeScript when possible.
- Prefer named exports over default exports.
- Write comments only when the code isn't self-explanatory.

This is just a starting point. The beauty of AGENTS.md is that you can make it as specific as you want. Prefer tabs over spaces? Say so. Want OpenCode to always write tests? Add that rule. Hate emoji in commit messages? Put it in writing.

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.