Customizing Agents

Coding agents are already very capable without customization. But OpenCode provides two customization layers that resemble onboarding a new teammate: rules and skills.

Rules

Rules are AGENTS.md files stored in your repository. OpenCode reads them at the start of each conversation. Think of them as permanent instructions that are always active.

A good rules file is short, specific, and points to examples instead of copying them:

# Project rules

- Use `pnpm` for all package commands.
- Run `pnpm test` before committing.
- Follow the patterns in `src/features/billing/` when adding a new feature module.
- Do not edit generated files under `src/generated/`.

Rules are most effective for:

• Build and test commands the agent needs to know.
• Code conventions the agent must follow.
• References to canonical examples in the codebase.
• Boundaries, such as files not to edit or patterns to avoid.

What to avoid in rules

• Do not write a novel. Long rules consume context in every conversation.
• Do not document every command. Agents already know common tools. Add only project-specific commands.
• Start simple. Rules are included in every conversation, so they accumulate. Add rules only when you see repeated patterns that need correction.

Keep rules in git so your whole team benefits from shared knowledge.

Skills

Skills extend what your agent can do with specialized knowledge and workflows. Unlike rules, which are always active, skills are loaded dynamically by the agent only when relevant.

Skills are defined in SKILL.md files under .opencode/skills/<name>/ and can include domain knowledge, custom workflows, and executable scripts.

Example skill header:

---
name: deploy-staging
description: Deploy to staging. Use when the user asks to deploy, ship, or push to staging.
---

Follow the staging deployment checklist:

1. Run tests.
2. Build the app.
3. Push the Docker image.
4. Update the staging service.

Rules vs skills

Use rules for always-on context. Use skills for workflows that would waste context if loaded every time.

MCP

MCP (Model Context Protocol) lets agents connect to external tools and retrieve relevant context. MCP servers provide tools and resources the agent can use during a conversation.

For example, you can connect an agent to:

• Slack to read messages and send updates.
• Datadog to investigate production logs.
• Sentry to inspect errors and stack traces.
• Databases to query data directly.
• Figma to retrieve design tokens and component specs.

MCP turns the agent into a participant in your real engineering workflow instead of a tool that only knows what you paste into the chat.

Custom commands

In addition to skills that agents load automatically, OpenCode supports custom commands: workflows you invoke yourself by typing /command-name in the TUI. Custom commands live under .opencode/commands/.

For example, a /pr command that commits, pushes, and opens a pull request:

---
description: Create a pull request for the current changes.
---

Run tests, summarize the diff, create semantic commits, push the branch, and open a pull request.

Other workflows that fit custom commands:

• /fix-issue [number]: fetch issue details, find relevant code, fix the bug, and open a PR.
• /review: run linters, check common issues, and summarize review risks.
• /update-deps: check outdated dependencies and update them one by one.

Avoid over-engineering

You may be tempted to write rules for everything. Resist that urge. Too many rules consume context and make it harder for the agent to follow all of them.

Keep your rules minimal and high quality. They should be living team artifacts, not documents written once and forgotten.

What you learned

You learned how to customize agents to match your team's patterns. In the final lesson, you will combine everything you have learned into a complete end-to-end example.