Skip to content

Rewrite Copilot instructions and move to AGENTS.md #53630

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lbussell wants to merge 11 commits into
base: main
Choose a base branch
from
Open

Rewrite Copilot instructions and move to AGENTS.md #53630

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
0bc6693
Remove skills directory link
lbussell Mar 20, 2026
5c368da
Rewrite Copilot instructions
lbussell Mar 20, 2026
747216e
Clean up Copilot instructions
lbussell Mar 23, 2026
c66fd64
Remove recommendation to run all tests
lbussell Mar 30, 2026
b9bdec0
Rework project layout in AGENTS.md
lbussell Mar 30, 2026
16c4bdf
Remove unnecessary lines
lbussell Mar 30, 2026
9cac85c
Simplify and remove unnecessary parts of AGENTS.md
lbussell Apr 6, 2026
4e349fe
Update test path
lbussell Apr 16, 2026
dac83ea
Remove layout content that is self-evident
lbussell Apr 16, 2026
da4f0f4
Update build flag section
lbussell Apr 16, 2026
2b9f2ff
Merge branch 'main' into improve-instructions
lbussell Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 0 additions & 44 deletions .github/copilot-instructions.md
View file
Open in desktop

This file was deleted.

1 change: 0 additions & 1 deletion .github/skills
View file
Open in desktop

This file was deleted.

56 changes: 56 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# dotnet/sdk Repo Overview

This is the .NET SDK repo.
It contains the `dotnet` CLI, MSBuild tasks/targets, project system SDKs, template engine, workload management, and related tooling.
Comment on lines +3 to +4
Copy link
Copy Markdown
Member

@nagilson nagilson Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This is the .NET SDK repo.
It contains the `dotnet` CLI, MSBuild tasks/targets, project system SDKs, template engine, workload management, and related tooling.
The .NET SDK contains the `dotnet` CLI, MSBuild tasks/targets, project system SDKs, template engine, workload management, and related tooling.

nit:
Does the agent need to be told this is the sdk repo? Did that help in any way?

This repo uses https://github.com/dotnet/arcade for build, test, and pipeline infrastructure.
Copy link
Copy Markdown
Member

@nagilson nagilson Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: technically I think 'repo' refers to the digital source storage mechanism, aka 'https://github.com/dotnet/sdk' but this source code folder is not a 'repo' if it is cloned. I don't think this is the best terminology. We could be more concise as well using bullet points instead of full sentences with 'this repo' 'the sdk'


## Local Development Workflow

Use the `.dotnet/dotnet` executable for `dotnet` CLI commands.
It is automatically acquired during the build process.
Do not modify the SDK version specified in `global.json`.

### Build

- Linux/macOS: `./build.sh`
- Windows: `build.cmd`

Useful flags:

- `-bl` - Generate binlog
- `-v <level>` - verbosity: q[uiet], m[inimal], n[ormal], d[etailed], diag[nostic]
- `/p:SomeProperty=value` - Set MSBuild property

The newly built .NET CLI is output to `artifacts/bin/redist/Debug/dotnet/dotnet`.
It can be used to sanity check local changes in a temp directory.

### Test

Do not run the full test suite locally, it takes hours.
Instead, run only the tests relevant to your changes.
Copy link
Copy Markdown
Member

@nagilson nagilson Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Instead, run only the tests relevant to your changes.
Instead: build, then run only relevant tests, like so:

Copy link
Copy Markdown
Member

@nagilson nagilson Apr 23, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'your' confuses context with 3rd person vs first person


After building, run individual test projects:

```bash
# Run all tests in a specific test project
./.dotnet/dotnet test test/<ProjectName>.Tests

Copy link
Copy Markdown
Member

@nagilson nagilson Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we remove the mstest vs xunit bifurcation guide?

# Run a single test by name
./.dotnet/dotnet test test/<ProjectName>.Tests --filter "FullyQualifiedName~TestMethodName"

# Run a single test by class
./.dotnet/dotnet test test/<ProjectName>.Tests --filter "ClassName=Microsoft.DotNet.Cli.SomeTests"
Comment thread
lbussell marked this conversation as resolved.
```

Copy link
Copy Markdown
Member

@nagilson nagilson Apr 23, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you think this is helpful and we should keep this?
Do not manually edit files under documentation/manpages/sdk as these are generated based on documentation and should not be manually modified.

Test projects live in `test/<ProjectName>.Tests` and `test/<ProjectName>.IntegrationTests` (with one exception: `NetAnalyzers` tests live in `src/Microsoft.CodeAnalysis.NetAnalyzers/tests`).

## Project Layout

| Feature | Location |
|---|---|
| `dotnet` CLI (entry point & commands) | `src/Cli/` |
| Template content | `template_feed/` |
| Build infrastructure | `eng/` |
| Arcade infrastructure (do not edit) | `eng/common` |
Copy link
Copy Markdown
Member

@nagilson nagilson Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does the do not edit warning here make agents worse at modifying props / targets for codeflow ?

Copy link
Copy Markdown
Member Author

@lbussell lbussell Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I opened dotnet/arcade#16757 which is a more general solution to keeping agents from messing up eng/common.

| Distributed test orchestration via Helix | `test/UnitTests.proj` |
| Developer documentation | `documentation/` |
Loading