docs: move the agent guide to AGENTS.md and bring it up to date by mmcky · Pull Request #287 · QuantEcon/website

mmcky · 2026-09-29T13:51:20Z

Moves the agent guide from .github/copilot-instructions.md to a tool-agnostic AGENTS.md at the repository root, brings it up to date with main at f3f9ae6, and leaves a short pointer at the old path. Part of QuantEcon/meta#293.

What changes and why

AGENTS.md is now the one guide, for any agent and for people. Copilot code review on github.com, the Copilot cloud agent and CLI, Copilot in VS Code, Claude Code, Codex and Cursor all read a root AGENTS.md (table below), while Claude Code and Codex never read the old path. The first commit moves the file unchanged (plus the exclude: entry), so it shows as a rename, and the second commit shows the rewrite against the old text.
The rewrite follows reports-activity's AGENTS.md: overview, layout, commands, CI, content, gotchas, and pull request and commit conventions. It points to README's "News and Activity", the header comment of _plugins/activity_generator.rb and the scripts rather than restating them. In place of "always reference these instructions first", it says to trust the code where the two disagree and to correct the guide in the same pull request.
.github/copilot-instructions.md is a short pointer to AGENTS.md, as in reports-activity, for the Copilot features that read only that path.
_config.yml excludes AGENTS.md. Otherwise Jekyll would publish it at quantecon.org/AGENTS.md, as it publishes README.md.
PLAN-IMPROVEMENTS.md names the new file. It held the only other mention of the old path.

What the old guide said at f3f9ae6, and what AGENTS.md says instead:

Old guide	`AGENTS.md`
CI runs two checks before the build	`build` has seven steps: checkout, the limit on the reporter's PRs, setup-ruby, the data check with `--base HEAD^1`, `test-check-activity-data.rb`, `test-activity.rb`, then the production build. The guide lists them and gives the local command for each check
Workshops: edit `pages/workshops.md` and the hard-coded list in `_layouts/home.html`	One file per workshop in `_workshops/` (`deb9649`), which both pages loop over
minima is the base theme, and jekyll-feed generates the RSS feed	No theme since `d0c81f0`. `feed.xml` is a hand-written template, which jekyll-feed skips because the file exists
Collections: news, lectures, projects, team-members	lectures, projects, workshops and team-members (`46d24ef` removed `news`), none with pages of its own
`_includes/` holds `quantecon-menubar.html`	Nothing includes it; the navigation is in `_layouts/default.html`
`gem install bundler --user-install`, then a Ruby 3.4 `PATH` line	Bundler comes with Ruby
`jekyll serve --host 0.0.0.0`	The default host: `0.0.0.0` exposes the server to the network and sets `site.url` to `http://0.0.0.0:4000`
All content is Markdown, and the CDNs include AOS and Swiper	Pages are Markdown or HTML, and the CDNs are Bootstrap, Bootstrap Icons, MathJax, Google Fonts and Plotly
A manual walk-through, whose About page step checked the team	Dropped: the team is on `/team/`, and the guide says to check the change on the deploy preview

New in the guide: what Jekyll publishes; the url, timezone and front-matter default traps; where each kind of content goes, including why a post dated in the future doesn't appear and how a Sass partial reaches the brand colours; what jekyll serve doesn't reload; the Activity view's escaping, date and anchor rules; the LoadError that another Ruby's GEM_HOME causes; and the repository's pull request and commit conventions. Those include the three rules for writing to GitHub from the "Writing to GitHub" section of QuantEcon/skills' AGENTS.md, copied in because Copilot review doesn't follow links.

Which tools read which file

From research on 2026-09-29 in each tool's documentation and changelog. Nothing was tested in a live Copilot session.

