Add initial instructions for AI agents #7765

mcmire · 2026-01-28T17:53:03Z

Explanation

As more and more people use AI tools at the company, we need to make sure that generated code follows the standards that we want engineers to follow as well.

AGENTS.md is a standard that is used by many AI agents (Cursor, Claude Code, etc.). This commit introduces a basic version that describes how the monorepo is structured, how to perform various tasks, and what kind of guidelines to follow.

References

https://consensyssoftware.atlassian.net/browse/WPC-79

Testing

To test these agent rules, I had AI create a controller package. You can see the results here: 88bde44. The only tweaks I made after the initial generation was to fix lint errors, everything else is coming straight from AI.

Checklist

I've updated the test suite for new or updated code as appropriate
I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
I've communicated my changes to consumers by updating changelogs for packages I've changed
I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

Note

Low Risk
Low risk: this PR only adds documentation and does not change runtime code, build output, or dependencies.

Overview
Adds a new AGENTS.md document with repo-specific guidance for AI agents, covering monorepo structure, common Yarn commands (testing/linting/building), changelog expectations, and coding standards for packages/controllers/data services.

^{Written by Cursor Bugbot for commit 9dc59fc. This will update automatically on new commits. Configure here.}

As more and more people use AI tools at the company, we need to make sure that generated code follows the standards that we want engineers to follow as well. `AGENTS.md` is a standard that is used by many AI agents (Cursor, Claude Code, etc.). This commit introduces a basic version that describes how the monorepo is structured, how to perform various tasks, and what kind of guidelines to follow.

cryptodev-2s

Looks good to me, I left a few minor suggestions. We can follow up by adding a “skills” section to each of the existing pattern docs (Data Service, Selectors, etc.).

cryptodev-2s · 2026-01-28T21:19:14Z

AGENTS.md

+### Configuration files
+
+The monorepo uses a hierarchical configuration approach for different tools:
+
+### Contributing teams and codeowners


Suggested change

### Configuration files

The monorepo uses a hierarchical configuration approach for different tools:

### Contributing teams and codeowners

### Configuration files

The monorepo uses a hierarchical configuration approach for different tools. Root-level config files define shared settings, while package-level files extend or customize them.

#### Contributing teams and codeowners

Updated here: 75a2174

cryptodev-2s · 2026-01-28T21:20:11Z

AGENTS.md

+
+- Run `yarn workspace <package-name> run <script>` to run a package script within a package.
+- Run `yarn workspace <package-name> exec <command>` to run a command within a package.
+- Run `yarn workspace foreach --all run <script>` to run a package script across all repos.


Suggested change

- Run `yarn workspace foreach --all run <script>` to run a package script across all repos.

- Run `yarn workspace foreach --all run <script>` to run a package script across all packages.

Updated here: 75a2174

cryptodev-2s · 2026-01-28T21:20:32Z

AGENTS.md

+- Run `yarn workspace <package-name> run <script>` to run a package script within a package.
+- Run `yarn workspace <package-name> exec <command>` to run a command within a package.
+- Run `yarn workspace foreach --all run <script>` to run a package script across all repos.
+- Run `yarn workspace foreach --all exec <command>` to run a command across all repos.


Suggested change

- Run `yarn workspace foreach --all exec <command>` to run a command across all repos.

- Run `yarn workspace foreach --all exec <command>` to run a command across all packages.

Updated here: 75a2174

cryptodev-2s · 2026-01-28T21:21:56Z

AGENTS.md

+- Run `yarn workspace foreach --all run <script>` to run a package script across all repos.
+- Run `yarn workspace foreach --all exec <command>` to run a command across all repos.
+- Run `yarn run <script>` to run a package script defined in the root `package.json`.
+- Run `yarn exec <command>` to run a command available at the root of the project.


Nit: might be worth adding a note on how to add a dependency too.

Suggested change

- Run `yarn exec <command>` to run a command available at the root of the project.

- Run `yarn exec <command>` to run a command available at the root of the project.

- Run `yarn workspace <package-name> add <dependency>` to add a dependency to a specific package.

- Run `yarn workspace <package-name> add -D <dependency>` to add a dev dependency to a specific package.

Good point. Updated here: 75a2174

cryptodev-2s · 2026-01-28T21:24:30Z

AGENTS.md

+- Run `yarn workspace <package-name> run jest --no-coverage <file>` to run a specific test file.
+- Prefer the above two commands, but if you must, run `yarn test` to run tests for all packages in the monorepo.
+
+### Linting and formatting


