Add AI agent instructions by edgchen1 · Pull Request #27856 · microsoft/onnxruntime

edgchen1 · 2026-03-26T01:31:33Z

Description

Initial pass at some AI agent instructions for this repo.

Following some conventions:

Add repository instructions for AI agents covering:

Build system phases (--update/--build/--test) and key flags
High-level architecture (graph, optimizer, session, providers)
C++ conventions (error macros, container types, span/string_view preferences)
Python conventions and testing patterns
C API guidelines and PR expectations

Sourced from existing docs (CONTRIBUTING.md, docs/Coding_Conventions_and_Standards.md, docs/PR_Guidelines.md, docs/C_API_Guidelines.md) and codebase inspection.

Copilot put most of this together.

Motivation and Context

Trying to help AI agents work better in this repo. Just getting some initial instructions in place. We should refine it.

Add repository instructions for GitHub Copilot sessions covering: - Build system phases (update/build/test) and key flags - High-level architecture (graph, optimizer, session, providers) - C++ conventions (error macros, container types, span/string_view) - Python conventions and testing patterns - C API guidelines and PR expectations Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

edgchen1 · 2026-03-26T01:35:12Z

FYI - This is what I got when I ran /init in Copilot CLI and then refined it a bit.

also renamed it to AGENTS.md to hopefully make it more general.

Copilot

Pull request overview

Adds a new repository-level .github/copilot-instructions.md intended to guide GitHub Copilot sessions with ONNX Runtime-specific build, architecture, coding conventions, C API guidance, and PR expectations.

Changes:

Introduces a Copilot instruction document covering build/test/lint workflows and key flags.
Summarizes core architecture (graph/optimizer/framework/session/providers) and contrib/training structure.
Captures C++/Python/C API conventions and PR guidelines in a single reference.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

fs-eire · 2026-03-26T21:59:42Z

I have 2 suggestions:

keep it short. the current content seems too long for an AGENTS.md
make it multiple files and use the main AGENTS.md and an index, to make it load on demand. (the idea of SKILLs)

- Add build duration section advising agents to run builds in the background and redirect output to a file for long builds - Document --target and --targets flags for building specific CMake targets - Add example for building a single target - Update workflow to mention continuing with other tasks during build Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Advise agents to use an isolated virtual environment before building or testing, since those processes may install Python dependencies. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

edgchen1 · 2026-03-31T02:17:45Z

@fs-eire @justinchuby thanks for the suggestions of moving some information to skills.

I'm new to this, so I am not sure what the appropriate scope of a skill is.

Copilot came up with some initial skills. I asked it again afterwards:

❯ please take a look at AGENTS.md. do you think any information there would be better suited as a separate skill?

● Read AGENTS.md
  └ 119 lines read

● I think the current AGENTS.md is well-structured as-is. Everything there is appropriate for "always loaded" context — it's concise reference material an agent needs regardless of the task:

   - Architecture Overview — essential context for navigating any code change
   - C++/Python/C API Conventions — coding style rules needed when writing any code
   - Python Environment — lightweight, cross-cutting guidance
   - PR Guidelines — always relevant when preparing changes

  Skills are best for procedural workflows (step-by-step "how to do X") that are only needed on demand. The three existing skills (build, test, lint) fit that pattern well.

  The one section I could see an argument for extracting is C API Conventions — it's only relevant when modifying the public C API, which is a narrow use case. But it's short enough (10 lines) that the context cost of keeping it in AGENTS.md is
  minimal, and making it a skill would add overhead for little benefit.

  Bottom line: I wouldn't move anything out. The file is ~120 lines, which is a reasonable size for always-on context, and everything there has broad applicability.

if you have other ideas about what should be moved into a skill, or just removed from AGENTS.md, please let me know.

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

justinchuby · 2026-03-31T16:30:55Z

@fs-eire @justinchuby thanks for the suggestions of moving some information to skills.

I'm new to this, so I am not sure what the appropriate scope of a skill is.

