Skip to content

Commit 83d59aa

Browse files
Copilotgarrytrinder
Copilot
and
garrytrinder
authored
Add AGENTS.md to guide coding agents when contributing new samples (#118)
* Initial plan * Add AGENTS.md to guide coding agents when contributing new samples Co-authored-by: garrytrinder <11563347+garrytrinder@users.noreply.github.com> * Remove msgext- prefix and add AGENT-TYPE metadata key per review feedback Co-authored-by: garrytrinder <11563347+garrytrinder@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: garrytrinder <11563347+garrytrinder@users.noreply.github.com>
1 parent 21cc4a9 commit 83d59aa

1 file changed

Lines changed: 116 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# AGENTS.md
2+
> Instructions for coding agents contributing samples to this repository.
3+
4+
## Purpose
5+
Community sample repository for Microsoft 365 Copilot agents built using code-first approaches.
6+
Read [CONTRIBUTING.md](CONTRIBUTING.md) for full human-oriented guidance.
7+
8+
## Repository layout
9+
| Path | Purpose |
10+
|------|---------|
11+
| `samples/` | One subfolder per sample |
12+
| `samples/_SAMPLE_templates/` | Templates — copy, do not edit |
13+
| `templates/` | Supporting templates |
14+
15+
## Sample folder naming
16+
Prefix the folder name based on sample type:
17+
| Prefix | Type |
18+
|--------|------|
19+
| `da-` | Declarative agent |
20+
| `cea-` | Custom engine agent (Azure Bot Framework) |
21+
22+
Rules: lowercase, hyphens only, no periods.
23+
24+
## Required files
25+
| File | Notes |
26+
|------|-------|
27+
| `assets/sample.json` | See example below |
28+
| `assets/<screenshot>` | At least one `.png`, `.jpg`, or `.gif` |
29+
| `README.md` | Copy correct template (see below) |
30+
| `.gitignore` | Appropriate for toolchain |
31+
| `.env.*.sample` | Redacted copies of all env files |
32+
33+
## sample.json example
34+
```json
35+
[
36+
{
37+
"name": "pnp-copilot-pro-dev-da-example",
38+
"source": "pnp",
39+
"title": "Declarative Agent Example",
40+
"shortDescription": "A declarative agent sample for Microsoft 365 Copilot.",
41+
"url": "https://github.com/pnp/copilot-pro-dev-samples/tree/main/samples/da-example",
42+
"downloadUrl": "https://pnp.github.io/download-partial/?url=https://github.com/pnp/copilot-pro-dev-samples/tree/main/samples/da-example",
43+
"longDescription": [
44+
"A sample project that demonstrates how to build a declarative agent for Microsoft 365 Copilot."
45+
],
46+
"creationDateTime": "2026-01-01",
47+
"updateDateTime": "2026-01-01",
48+
"products": ["Microsoft 365 Copilot"],
49+
"metadata": [
50+
{ "key": "PLATFORM", "value": "Node.js" },
51+
{ "key": "LANGUAGE", "value": "TypeScript" },
52+
{ "key": "AGENT-TYPE", "value": "Declarative Agent" },
53+
{ "key": "API-PLUGIN", "value": "No" },
54+
{ "key": "GRAPH-CONNECTOR", "value": "No" }
55+
],
56+
"thumbnails": [
57+
{
58+
"type": "image",
59+
"order": 100,
60+
"url": "https://github.com/pnp/copilot-pro-dev-samples/raw/main/samples/da-example/assets/example.png",
61+
"alt": "Screenshot of the sample"
62+
}
63+
],
64+
"authors": [
65+
{
66+
"gitHubAccount": "username",
67+
"pictureUrl": "https://github.com/username.png",
68+
"name": "Sample Author"
69+
}
70+
],
71+
"references": [
72+
{
73+
"name": "Microsoft 365 Copilot extensibility",
74+
"description": "Learn more about extensibility.",
75+
"url": "https://learn.microsoft.com/microsoft-365-copilot/extensibility/"
76+
}
77+
]
78+
}
79+
]
80+
```
81+
82+
## README template selection
83+
| Toolchain | Template |
84+
|-----------|----------|
85+
| Teams Toolkit for VS Code | `samples/_SAMPLE_templates/ttk-vs-code-sample/README.md` |
86+
| Teams Toolkit for Visual Studio | `samples/_SAMPLE_templates/ttk-vs-sample/README.md` |
87+
| Other | `samples/_SAMPLE_templates/any-sample/README.md` |
88+
89+
## Schema versions
90+
Always use the latest published schema version. Use the links below to identify the current latest — the version number is in the URL and can be incremented to find newer versions.
91+
92+
| Schema | Reference |
93+
|--------|-----------|
94+
| Teams/M365 `manifest.json` | `$schema: https://developer.microsoft.com/json-schemas/teams/v1.25/MicrosoftTeams.schema.json` (replace `v1.25` with latest) |
95+
| Declarative agent manifest | [declarative-agent-manifest-1.6](https://learn.microsoft.com/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.6) — replace `1.6` with latest |
96+
| API plugin manifest | [api-plugin-manifest-2.4](https://learn.microsoft.com/microsoft-365-copilot/extensibility/api-plugin-manifest-2.4) — replace `2.4` with latest |
97+
98+
## Rules
99+
- Add the sample to the samples table in the root `README.md`
100+
- DO NOT include `projectId` in `m365agents.yml`
101+
- DO NOT commit secrets, API keys, tenant IDs, or app IDs
102+
- DO NOT reference assets from external URLs — all assets in `assets/`
103+
- DO NOT modify files outside the new sample folder
104+
- DO NOT submit more than one sample per pull request
105+
- If the sample contains `teamsapp.yml` or `teamsapp.local.yml`, it was scaffolded with Teams Toolkit (now renamed Microsoft 365 Agents Toolkit) and is likely out of date — update accordingly
106+
- One branch per sample, forked from `main`, PR targets `main`
107+
108+
## Checklist
109+
- [ ] Sample in `/samples/<prefix>-<folder>/`
110+
- [ ] Sample added to the table in root `README.md`
111+
- [ ] Uses correct templates for `README.md` and `sample.json`
112+
- [ ] All schema versions target latest (see links above)
113+
- [ ] No `projectId` in `m365agents.yml`
114+
- [ ] No `teamsapp.yml` or `teamsapp.local.yml` (update if present)
115+
- [ ] No secrets or external asset links
116+
- [ ] One PR per sample

0 commit comments

Comments
 (0)