From 705132bd6cc1483aec798cce5ff2dbb399c9584f Mon Sep 17 00:00:00 2001 From: Elliot Margot Date: Fri, 1 May 2026 12:44:29 +0200 Subject: [PATCH] docs: add AGENTS.md to help AI coding tools understand the repo --- AGENTS.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..db8589f2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,132 @@ +# AGENTS.md - Copilot Developer Camp + +This file helps AI coding assistants understand the repository structure, conventions, and workflows for [Copilot Developer Camp](https://aka.ms/copilotdevcamp) - a self-paced lab resource for extending Microsoft 365 Copilot and building custom engine agents. + +--- + +## Repository Overview + +| Path | Purpose | +|---|---| +| `docs/` | All MkDocs site content (lab markdown, assets, JS, CSS) | +| `docs/pages/` | Lab content organized by learning path | +| `docs/assets/` | Images, badge artwork, logos | +| `docs/includes/` | Shared markdown snippets (used via `pymdownx.snippets`) | +| `docs/ja/` | Japanese translations (mirrors English structure) | +| `docs/javascripts/` | Custom JS for award tracking, lab navigation, adaptive cards | +| `docs/stylesheets/` | Custom CSS overrides for the Material theme | +| `src/` | Sample source code referenced by labs | +| `mkdocs.yml` | MkDocs configuration - nav structure, plugins, theme settings | +| `README.md` | Repo overview and quick sample index | + +--- + +## Lab Structure and Naming Conventions + +Labs are organized under `docs/pages/` by learning path. Each path has its own prefix: + +| Prefix | Learning Path | Folder | +|---|---|---| +| `E` | Declarative Agents | `docs/pages/extend-m365-copilot/` | +| `BMA` | Custom Engine - M365 Agents SDK + Microsoft Foundry | `docs/pages/custom-engine/agents-sdk/` | +| `BAF` | Custom Engine - Agent Framework | `docs/pages/custom-engine/agent-framework/` | +| `MCS` | No-code/low-code - Microsoft Copilot Studio | `docs/pages/make/copilot-studio/` | +| `MAB` | No-code/low-code - Agent Builder | `docs/pages/make/agent-builder/` | +| `MSA` | No-code/low-code - Custom SharePoint Agents | `docs/pages/make/sharepoint-agents/` | + +**File naming:** `NN-short-description.md` where `NN` is zero-padded (e.g., `00-prerequisites.md`, `01-first-agent.md`, `08-mcp-server.md`). + +**Every learning path has:** +- An `index.md` (welcome/overview page) +- A `00-prerequisites.md` (setup and environment) +- Numbered lab files for each step + +--- + +## Running the Docs Site Locally + +```bash +# Install dependencies (Python 3.8+ required) +pip install mkdocs-material +pip install mkdocs-static-i18n + +# Serve with live reload +mkdocs serve +``` + +Site is available at `http://127.0.0.1:8000`. The `site/` output folder is git-ignored. + +Alternatively with Docker: + +```bash +docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material serve --dev-addr=0.0.0.0:8000 +``` + +--- + +## Adding or Editing Lab Content + +1. Create or edit the markdown file in the appropriate `docs/pages//` folder. +2. Add the new file to the `nav:` section of `mkdocs.yml` (under both `en` and `ja` locales if translating). +3. For shared content (repeated across labs), add a snippet to `docs/includes/` and reference it with: + ```markdown + --8<-- "snippet-name.md" + ``` +4. Images go in `docs/assets/images/`. Use relative paths in markdown. +5. For lab step navigation buttons, use the custom `cc-next.js` class (see existing labs for the pattern). + +**Admonition blocks** (used heavily throughout the labs): +```markdown +!!! note + Text here + +!!! tip "Custom title" + Text here + +??? warning "Collapsible" + Text here +``` + +--- + +## JavaScript and Award Logic + +| File | Purpose | +|---|---| +| `docs/javascripts/cc-award.js` | Badge award tracking and Credly integration | +| `docs/javascripts/cc-next.js` | Lab step navigation (Next/Previous buttons) | +| `docs/javascripts/cc-lab-step.js` | In-page lab step rendering | +| `docs/javascripts/cc-card.js` | Card layout rendering | + +--- + +## Source Code Samples + +Sample code for labs lives in `src/`. Each subfolder corresponds to a lab path. Labs reference the source via GitHub links in the markdown rather than embedding code inline. + +--- + +## i18n (Translations) + +English is the default locale. Japanese (`ja`) translations mirror the English folder structure under `docs/ja/`. When adding English content, add a corresponding entry in the `ja:` locale nav in `mkdocs.yml` even if the translation is not yet available (use the file path without a label to inherit the English version). + +--- + +## Contribution Checklist + +- [ ] Lab markdown follows the existing heading and admonition style +- [ ] New lab file is added to the `nav:` in `mkdocs.yml` (English locale at minimum) +- [ ] `mkdocs serve` runs without errors or warnings +- [ ] Images are in `docs/assets/images/` and referenced with relative paths +- [ ] No hardcoded tenant IDs, client IDs, or secrets in any file +- [ ] CLA bot check passes (required for all external contributors) + +--- + +## Key Contacts and Resources + +- Issues: https://github.com/microsoft/copilot-camp/issues +- Discussions: https://github.com/microsoft/copilot-camp/discussions +- Awards: https://microsoft.github.io/copilot-camp/awards/ +- Community Recognition Program: https://aka.ms/community/recognition-register +- Sample Solution Gallery: https://aka.ms/community/samples