Copilot came up with some initial skills. I asked it again afterwards:

❯ please take a look at AGENTS.md. do you think any information there would be better suited as a separate skill?

● Read AGENTS.md
  └ 119 lines read

● I think the current AGENTS.md is well-structured as-is. Everything there is appropriate for "always loaded" context — it's concise reference material an agent needs regardless of the task:

   - Architecture Overview — essential context for navigating any code change
   - C++/Python/C API Conventions — coding style rules needed when writing any code
   - Python Environment — lightweight, cross-cutting guidance
   - PR Guidelines — always relevant when preparing changes

  Skills are best for procedural workflows (step-by-step "how to do X") that are only needed on demand. The three existing skills (build, test, lint) fit that pattern well.

  The one section I could see an argument for extracting is C API Conventions — it's only relevant when modifying the public C API, which is a narrow use case. But it's short enough (10 lines) that the context cost of keeping it in AGENTS.md is
  minimal, and making it a skill would add overhead for little benefit.

  Bottom line: I wouldn't move anything out. The file is ~120 lines, which is a reasonable size for always-on context, and everything there has broad applicability.

if you have other ideas about what should be moved into a skill, or just removed from AGENTS.md, please let me know.

That sounds reasonable. As this grow we can then split. I think of topics like "how to create a new kernel for an op", etc. belonging to a skill.

- AGENTS.md: Broaden contrib ops registration to list all EP-specific files - ort-build: Update --use_cuda flag docs, add build output path details, consolidate and streamline content - ort-test: Fix macOS platform name, add VS multi-config path info, consolidate and streamline content - ort-lint: Add coding standards doc reference, 80-char line preference, consolidate and streamline content Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Merge Python Environment and Python Conventions under one heading - Add coding standards doc reference and 80-char aim to C++ style - Trim verbose source paths from container types - Consolidate C API header locations - Minor wording and formatting cleanup Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Fix CMake file discovery wording (mix of globs and explicit lists) - Note that --target requires --build Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

When --test is explicitly provided, the build script only runs the test phase. Add a note that this assumes a prior successful build. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

### Description Add a pre-commit [git hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) that runs lintrunner on staged files, catching lint and formatting issues before they reach CI. The hook runs lintrunner in check-only mode (no auto-fix) to avoid issues with partial staging. If lint issues are found, the commit is blocked and the developer is prompted to run `lintrunner -a` to fix. The hook is opt-in. Contributors enable it with: `git config core.hooksPath .githooks` ### Motivation and Context Follow-up from #27856. Catching lint issues at commit time saves CI cycles and review time.

edgchen1 requested a review from Copilot March 26, 2026 01:33

Copilot started reviewing on behalf of edgchen1 March 26, 2026 01:34 View session

Copilot AI reviewed Mar 26, 2026

View reviewed changes

Comment thread .github/copilot-instructions.md Outdated

Comment thread .github/copilot-instructions.md Outdated

Comment thread .github/copilot-instructions.md Outdated

Comment thread AGENTS.md Outdated

Comment thread .github/copilot-instructions.md Outdated

Apply suggestions from code review

408d4a6

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

edgchen1 requested a review from Copilot March 26, 2026 17:27

Copilot started reviewing on behalf of edgchen1 March 26, 2026 17:29 View session

Copilot AI reviewed Mar 26, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

edgchen1 added 2 commits March 26, 2026 11:24

rename to agents.md, some tweaks

acfbdff

refine note about macros

54cb183

edgchen1 changed the title ~~Add .github/copilot-instructions.md~~ Add AGENTS.md Mar 26, 2026

edgchen1 requested a review from Copilot March 26, 2026 18:33

Copilot started reviewing on behalf of edgchen1 March 26, 2026 18:34 View session

Copilot AI reviewed Mar 26, 2026

View reviewed changes

Comment thread AGENTS.md

Comment thread AGENTS.md Outdated

Comment thread AGENTS.md Outdated

add .agents/skills - initial pass at skills

