Skip to content

Commit b138bf9

Browse files
jongiojongio
committed
Enhance README and web pages for azd copilot
- Updated README.md to provide a clearer overview of azd copilot, including installation instructions, commands, and detailed descriptions of agents and skills. - Revamped getting-started.astro to improve the onboarding experience with a structured step-by-step guide for installation and usage. - Enhanced index.astro to highlight the unique value propositions of azd copilot, including built-on pillars and a dedicated section for features and stats.
1 parent a47870f commit b138bf9

File tree

3 files changed

+952
-89
lines changed

3 files changed

+952
-89
lines changed

‎README.md‎

Lines changed: 199 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,228 @@
1-
# azd-copilot
1+
# azd copilot
22

3-
An Azure Developer CLI extension for GitHub Copilot integration.
3+
**Describe what you want. Copilot builds it and deploys it to Azure.**
44

5-
## Prerequisites
5+
`azd copilot` is an [Azure Developer CLI](https://learn.microsoft.com/azure/developer/azure-developer-cli/) extension that turns GitHub Copilot CLI into a full-stack Azure development assistant — 16 specialized agents, 28 Azure skills, and 6 MCP servers working together so you can go from idea to deployed app in one command.
66

7-
- [Azure Developer CLI (azd)](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd)
8-
- [Go 1.25+](https://golang.org/dl/)
9-
- [Mage](https://magefile.org/) (optional, for build automation)
7+
```
8+
_ ___ _ _ _
9+
/_\ ___ _ _ _ _ ___ / __|___ _ __ (_) |___ | |_
10+
/ _ \|_ / || | '_/ -_) | (__/ _ \ '_ \ | | / _ \ | _|
11+
/_/ \_\/__|\_,_|_| \___| \___\___/ .__/ |_|_\___/ \__|
12+
|_|
13+
AI-powered Azure development assistant
14+
Built on Copilot SDK • Azure MCP • Azure Developer CLI • Azure Agents & Skills
15+
Version 0.1.0 • 16 agents • 28 skills
16+
```
17+
18+
---
1019

11-
## Installation
20+
## Quick Start
1221

1322
```bash
23+
# Install
1424
azd extension install jongio.azd.copilot
25+
26+
# Start an interactive session
27+
azd copilot
28+
29+
# Or describe what you want
30+
azd copilot -p "build me a REST API with PostgreSQL and deploy it"
31+
32+
# Build a complete app from a description
33+
azd copilot build "todo app with React frontend and Azure Functions backend"
1534
```
1635

17-
## Development
36+
## What It Does
1837

19-
### Build and Install
38+
When you run `azd copilot`, the extension:
2039

21-
```bash
22-
# Using mage (recommended)
23-
mage build
40+
1. **Installs 16 specialized agents** to `~/.copilot/agents/` — each an expert in a domain (architecture, security, DevOps, data, AI, etc.)
41+
2. **Installs 28 focused skills** to `~/.copilot/skills/` — step-by-step playbooks for Azure tasks (deploy, prepare, validate, cost-optimize, etc.)
42+
3. **Configures 6 MCP servers** in `~/.copilot/mcp-config.json` — Azure, azd, Microsoft Learn, Context7, Playwright, and the extension's own MCP server
43+
4. **Launches GitHub Copilot CLI** with all of the above pre-loaded
44+
45+
The result: Copilot understands Azure deeply and can build, test, deploy, diagnose, and optimize your applications.
46+
47+
## Commands
48+
49+
### Core
50+
51+
| Command | Description |
52+
|---------|-------------|
53+
| `azd copilot` | Start an interactive AI session |
54+
| `azd copilot -p "prompt"` | Run a single prompt non-interactively |
55+
| `azd copilot --resume` | Resume the previous session |
56+
| `azd copilot --agent azure-security` | Use a specific agent |
57+
| `azd copilot --yolo` | Auto-approve all tool executions |
58+
59+
### Build
60+
61+
| Command | Description |
62+
|---------|-------------|
63+
| `azd copilot build "description"` | Generate a complete app from a description |
64+
| `azd copilot build --mode prototype "demo chat app"` | Quick prototype with free tiers |
65+
| `azd copilot build --approve` | Build from an approved spec |
66+
67+
The build process generates a spec → waits for approval → generates code, infra, tests, docs → runs preflight → deploys.
68+
69+
### Quick Actions
70+
71+
| Command | Description |
72+
|---------|-------------|
73+
| `azd copilot init` | Scan a project and generate Azure config |
74+
| `azd copilot review` | AI-powered code review |
75+
| `azd copilot fix` | Auto-fix build errors and test failures |
76+
| `azd copilot optimize` | Cost and performance optimization |
77+
| `azd copilot diagnose` | Troubleshoot Azure deployment issues |
78+
79+
### Management
80+
81+
| Command | Description |
82+
|---------|-------------|
83+
| `azd copilot agents` | List all available agents |
84+
| `azd copilot skills` | List all available skills |
85+
| `azd copilot sessions` | List and manage Copilot sessions |
86+
| `azd copilot checkpoints` | Manage build checkpoints |
87+
| `azd copilot spec` | View or edit the project spec |
88+
| `azd copilot context` | Show current azd project context |
89+
| `azd copilot version` | Show version info |
90+
| `azd copilot mcp configure` | Configure MCP servers |
91+
92+
## Agents
93+
94+
16 specialized agents, each an expert in a specific domain:
95+
96+
| Agent | Role |
97+
|-------|------|
98+
| `azure-manager` | **Coordinator** — plans work, delegates to other agents |
99+
| `azure-architect` | Infrastructure design, Bicep, networking |
100+
| `azure-dev` | Application code, APIs, frontend |
101+
| `azure-data` | Database schema, queries, migrations |
102+
| `azure-ai` | AI services, RAG, agent frameworks |
103+
| `azure-security` | Security audits, identity, compliance |
104+
| `azure-devops` | CI/CD, deployment, observability |
105+
| `azure-finance` | Cost estimation, optimization, TCO analysis |
106+
| `azure-quality` | Testing, code review, refactoring |
107+
| `azure-docs` | README, API docs, ADRs, runbooks |
108+
| `azure-product` | Requirements, acceptance criteria, specs |
109+
| `azure-design` | WCAG compliance, accessibility, UI review |
110+
| `azure-analytics` | Usage analytics, dashboards, metrics |
111+
| `azure-marketing` | Positioning, landing pages, competitive analysis |
112+
| `azure-support` | Troubleshooting, FAQ, error messages |
113+
| `azure-compliance` | Framework assessment (GDPR, SOC2, HIPAA) |
114+
115+
## Skills
116+
117+
28 curated skills providing deep expertise. Skills come from two sources:
118+
119+
- **Upstream skills** (18) — synced from [microsoft/GitHub-Copilot-for-Azure](https://github.com/microsoft/GitHub-Copilot-for-Azure) via `mage SyncSkills`
120+
- **Custom skills** (10) — maintained in this repo
121+
122+
Skills cover: preparing apps for Azure, deploying, validating, cost optimization, diagnostics, networking, observability, AI services, storage, PostgreSQL, Cosmos DB, Functions, Container Apps, security, Entra ID, and more.
123+
124+
Run `azd copilot skills` to see the full list.
125+
126+
## MCP Servers
127+
128+
The extension auto-configures these MCP servers for Copilot CLI:
129+
130+
| Server | Purpose |
131+
|--------|---------|
132+
| `azure` | Azure resource operations via `@azure/mcp` |
133+
| `azd` | Azure Developer CLI operations |
134+
| `azd-app` | This extension's own MCP server (agents, skills, checkpoints) |
135+
| `microsoft-learn` | Microsoft Learn documentation search |
136+
| `context7` | Library documentation lookup |
137+
| `playwright` | Browser automation and E2E testing |
138+
139+
## Architecture
24140

25-
# Or using azd directly
26-
azd x build
141+
```
142+
azd copilot (Go CLI extension)
143+
├── Launches GitHub Copilot CLI with:
144+
│ ├── 16 agents installed to ~/.copilot/agents/
145+
│ ├── 28 skills installed to ~/.copilot/skills/
146+
│ └── 6 MCP servers configured in ~/.copilot/mcp-config.json
147+
├── Detects azd project context (azure.yaml, services, environment)
148+
├── Passes Azure context as environment variables
149+
└── Exposes its own MCP server (azd copilot mcp serve)
27150
```
28151

29-
### Run Tests
152+
### Project Structure
30153

31-
```bash
32-
mage test
154+
```
155+
cli/
156+
├── src/
157+
│ ├── cmd/copilot/ # CLI commands (cobra)
158+
│ │ ├── main.go # Entry point, root command, session launcher
159+
│ │ └── commands/ # Subcommands (build, agents, skills, etc.)
160+
│ └── internal/
161+
│ ├── assets/ # Embedded agents & skills
162+
│ │ ├── agents/ # 16 agent definitions (*.md)
163+
│ │ ├── ghcp4a-skills/ # Upstream skills (synced from GitHub)
164+
│ │ └── skills/ # Custom skills
165+
│ ├── copilot/ # Copilot CLI launcher & MCP config
166+
│ ├── checkpoint/ # Build checkpoint management
167+
│ ├── spec/ # Project spec generation
168+
│ ├── cache/ # Caching utilities
169+
│ └── logging/ # Structured logging
170+
├── magefile.go # Build automation (mage)
171+
└── extension.yaml # azd extension manifest
33172
```
34173

35-
### Lint
174+
## Development
175+
176+
### Prerequisites
177+
178+
- [Go 1.25+](https://golang.org/dl/)
179+
- [Azure Developer CLI (azd)](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd)
180+
- [Mage](https://magefile.org/) (optional, for build automation)
181+
182+
### Build & Test
36183

37184
```bash
38-
mage lint
185+
cd cli
186+
187+
# Build, lint, test, and install
188+
mage # runs All (fmt → lint → test → build → install)
189+
190+
# Or individually
191+
mage build # build + install to ~/.azd/extensions/
192+
mage test # run tests
193+
mage lint # run golangci-lint
194+
mage fmt # format code
195+
196+
# Without mage
197+
go build ./...
198+
go test ./...
39199
```
40200

41-
## Usage
201+
### Upstream Skill Workflow
42202

43203
```bash
44-
# Show version
45-
azd copilot version
204+
# Pull latest skills from microsoft/GitHub-Copilot-for-Azure
205+
mage SyncSkills
46206

47-
# Show help
48-
azd copilot --help
207+
# Contribute your skill changes back upstream
208+
mage ContributeSkills
49209
```
50210

211+
The sync uses **smart merge** — your local changes are preserved, new upstream files are added, and only unmodified files are updated.
212+
213+
### Adding a Custom Skill
214+
215+
Create a directory in `cli/src/internal/assets/skills/` with a `SKILL.md`:
216+
217+
```
218+
skills/my-skill/
219+
├── SKILL.md # Required — YAML frontmatter (name, description) + instructions
220+
├── references/ # Optional — additional docs
221+
└── assets/ # Optional — templates
222+
```
223+
224+
Then run `mage UpdateCounts` to update agent/skill counts across the project.
225+
51226
## License
52227

53228
MIT

0 commit comments

Comments
 (0)