Nit: should we add a short section here about CI?

Suggested change

### Linting and formatting

### Continuous integration

Pull requests trigger automated checks including:

- **Lint** — Runs ESLint and Prettier to check code quality and formatting.

- **Tests** — Runs Jest tests across affected packages.

- **Type checking** — Ensures TypeScript compiles without errors.

- **Changelog validation** — Verifies changelog entries are properly formatted.

Ensure all checks pass locally before pushing changes.

### Linting and formatting

I think Cursor tends to handle linting and typechecking automatically without my having to tell it what to do. (Claude Code I'm not sure about.)

That said, you're right that there are some missing instructions in the "General development workflow" section. I've added some more words there: 75a2174

cryptodev-2s · 2026-01-28T21:27:34Z

AGENTS.md

+
+### Controllers
+
+When adding or updating controllers in packages, make sure to abide by the guidelines in `docs/controller-guidelines.md`. Use `SampleGasPricesController` and `SamplePetnamesController` in the `sample-controllers` package as examples for implementation and tests.


Nit: maybe worth expanding this a bit more, then we can add “skills” for each of these later.

Suggested change

When adding or updating controllers in packages, make sure to abide by the guidelines in `docs/controller-guidelines.md`. Use `SampleGasPricesController` and `SamplePetnamesController` in the `sample-controllers` package as examples for implementation and tests.

When adding or updating controllers in packages, make sure to abide by the guidelines in `docs/controller-guidelines.md`. Key patterns include:

- Controllers extend `BaseController` and use a messenger for inter-controller communication.

- Actions and events should be explicitly typed on the controller's messenger.

Use `SampleGasPricesController` and `SamplePetnamesController` in the `sample-controllers` package as examples for implementation and tests.

I found that Cursor was basically able to read sample-controllers and figure out what to do. That said, it couldn't hurt. I added some controller guidelines here: 75a2174

cryptodev-2s · 2026-01-28T21:29:04Z

AGENTS.md

+
+### Services
+
+When adding or updating services in packages, use the `sample-gas-prices-service/` directory in the `sample-controllers` package as examples for implementation and tests.


Nit: maybe worth expanding this a bit, feel free to update it.

Suggested change

When adding or updating services in packages, use the `sample-gas-prices-service/` directory in the `sample-controllers` package as examples for implementation and tests.

When adding or updating services in packages, follow these patterns:

- Services encapsulate external API calls and data fetching logic.

- They should be stateless and injectable into controllers.

- Use dependency injection to allow mocking in tests.

Use the `sample-gas-prices-service/` directory in the `sample-controllers` package as examples for implementation and tests.

I found that Cursor was basically able to read sample-controllers and figure out what to do. That said, it couldn't hurt. I added some (data) service guidelines here: 75a2174

cryptodev-2s

LGTM!

mcmire · 2026-01-28T22:32:39Z

We can follow up by adding a “skills” section to each of the existing pattern docs (Data Service, Selectors, etc.).

Agreed!

Add AGENTS.md file with instructions for AI agents that operate on the repository. The goal is to outline our requirements for feature development and any quirks in using the repo. Mostly written by Claude as an experiment, but with edits and guidance from myself. Also with inspiration from MetaMask/core#7765  --- > [!NOTE] > **Low Risk** > Low risk: documentation-only addition plus a small `lint-staged` pattern tweak that only affects formatting behavior for `CLAUDE.md`. No runtime or package code changes. > > **Overview** > Adds `AGENTS.md`, a repository guide for AI coding agents covering stack/tooling, monorepo conventions, build/test/lint commands, changelog requirements, and high-level Snaps platform architecture/naming guidelines. > > Adds `CLAUDE.md` pointing to `AGENTS.md`, and updates `lint-staged` in `package.json` to exclude `CLAUDE.md` (alongside `CHANGELOG.md`) from Prettier formatting. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 4ade350. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup>  --------- Co-authored-by: Maarten Zuidhoorn <maarten@zuidhoorn.com>

mcmire · 2026-01-29T18:38:19Z

Oops, I thought I merged this 😂

cryptodev-2s

LGTM!

mcmire force-pushed the add-agents-config branch from 2108113 to cfb4857 Compare January 28, 2026 18:03

mcmire marked this pull request as ready for review January 28, 2026 18:28

cryptodev-2s reviewed Jan 28, 2026

View reviewed changes

mcmire added 3 commits January 28, 2026 14:53

Adjust barrel exports rule

8b55258

Respond to feedback

75a2174

Tweak

243019b

cryptodev-2s previously approved these changes Jan 28, 2026

View reviewed changes

mcmire enabled auto-merge January 28, 2026 22:31

Merge branch 'main' into add-agents-config

aa098c9

FrederikBolding mentioned this pull request Jan 29, 2026

chore: Add AGENTS.md MetaMask/snaps#3823

Merged

mcmire closed this Jan 29, 2026

auto-merge was automatically disabled January 29, 2026 14:15
Pull request was closed

mcmire deleted the add-agents-config branch January 29, 2026 14:15

mcmire restored the add-agents-config branch January 29, 2026 18:38

mcmire reopened this Jan 29, 2026

Fix lint violation

ded253f

mcmire dismissed cryptodev-2s’s stale review via ded253f January 29, 2026 18:50

Merge branch 'main' into add-agents-config

9dc59fc

mcmire enabled auto-merge January 29, 2026 18:51

cryptodev-2s approved these changes Jan 29, 2026

View reviewed changes

mcmire added this pull request to the merge queue Jan 29, 2026

Merged via the queue into main with commit 6282894 Jan 29, 2026
306 checks passed

mcmire deleted the add-agents-config branch January 29, 2026 19:41

	- Run `yarn workspace foreach --all run <script>` to run a package script across all repos.
	- Run `yarn workspace foreach --all run <script>` to run a package script across all packages.

	- Run `yarn workspace foreach --all exec <command>` to run a command across all repos.
	- Run `yarn workspace foreach --all exec <command>` to run a command across all packages.

-### Linting and formatting
+### Continuous integration
+Pull requests trigger automated checks including:
+- **Lint** — Runs ESLint and Prettier to check code quality and formatting.
+- **Tests** — Runs Jest tests across affected packages.
+- **Type checking** — Ensures TypeScript compiles without errors.
+- **Changelog validation** — Verifies changelog entries are properly formatted.
+Ensure all checks pass locally before pushing changes.
+### Linting and formatting


		### Controllers

		When adding or updating controllers in packages, make sure to abide by the guidelines in `docs/controller-guidelines.md`. Use `SampleGasPricesController` and `SamplePetnamesController` in the `sample-controllers` package as examples for implementation and tests.

-When adding or updating controllers in packages, make sure to abide by the guidelines in `docs/controller-guidelines.md`. Use `SampleGasPricesController` and `SamplePetnamesController` in the `sample-controllers` package as examples for implementation and tests.
+When adding or updating controllers in packages, make sure to abide by the guidelines in `docs/controller-guidelines.md`. Key patterns include:
+- Controllers extend `BaseController` and use a messenger for inter-controller communication.
+- Actions and events should be explicitly typed on the controller's messenger.
+Use `SampleGasPricesController` and `SamplePetnamesController` in the `sample-controllers` package as examples for implementation and tests.


		### Services

		When adding or updating services in packages, use the `sample-gas-prices-service/` directory in the `sample-controllers` package as examples for implementation and tests.

-When adding or updating services in packages, use the `sample-gas-prices-service/` directory in the `sample-controllers` package as examples for implementation and tests.
+When adding or updating services in packages, follow these patterns:
+- Services encapsulate external API calls and data fetching logic.
+- They should be stateless and injectable into controllers.
+- Use dependency injection to allow mocking in tests.
+Use the `sample-gas-prices-service/` directory in the `sample-controllers` package as examples for implementation and tests.

Uh oh!

Add initial instructions for AI agents #7765

Add initial instructions for AI agents #7765

Conversation

mcmire commented Jan 28, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Explanation

References

Testing

Checklist

Uh oh!

cryptodev-2s left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cryptodev-2s Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cryptodev-2s Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cryptodev-2s Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcmire Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cryptodev-2s Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cryptodev-2s left a comment

Choose a reason for hiding this comment

Uh oh!

mcmire commented Jan 28, 2026

Uh oh!

mcmire commented Jan 29, 2026

Uh oh!

cryptodev-2s left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mcmire commented Jan 28, 2026 •

edited by cursor bot

Loading

cryptodev-2s Jan 28, 2026 •

edited

Loading

cryptodev-2s Jan 28, 2026 •

edited

Loading

cryptodev-2s Jan 28, 2026 •

edited

Loading

mcmire Jan 28, 2026 •

edited

Loading

cryptodev-2s Jan 28, 2026 •

edited

Loading