f2b4c4d

justinchuby reviewed Mar 30, 2026

View reviewed changes

Comment thread AGENTS.md

justinchuby reviewed Mar 30, 2026

View reviewed changes

Comment thread AGENTS.md

edgchen1 and others added 4 commits March 30, 2026 18:21

update AGENTS.md to refer to skills

9b9e5b4

note that training code is not actively developed

f5e42b7

Add Python environment guidance to AGENTS.md

b7b681e

Advise agents to use an isolated virtual environment before building or testing, since those processes may install Python dependencies. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

edgchen1 changed the title ~~Add AGENTS.md~~ Add AI agent instructions Mar 31, 2026

edgchen1 requested a review from Copilot March 31, 2026 02:21

Copilot started reviewing on behalf of edgchen1 March 31, 2026 02:22 View session

Copilot AI reviewed Mar 31, 2026

View reviewed changes

Comment thread .agents/skills/ort-test/SKILL.md Outdated

Comment thread .agents/skills/ort-test/SKILL.md Outdated

Comment thread .agents/skills/ort-build/SKILL.md Outdated

Comment thread AGENTS.md Outdated

remove note about training code. we can document this elsewhere first

0735973

edgchen1 added 5 commits March 31, 2026 12:26

some updates to ort-build/SKILL.md by copilot

1ac30f4

remove specific EP options as they probably aren't common

53c0d6e

update ort-build skill

7891228

update ort-lint

f5db746

update ort-test

5b852c3

skottmckay reviewed Apr 1, 2026

View reviewed changes

Comment thread .agents/skills/ort-lint/SKILL.md Outdated

skottmckay reviewed Apr 1, 2026

View reviewed changes

Comment thread .agents/skills/ort-lint/SKILL.md Outdated

skottmckay reviewed Apr 1, 2026

View reviewed changes

Comment thread .agents/skills/ort-test/SKILL.md Outdated

skottmckay reviewed Apr 1, 2026

View reviewed changes

Comment thread AGENTS.md

justinchuby previously approved these changes Apr 1, 2026

View reviewed changes

edgchen1 and others added 5 commits April 1, 2026 19:52

more updates from another session

02bf842

Update Python environment references in skill files

f526717

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Minor accuracy fixes from review

00feb60

- Fix CMake file discovery wording (mix of globs and explicit lists) - Note that --target requires --build Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

edgchen1 dismissed justinchuby’s stale review via 00feb60 April 2, 2026 04:13

edgchen1 commented Apr 2, 2026

View reviewed changes

Comment thread .agents/skills/ort-lint/SKILL.md

edgchen1 requested review from Copilot, justinchuby, skottmckay and yuslepukhin April 2, 2026 04:33

Copilot started reviewing on behalf of edgchen1 April 2, 2026 04:37 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

Comment thread .agents/skills/ort-test/SKILL.md

Comment thread .agents/skills/ort-build/SKILL.md

Comment thread .agents/skills/ort-test/SKILL.md

Clarify --test assumes a prior successful build

0fe6642

When --test is explicitly provided, the build script only runs the test phase. Add a note that this assumes a prior successful build. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

justinchuby approved these changes Apr 7, 2026

View reviewed changes

edgchen1 enabled auto-merge (squash) April 7, 2026 23:20

edgchen1 merged commit c2e040a into main Apr 7, 2026
105 of 108 checks passed

edgchen1 deleted the edgchen1/add_copilot_instructions branch April 7, 2026 23:54

vraspar mentioned this pull request Apr 8, 2026

Add pre-commit git hook to run lintrunner on staged files #28013

Merged

Conversation

edgchen1 commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and Context

Uh oh!

edgchen1 commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fs-eire commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

edgchen1 commented Mar 31, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

justinchuby commented Mar 31, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

edgchen1 commented Mar 26, 2026 •

edited

Loading

edgchen1 commented Mar 26, 2026 •

edited

Loading

fs-eire commented Mar 26, 2026 •

edited

Loading