Repository navigation
Coordinator should detect and enforce all three tooling layers (local skills, global MCP, global Copilot skills) #330
Description
Problem
During a real-world build session (FastAPI + AKS Automatic + PostgreSQL + ACR deployed via `azd up`), the Squad coordinator had three layers of tooling available but used none of them:
- Global MCP tools (`azure-mcp-get_azure_bestpractices`, `azure-mcp-aks`, `azure-mcp-documentation`, etc.) — 8+ tools available, zero called
- Global Copilot skills (`azure-ai`, `appinsights-instrumentation`, etc.) — available via `<available_skills>`, never considered
- Local project skills (`.squad/skills/`) — blank template, expected for a new project
This led to 13 deployment fix commits out of 18 total — most avoidable with a single pre-flight query.
Root Cause — Three Distinct Gaps in squad.agent.md
Gap 1: MCP Tools — Detected but Not Enforced
The coordinator's MCP Integration section says to detect `azure_*` tools and pass them to agents via an `MCP TOOLS AVAILABLE` block. But:
- There's no rule enforcing a research-before-build step for Azure infrastructure work
- The coordinator routes directly to the infra agent without querying best practices first
- The MCP block is "include if detected" — not "must call before routing"
Gap 2: Global Copilot Skills — Completely Invisible
The coordinator's Skill-aware routing says: "check `.squad/skills/` for skills relevant to the task domain."
This is local skills only. The globally-installed Copilot skills provided via `<available_skills>` in the environment (like `azure-ai`, `appinsights-instrumentation`) are:
- ❌ Not detected by the coordinator
- ❌ Not passed to spawned agents
- ❌ Not used as routing signals
- ❌ Not mentioned anywhere in the spawn template
These global skills are fundamentally different from local project skills — they're installed at the user/system level and provide domain expertise that any agent could use. The coordinator has no concept of them.
Gap 3: No Layered Tooling Model
The coordinator doesn't distinguish between these three layers:
| Layer | Source | When Available | Example | Coordinator Awareness |
|---|---|---|---|---|
| Local skills | `.squad/skills/` | After team discovers patterns | "Our Bicep files use `environmentName` prefix" | ✅ Checked during routing |
| Global MCP tools | User's MCP config | Always (if configured) | `azure-mcp-aks`, `azure-mcp-documentation` | |
| Global Copilot skills | `<available_skills>` | Always (if installed) | `azure-ai`, `appinsights-instrumentation` | ❌ Completely invisible |
Without this layered model, the coordinator treats "we had no local skills" as "we had no tools" — which was wrong. Platform knowledge was available from day one via MCP tools and global skills.
Proposed Fix
1. Add a Tooling Awareness section to squad.agent.md
Define the three-layer model so the coordinator understands what's available:
```markdown
Tooling Awareness — Three Layers
The coordinator must be aware of three distinct layers of tooling:
- Local project skills (`.squad/skills/`) — team-earned patterns, checked during routing
- Global MCP tools (detected by tool prefix) — platform API access, passed to agents via MCP block
- Global Copilot skills (`<available_skills>`) — domain expertise, passed to agents when relevant
All three layers should inform routing decisions and agent spawn prompts.
```
2. Add Global Skills detection and passthrough
Add to the spawn template an optional `GLOBAL SKILLS AVAILABLE` block (similar to the existing `MCP TOOLS` block):
```
{only if relevant global skills detected in <available_skills>:}
GLOBAL SKILLS AVAILABLE:
- {skill-name}: {description}
Call the `skill` tool with the skill name if this domain is relevant to your task.
{end block}
```
3. Add Azure Pre-Flight Rule to Routing
| Signal | Action |
|---|---|
| Azure infra work (Bicep, AKS, ACR, azd, ARM) | Pre-flight: Coordinator calls `azure-mcp-get_azure_bestpractices` BEFORE spawning the infra agent. Include results in spawn prompt as `AZURE BEST PRACTICES:` block. |
4. Update Skill-aware routing
Change from:
"check `.squad/skills/` for skills relevant to the task domain"
To:
"check `.squad/skills/` (local) AND `<available_skills>` (global) for skills relevant to the task domain. Include both in spawn prompts when matched."
Evidence
Full session documented in `LESSONS-LEARNED.md` at https://github.com/shboyer/gartner-march.
Deployment failures mapped to tools that would have prevented them
| Failure | Fix Commits | Tool Layer | Specific Tool |
|---|---|---|---|
| K8s version 1.29/1.31 LTS-only | 3 commits | Global MCP | `azure-mcp-aks` get-versions |
| AKS Automatic requirements | 2 commits | Global MCP | `azure-mcp-get_azure_bestpractices` |
| azd env var naming (AZURE_ prefix) | 3 commits | Global MCP | `azure-mcp-documentation` |
| Deployment safeguards (seccomp, no :latest) | 1 commit | Global MCP | `azure-mcp-documentation` |
| Image reference pattern | 1 commit | Global MCP | `azure-mcp-documentation` |
| RBAC Cluster Admin requirement | 1 commit | Global MCP | `azure-mcp-get_azure_bestpractices` |
| OMS agent deprecated | 1 commit | Global Skill | `appinsights-instrumentation` skill |
| PostgreSQL region restrictions | 2 commits | Global MCP | `azure-mcp-postgres` |
Conservative estimate: 11 of 13 fix commits avoidable by using available tools before writing code.
Labels
Coordinator governance fix — changes only `squad.agent.md`, no code changes needed. Affects both MCP Integration and Skill-aware routing sections.
Activity
[-]Coordinator should enforce Azure MCP pre-flight before infra work[/-][+]Coordinator should detect and enforce all three tooling layers (local skills, global MCP, global Copilot skills)[/+]fix: implement P1 UX polish from Marquez audit (github#356)
github-actions commentedon Mar 13, 2026
🏗️ Squad Triage — Flight (Lead)
Issue: #330 — Coordinator should detect and enforce all three tooling layers (local skills, global MCP, global Copilot skills)
Assigned to: FIDO (Quality Owner)
Reason: Issue relates to testing/quality work
@copilot evaluation: 🔴 Not suitable — issue involves work outside the coding agent's capability profile.
Team roster:
squad:flightsquad:proceduressquad:eecomsquad:fidosquad:paosquad:capcomsquad:controlsquad:surgeonsquad:boostersquad:gncsquad:networksquad:retrosquad:incosquad:guidosquad:telemetrysquad:voxsquad:dskysquad:simssquad:handbooksquad:ralphsquad:copilotgithub-actions commentedon Mar 13, 2026
📋 Assigned to Flight (Lead)
Issue: #330 — Coordinator should detect and enforce all three tooling layers (local skills, global MCP, global Copilot skills)
Flight will pick this up in the next Copilot session.
github-actions commentedon Mar 13, 2026
📋 Assigned to Procedures (Prompt Engineer)
Issue: #330 — Coordinator should detect and enforce all three tooling layers (local skills, global MCP, global Copilot skills)
Procedures will pick this up in the next Copilot session.
bradygaster commentedon Mar 16, 2026
🔗 Linked with #354 — these two must ship together as a single body of work.
Decision (bradygaster): This is now the team's top priority. All efforts focused here until it ships. No next release without this landing.
The three-layer tooling model (#330) defines what the coordinator needs to know. The skills migration (#354) defines where skills live so Copilot can discover them. One without the other is incomplete.
Execution plan:
cc #354
chore(.squad): update team focus to skills migration (#330/#354)
feat: migrate skills from .squad/skills/ to .copilot/skills/ (#330, #354
feat: migrate skills from .squad/skills/ to .copilot/skills/ (#330, #354
feat: migrate skills from .squad/skills/ to .copilot/skills/ (#330, #354