Tool	Root `AGENTS.md`	`.github/copilot-instructions.md`	`CLAUDE.md`	Evidence
Copilot code review on github.com	Yes, root only, since 2026-06-18	Yes	Yes, per the 2026-07-17 changelog (the support matrix omits it)	support matrix, changelogs of 2026-06-18 and 2026-07-17
Copilot cloud agent	Yes	Yes	Yes	changelog of 2025-08-28, repository instructions
Copilot CLI	Yes	Yes	Yes	CLI custom instructions
Copilot in VS Code, chat and agent mode	Yes, by default since 1.104	Yes	Yes	VS Code custom instructions
Copilot Chat on github.com	No	Yes	No	support matrix
Copilot code review inside an IDE, and chat in Visual Studio, JetBrains, Eclipse and Xcode	No	Yes, except code review in Eclipse, which reads no custom instructions	No	support matrix
Claude Code	Yes, since v2.1.277 (2026-09-18), when no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` is in the working directory or above it	No	Yes	memory docs, CHANGELOG
OpenAI Codex	Yes	No	No	Codex AGENTS.md guide
Cursor	Yes	Not documented	Not documented	Cursor rules
Gemini CLI	Only if listed in `context.fileName`	No	No	GEMINI.md docs

Copilot code review has read these files from the pull request's head branch since 2026-07-17, so this pull request's own review runs with the new layout. Review also needs the repository setting "Use custom instructions when reviewing pull requests", which is on by default; I didn't check its value here.

How it was verified

The site is unchanged. A production build of the branch, compared with a production build of main at f3f9ae6 after normalising the build timestamps: 0 differing files of 329. With the exclude: entry removed, the only difference is a published /AGENTS.md.
Every command in the guide ran in a scratch clone of the branch, on Ruby 4.0.7 with Bundler 4.0.20:
- bundle config set --local path vendor/bundle and bundle install: 10.5 s, and git status stays clean.
- JEKYLL_ENV=production bundle exec jekyll build: 329 files in about a second, with no AGENTS.md.
- bundle exec jekyll serve: 200 on /; the feed's link and og:url read http://localhost:4000; /AGENTS.md is a 404 and /README.md a 200.
- bundle exec jekyll clean: removes _site/ and .jekyll-cache/.
- git fetch origin, then ruby .github/scripts/check-activity-data.rb --base "$(git merge-base HEAD origin/main)": the 40 entries in 23 files are unchanged.
- ruby .github/scripts/test-check-activity-data.rb: 38 runs, 688 assertions, 0 failures, in 11.6 s.
- ruby .github/scripts/test-activity.rb: 51 runs, 27,519 assertions, 0 failures.
Why the merge base. With main simulated one Activity day file ahead of the branch, --base at that main fails with "deleted, but it exists at the base", and --base at the merge base passes. So the guide doesn't use --base origin/main, which would fail that way as soon as the reporter's daily files land on main.
The LoadError line. With chruby's GEM_HOME and GEM_PATH in the environment, ruby .github/scripts/test-activity.rb stops loading mutex_m from chruby's minitest 5.18.1. With the three variables unset, it passes.
Paths and facts. Every path the guide names exists, and every README section it names is a heading there. Its claims were checked against the files at f3f9ae6: for example, no template uses an include tag, the built feed is the hand-written one, and jekyll-4.4.1's serve sets site.url from the host.
Review follow-ups, each checked in a scratch copy of the branch:
- A partial loaded with @use that uses $qe-blue fails the build with "Undefined variable". With var(--qe-blue) it builds.
- A post dated 2026-10-20 is skipped ("has a future date"), and the build exits 0.
- /code/ lists two added code libraries in reverse file-name order, whatever their order.
- jekyll serve regenerates after an edit to _plugins/activity/rows.rb but keeps serving the old plugin's output, and doesn't notice an edit to _config.yml.
- With an older Gemfile.lock in place, bundle install asks for the locked sass-embedded 1.101.0, and bundle update moves to 1.105.0.
- The built home page doesn't contain the body text of index.md, and /team/ shows the three members with role: "Translator" once each, under Translators.
Closing keywords. This body and the four commit messages pass the closing-keyword check.

Choices for review

No CLAUDE.md. From v2.1.277, Claude Code reads a root AGENTS.md by itself when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it, and this repository has none. Claude Code here runs 2.1.284 in VS Code and 2.1.281 in the desktop app; only the claude CLI on PATH is older, at 2.1.280. In local sessions on 2.1.281 and later, in repositories that have an AGENTS.md and no CLAUDE.md, main sessions and workflow-harness subagents alike were given AGENTS.md as project instructions, although the Agent SDK's docs mention only CLAUDE.md. The research still suggested a CLAUDE.md holding only @AGENTS.md, to cover the remaining gaps: versions before 2.1.277, sometimes the first session after upgrading from one, sessions on Bedrock, Vertex or a gateway or with telemetry off on versions before 2.1.281 (both apps here are past it), and anyone who adds a personal CLAUDE.local.md or .claude/CLAUDE.md (.claude/ is gitignored here), which switches native reading off. No Claude session loses anything here, since none read the old path. For that cover, add a CLAUDE.md containing only @AGENTS.md, and add it to exclude:. From v2.1.280, /memory lists AGENTS.md when Claude has read it.
A pointer, not a copy. Copilot code review on github.com reads the root AGENTS.md itself, so the pointer costs it nothing, and there is one copy to keep current. Copilot Chat on github.com and code review run inside an IDE now see only the pointer. A full copy (the QuantEcon.manual pattern) would load twice in every other Copilot surface and drift, and a symlink (the lecture-julia.myst pattern) is undocumented for Copilot on GitHub and loads twice too.
History. A squash merge records AGENTS.md as a new file: after a scratch squash, git log --follow AGENTS.md started at the squash commit. The old history stays under git log -- .github/copilot-instructions.md. Rebase-merging this one pull request, if that method is enabled, would keep the rename on main.
Size. The guide is 123 lines and about 13 KB, up from 195 lines and 8 KB, because it now covers CI, content, gotchas and conventions. Copilot review has had no size cap since 2026-06-12, and Codex reads up to 32 KiB.
Still published. README.md and netlify.toml are copied to quantecon.org as they are. Excluding them would change the site, so this pull request leaves them.

Notes

The CI-check line. This adds the line that Harden the Activity data contract before automatic merges #284 and Compute the Activity rows at build time, with tests #276 left for whichever merged second. activity: harden the data contract before automatic merges #286 merged after activity: compute the Activity rows at build time, with tests #285, and the old guide still listed only the data check and test-activity.rb. AGENTS.md now lists every step of build, including test-check-activity-data.rb and the limit on the reporter's PRs.
Restyle /activity/ with the shared rows, a type filter and day links #277. Its branch should start from main after this merges, or else edit AGENTS.md rather than the old file.
QEP-5. The Code of AI Use's in-brief block isn't pasted in by hand: qe gh agents sync (QuantEcon/cli#50) will add it as a managed block, through its own pull request.
Found while writing, and not changed here:
- _team-members/natasha.md has role: "QuantEcon Early Career Researchers", which matches no section of _layouts/team.html, so she appears nowhere on /team/.
- archive/ is published, and three of its pages are in the sitemap, though nothing links to them.
- pages/2024-11-20-rba-workshop.md has no permalink:, so it publishes at /pages/2024-11-20-rba-workshop.html.
- _includes/quantecon-menubar.html is unused.
- _layouts/code.html doesn't sort by order: /code/ lists code libraries in reverse file-name order, which matches their order values only because of how the three files are named.
- The body of index.md is never rendered, since _layouts/home.html has no {{ content }}.

🤖 Generated with Claude Code

Move .github/copilot-instructions.md, unchanged, to AGENTS.md at the repository root. Copilot code review, the Copilot cloud agent and CLI, Copilot in VS Code, Claude Code, Codex and Cursor all read a root AGENTS.md, while only Copilot reads the old path. The move is a commit of its own, so the branch shows it as a rename. Jekyll would publish a root Markdown file as it is, so _config.yml excludes AGENTS.md. The built site is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Rewrite the guide for any agent or contributor, in the shape of reports-activity's AGENTS.md: overview, layout, commands, CI, content, gotchas, and pull request and commit conventions. It points to README's "News and Activity", the generator's header comment and the scripts rather than restating them, and it says that the code wins where the two disagree, in place of "always reference these instructions first". Out of date in the old text, and corrected: - CI's build job also runs the limit on the reporter's PRs and test-check-activity-data.rb, and the data check takes --base. The guide gives the local form, with the merge base as the base: with --base origin/main, Activity files that main gained after the branch was cut are reported as deleted. - A workshop is one file in _workshops/, not an edit to pages/workshops.md and the home layout. - minima is gone, feed.xml is a hand-written template that jekyll-feed skips, and there is no news collection. - The navigation is in _layouts/default.html; _includes/ is unused. - Bundler comes with Ruby, so the gem install and PATH steps are gone, and jekyll serve keeps its default host: 0.0.0.0 exposes the server and rewrites site.url. - Pages are Markdown or HTML, and the CDN list matches the layouts (no AOS or Swiper). New: what Jekyll publishes, the url, timezone and front-matter default traps, where each kind of content goes, the Activity view's escaping, date and anchor rules, the LoadError that another Ruby's GEM_HOME causes, and the repository's pull request and commit conventions, with the rules for writing to GitHub. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot code review has read a root AGENTS.md since June 2026, as do the Copilot cloud agent, the Copilot CLI and Copilot in VS Code. So the old path keeps only a short pointer, as in reports-activity, for the Copilot features that read nothing else: Copilot Chat on github.com and code review run inside an IDE. There is one copy of the guide to keep current. PLAN-IMPROVEMENTS.md's note on the guide now names AGENTS.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@use

Each was checked in a scratch copy of the branch: - jekyll serve rebuilds on changes to content, layouts and assets, but reads _config.yml and loads _plugins/ only when it starts, so restart it after editing either. - A Sass partial loaded with @use can't see main.scss's variables (the build fails with "Undefined variable"), so partials use the --qe-* custom properties, as _about.scss does. - The build skips a post dated in the future and still passes, so an announcement of something still to come takes the day it is published. - index.md sets only the home page's URL and layout: home.html has no {{ content }}, so the home page is edited in that layout. - /code/ ignores order and lists code libraries in reverse file-name order; order places lectures and books. - A translator with no other role has role "Translator", which matches no section, and appears only under Translators. - The gitignored Gemfile.lock that a first bundle install writes keeps local gem versions until bundle update, while CI, the deploy and Netlify resolve fresh ones on every run. The CI section now says to change it along with the workflow and its test. The Copilot pointer says which Copilot features read AGENTS.md directly: code review on GitHub.com does, code review in an IDE doesn't. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

netlify · 2026-09-29T13:51:28Z

✅ Deploy Preview for grand-swan-ca5201 ready!

Name	Link
🔨 Latest commit	`9699a0c`
🔍 Latest deploy log	https://app.netlify.com/projects/grand-swan-ca5201/deploys/6abbc25b20f9430008096680
😎 Deploy Preview	https://deploy-preview-287--grand-swan-ca5201.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Copilot

Copilot review overview

🟢 Approval recommended

It is a documentation-only migration whose factual claims and the one-line _config.yml exclude were verified accurate against the codebase, with no code-behavior impact.

Review effort: Balanced
Findings: None

What changed in this PR

This PR migrates the agent/contributor guide from .github/copilot-instructions.md to a tool-agnostic AGENTS.md at the repository root, brings the content up to date with main, and leaves the old path as a short pointer. It supports standardizing on the AGENTS.md convention read by multiple AI coding tools, while keeping the site build unaffected. It is part of QuantEcon/meta#293.

Changes:

Add AGENTS.md at the repo root as the single canonical guide (overview, layout, commands, CI, content, gotchas, PR/commit conventions), updated to reflect current CI, plugins, theming, and collections.
Reduce .github/copilot-instructions.md to a pointer to AGENTS.md for Copilot surfaces that only read that path.
Exclude AGENTS.md from the Jekyll build in _config.yml and update the stale reference in PLAN-IMPROVEMENTS.md.

File	Description
`AGENTS.md`	New canonical guide; content verified accurate against build.yml, README, layouts, Gemfile, plugins, and scripts.
`.github/copilot-instructions.md`	Trimmed to a pointer to `../AGENTS.md`; relative link resolves correctly.
`_config.yml`	Adds `AGENTS.md` to `exclude:` so Jekyll does not publish it at `/AGENTS.md`.
`PLAN-IMPROVEMENTS.md`	Updates the note to name `AGENTS.md` as the current guide.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

mmcky and others added 4 commits September 29, 2026 22:58

mmcky marked this pull request as ready for review September 29, 2026 21:36

Copilot AI balanced review requested due to automatic review settings September 29, 2026 21:36

Copilot started reviewing on behalf of mmcky September 29, 2026 21:37 View session

Copilot AI reviewed Sep 29, 2026

View reviewed changes

mmcky merged commit 8cba18b into main Sep 29, 2026
6 checks passed

mmcky deleted the agents-md branch September 29, 2026 21:42

Navigation Menu

Repository navigation

docs: move the agent guide to AGENTS.md and bring it up to date - #287

docs: move the agent guide to AGENTS.md and bring it up to date#287
mmcky merged 4 commits into
mainfrom
agents-md

mmcky commented Sep 29, 2026

Uh oh!

netlify Bot commented Sep 29, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

mmcky commented Sep 29, 2026

What changes and why

Which tools read which file

How it was verified

Choices for review

Notes

Uh oh!

netlify Bot commented Sep 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for grand-swan-ca5201 ready!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟢 Approval recommended

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

netlify Bot commented Sep 29, 2026 •

edited

Loading