Skip to content

Commit 9a45ca4

Browse files
WilliamBerryiiiBill Berry
WilliamBerryiii
and
Bill Berry
authored
docs(reference): add copilot artifacts documentation hub (#170)
## Description Added a centralized reference page documenting all 12 project-specific GitHub Copilot extensibility artifacts — agents, instructions, prompts, and skills. The new hub at *docs/reference/copilot-artifacts.md* provides an inventory table, quick-reference task mapping, detailed per-type sections, and workflow chain diagrams showing how artifacts compose into end-to-end workflows. Supporting changes integrated the new page into existing documentation: an **Agentic Tooling** section in the architecture guide explains loading mechanisms and the HVE-Core shared library, cross-references link from *prerequisites.md* and the reference *README.md*, and two new terms were added to the spelling dictionary. ## Type of Change - [ ] 🐛 Bug fix (non-breaking change fixing an issue) - [ ] ✨ New feature (non-breaking change adding functionality) - [ ] 💥 Breaking change (fix or feature causing existing functionality to change) - [x] 📚 Documentation update - [ ] 🏗️ Infrastructure change (Terraform/IaC) - [ ] ♻️ Refactoring (no functional changes) ## Component(s) Affected - [ ] `deploy/000-prerequisites` - Azure subscription setup - [ ] `deploy/001-iac` - Terraform infrastructure - [ ] `deploy/002-setup` - OSMO control plane / Helm - [ ] `deploy/004-workflow` - Training workflows - [ ] `src/training` - Python training scripts - [x] `docs/` - Documentation ## Testing Performed - [ ] Terraform `plan` reviewed (no unexpected changes) - [ ] Terraform `apply` tested in dev environment - [ ] Training scripts tested locally with Isaac Sim - [ ] OSMO workflow submitted successfully - [ ] Smoke tests passed (`smoke_test_azure.py`) ## Documentation Impact - [ ] No documentation changes needed - [x] Documentation updated in this PR - [ ] Documentation issue filed ## Bug Fix Checklist *Not applicable — documentation update.* ## Checklist - [x] My code follows the [project conventions](copilot-instructions.md) - [x] Commit messages follow [conventional commit format](instructions/commit-message.instructions.md) - [x] I have performed a self-review - [x] Documentation impact assessed above - [x] No new linting warnings introduced Co-authored-by: Bill Berry <wbery@microsoft.com>
1 parent 8adde50 commit 9a45ca4

5 files changed

Lines changed: 232 additions & 0 deletions

File tree

‎.cspell/general-technical.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ acunetix
88
adobe
99
adrm
1010
adrs
11+
agentic
1112
agentless
1213
agile
1314
anom
@@ -160,6 +161,7 @@ chatbot
160161
chatbots
161162
chatmode
162163
chatmodes
164+
chatlog
163165
cheatham
164166
checkbox
165167
checkboxes

‎docs/contributing/architecture.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -177,6 +177,56 @@ This repository will not maintain a separate codebase domain for simulation. Ins
177177
- Designing Isaac Lab environments using Manager-based and Direct workflows
178178
- Connecting simulation outputs to the Synthetic Data and Training domains
179179

180+
## Agentic Tooling
181+
182+
This project uses [GitHub Copilot](https://code.visualstudio.com/docs/copilot/overview) agents, instructions, prompts, and skills to automate development workflows. Tooling comes from two sources: the HVE-Core extension (shared across Microsoft HVE projects) and project-specific artifacts defined in `.github/`.
183+
184+
### HVE-Core Extension
185+
186+
The [hve-core-all](https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core-all) VS Code extension provides shared agentic tooling:
187+
188+
| Artifact Type | Count | Examples |
189+
|---------------|-------|----------|
190+
| Agents | 33 | RPI workflow, backlog management, PR creation |
191+
| Instructions | 24 | Coding standards (Bash, C#, Python, Terraform, Bicep), commit messages, markdown |
192+
| Prompts | 27 | ADO work items, GitHub issues, security planning, PR descriptions |
193+
| Skills | 2 | PR reference generation, video-to-GIF conversion |
194+
195+
HVE-Core artifacts are registered via the extension's `package.json` `contributes` section and loaded when the extension activates.
196+
197+
### Project Copilot Artifacts
198+
199+
This repository defines project-specific artifacts in `.github/` that extend HVE-Core with domain knowledge:
200+
201+
| Artifact Type | Count | Purpose |
202+
|---------------|-------|----------|
203+
| Agents | 2 | OSMO training manager, dataviewer developer |
204+
| Instructions | 4 | Copilot instructions, dataviewer conventions, documentation style, shell scripts |
205+
| Prompts | 4 | OSMO training submission, LeRobot pipeline, dataviewer workflows |
206+
| Skills | 2 | Dataviewer interaction, OSMO LeRobot training |
207+
208+
Project artifacts are auto-discovered by VS Code from the `.github/` directory without explicit registration.
209+
210+
Two workflow chains compose these artifacts:
211+
212+
- **OSMO Training Manager**: `osmo-training-manager` agent → `osmo-lerobot-training` skill → training submission prompts
213+
- **Dataviewer Developer**: `dataviewer-developer` agent → `dataviewer` skill → dataviewer instruction conventions
214+
215+
### Artifact Types and Loading
216+
217+
Each artifact type uses YAML frontmatter to declare behavior:
218+
219+
| Artifact | File Pattern | Key Frontmatter | Loading |
220+
|----------|-------------|-----------------|----------|
221+
| Agents | `*.agent.md` | `mode`, `tools`, `description` | Auto-discovered from `.github/agents/` |
222+
| Instructions | `*.instructions.md` | `applyTo`, `description` | Auto-discovered from `.github/instructions/` |
223+
| Prompts | `*.prompt.md` | `mode`, `description`, `tools` | Auto-discovered from `.github/prompts/` |
224+
| Skills | `SKILL.md` | N/A (referenced by agents) | Referenced via `copilot-skill:` URI |
225+
226+
HVE-Core artifacts follow the same patterns but load through extension contribution points rather than workspace auto-discovery.
227+
228+
For the detailed per-artifact inventory and workflow chain diagrams, see [Copilot Artifacts](../reference/copilot-artifacts.md).
229+
180230
## Agent Skills and Specification Documents
181231

182232
Each domain will contain specification documents alongside working examples. These specifications serve as structured inputs for [GitHub Copilot Agent Skills](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode), enabling customers to adapt this reference architecture to their own codebase and infrastructure.

‎docs/contributing/prerequisites.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -189,6 +189,8 @@ The workspace `.vscode/settings.json` also configures Copilot Chat to load instr
189189

190190
These paths resolve when hve-core is installed as a peer directory or via the VS Code Extension. Without hve-core, Copilot still functions but shared conventions, prompts, and chat modes are unavailable.
191191

192+
For a complete list of available agents, prompts, and skills, see [Copilot Artifacts](../reference/copilot-artifacts.md).
193+
192194
## Related Documentation
193195

194196
* [Contributing Guide](README.md) - Main contributing guide with all sections

‎docs/reference/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ Technical reference documentation for submission scripts, workflow templates, en
2020
|----------------------------------------|--------------------------------------------------------------------|-------------|
2121
| [Script Reference](scripts.md) | Submission script inventory, CLI arguments, and configuration | Available |
2222
| [Script Examples](scripts-examples.md) | Detailed examples for training, inference, and pipeline submission | Available |
23+
| [Copilot Artifacts](copilot-artifacts.md) | Agents, instructions, prompts, and skills inventory | Available |
2324
| Workflow Templates | AzureML and OSMO workflow YAML templates and configuration | Coming soon |
2425
| Terraform Variables | Terraform input variables and outputs reference | Coming soon |
2526
| Environment Variables | Environment variables for training and deployment | Coming soon |

‎docs/reference/copilot-artifacts.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
---
2+
title: Copilot Artifacts
3+
description: >-
4+
Inventory and reference for GitHub Copilot agents, instructions, prompts,
5+
and skills configured in this repository.
6+
author: Microsoft Robotics-AI Team
7+
ms.date: 2026-03-11
8+
ms.topic: reference
9+
keywords:
10+
- copilot
11+
- agents
12+
- instructions
13+
- prompts
14+
- skills
15+
- extensibility
16+
---
17+
18+
GitHub Copilot extensibility artifacts provide AI-assisted workflows
19+
for dataset analysis, training job management, and coding standards
20+
enforcement. These artifacts are configured in `.github/` and activate
21+
automatically in VS Code.
22+
23+
## 📋 Artifact Inventory
24+
25+
| Type | Name | Description | Path |
26+
|-------------|------------------------------|------------------------------------------------------|------------------------------------------------------------------|
27+
| Agent | Dataviewer Developer | Interactive dataset analysis and tool development | `.github/agents/dataviewer-developer.agent.md` |
28+
| Agent | OSMO Training Manager | LeRobot training lifecycle on OSMO with Azure ML | `.github/agents/osmo-training-manager.agent.md` |
29+
| Instruction | Commit Messages | Conventional Commits format for all commit messages | `.github/instructions/commit-message.instructions.md` |
30+
| Instruction | Dataviewer | Coding standards for dataviewer development | `.github/instructions/dataviewer.instructions.md` |
31+
| Instruction | Docs Style and Conventions | Writing standards for all markdown files | `.github/instructions/docs-style-and-conventions.instructions.md`|
32+
| Instruction | Shell Scripts | Implementation standards for bash scripts | `.github/instructions/shell-scripts.instructions.md` |
33+
| Prompt | `/chatlog` | Create and maintain conversation logs | `.github/prompts/chatlog.prompt.md` |
34+
| Prompt | `/check-training-status` | Monitor OSMO training job progress | `.github/prompts/check-training-status.prompt.md` |
35+
| Prompt | `/start-dataviewer` | Launch Dataset Analysis Tool | `.github/prompts/start-dataviewer.prompt.md` |
36+
| Prompt | `/submit-lerobot-training` | Submit LeRobot training job to OSMO | `.github/prompts/submit-lerobot-training.prompt.md` |
37+
| Skill | dataviewer | Dataset browsing, annotation, and export | `.github/skills/dataviewer/SKILL.md` |
38+
| Skill | osmo-lerobot-training | Training submission, monitoring, and analysis | `.github/skills/osmo-lerobot-training/SKILL.md` |
39+
40+
## 🔗 Quick Reference
41+
42+
| Want to... | Use this artifact |
43+
|-------------------------------------------|----------------------------------------------------------|
44+
| Launch the Dataset Analysis Tool | `/start-dataviewer` prompt → Dataviewer Developer |
45+
| Browse and annotate training episodes | Dataviewer Developer agent |
46+
| Submit a LeRobot training job | `/submit-lerobot-training` prompt → OSMO Training Manager|
47+
| Check training job status | `/check-training-status` prompt → OSMO Training Manager |
48+
| Save a conversation log | `/chatlog` prompt |
49+
| Enforce commit message standards | `commit-message` instruction (auto-applied) |
50+
| Enforce coding standards in dataviewer | `dataviewer` instruction (auto-applied) |
51+
| Enforce markdown writing standards | `docs-style-and-conventions` instruction (auto-applied) |
52+
| Enforce shell script standards | `shell-scripts` instruction (auto-applied) |
53+
54+
## 🤖 Agents
55+
56+
### Dataviewer Developer
57+
58+
Interactive agent for launching, browsing, annotating, and improving the
59+
Dataset Analysis Tool.
60+
61+
| Property | Value |
62+
|----------|-----------------------------------------------------|
63+
| Handoffs | Start Dataviewer, Browse Dataset, Annotate Episodes |
64+
| Tools | All (no restrictions) |
65+
| Skill | `dataviewer` |
66+
| Prompts | `/start-dataviewer` |
67+
68+
Four-phase workflow: Launch/Configure → Interactive Browsing (Playwright) →
69+
Episode Annotation (API+UI) → Feature Development (React+FastAPI).
70+
71+
### OSMO Training Manager
72+
73+
Multi-turn agent for managing LeRobot imitation learning training lifecycle
74+
on OSMO with Azure ML integration.
75+
76+
| Property | Value |
77+
|----------|---------------------------------------------------------|
78+
| Handoffs | Submit Training Job, Check Training Status, Run Inference Evaluation |
79+
| Tools | 11 explicit (run_in_terminal, memory, runSubagent, ...) |
80+
| Skill | `osmo-lerobot-training` |
81+
| Prompts | `/submit-lerobot-training`, `/check-training-status` |
82+
83+
Five-phase workflow: Submit → Monitor → Analyze → Summarize → Inference
84+
Evaluation. Handles VM eviction recovery, CUDA errors, and KeyError
85+
failures.
86+
87+
## 📝 Instructions
88+
89+
Instructions activate automatically when files matching their `applyTo`
90+
pattern appear in the chat context.
91+
92+
| Name | Applies To | Purpose |
93+
|----------------------------|---------------------|---------------------------------------------------------|
94+
| Commit Messages | `**` | Conventional Commits format, scopes, line-length limits |
95+
| Dataviewer | `src/dataviewer/**` | SOLID principles, test-first, validation commands |
96+
| Docs Style and Conventions | `**/*.md` | Document hierarchy, tables, voice/tone, frontmatter |
97+
| Shell Scripts | `**/*.sh` | Script template, library functions, deployment patterns |
98+
99+
## ⚡ Prompts
100+
101+
Prompts are slash commands invoked via `/` in the chat input. Each prompt
102+
targets a specific agent.
103+
104+
| Command | Agent Target | Required Inputs |
105+
|----------------------------|-----------------------|-----------------------|
106+
| `/chatlog` | Generic | None |
107+
| `/check-training-status` | OSMO Training Manager | workflowId (optional) |
108+
| `/start-dataviewer` | Dataviewer Developer | datasetPath |
109+
| `/submit-lerobot-training` | OSMO Training Manager | dataset (required) |
110+
111+
## 🛠️ Skills
112+
113+
Skills provide multi-file capabilities with progressive 3-level loading:
114+
discovery (frontmatter only) → instructions (SKILL.md body) → resources
115+
(bundled reference files).
116+
117+
### dataviewer
118+
119+
| Property | Value |
120+
|-----------|--------------------------------------------------------------------------|
121+
| Directory | `.github/skills/dataviewer/` |
122+
| Resources | `references/PLAYWRIGHT.md` (selectors, interaction recipes, API endpoints) |
123+
| Used by | Dataviewer Developer agent |
124+
125+
### osmo-lerobot-training
126+
127+
| Property | Value |
128+
|-----------|----------------------------------------------------------------------------------------------------------------|
129+
| Directory | `.github/skills/osmo-lerobot-training/` |
130+
| Resources | `references/DEFAULTS.md` (env, datasets, GPU profiles), `references/REFERENCE.md` (CLI, inference, AzureML navigation) |
131+
| Used by | OSMO Training Manager agent |
132+
133+
## 🔄 Workflow Chains
134+
135+
Agents compose prompts and skills into end-to-end workflows:
136+
137+
```text
138+
OSMO Training Manager (agent)
139+
├── /submit-lerobot-training (prompt)
140+
├── /check-training-status (prompt)
141+
└── osmo-lerobot-training (skill)
142+
├── references/DEFAULTS.md
143+
└── references/REFERENCE.md
144+
145+
Dataviewer Developer (agent)
146+
├── /start-dataviewer (prompt)
147+
└── dataviewer (skill)
148+
└── references/PLAYWRIGHT.md
149+
150+
Standalone:
151+
└── /chatlog (prompt, generic)
152+
```
153+
154+
## ➕ Adding New Artifacts
155+
156+
VS Code provides generator commands for scaffolding new artifacts:
157+
158+
- `/create-agent` — Create a new custom agent
159+
- `/create-instruction` — Create a new instruction file
160+
- `/create-prompt` — Create a new prompt file
161+
- `/create-skill` — Create a new agent skill
162+
163+
Place new artifacts in the corresponding `.github/` subdirectory and update
164+
this inventory page.
165+
166+
## Related Documentation
167+
168+
For broader project context, see these companion guides:
169+
170+
- [Contributing Guide](../contributing/README.md) — Development workflow and coding standards
171+
- [Architecture](../contributing/architecture.md) — System architecture and agent skills design
172+
- [Prerequisites](../contributing/prerequisites.md) — Required tools and VS Code settings
173+
174+
---
175+
176+
*Crafted with precision by Copilot following brilliant human instruction,
177+
then carefully refined by our team of discerning human reviewers.*

0 commit comments

Comments
 (0)