The Ecosystem

Ecosystem Overview

Six composable primitives — from always-on behavioral standards to deterministic policy enforcement.

🤖 Copilot Coding Agent

The autonomous runtime engine that executes agentic workflows in ephemeral GitHub Actions environments.

Entry Points

Workflow Lifecycle

📘 Custom Instructions

The foundational behavioral layer — always-on rules that shape every interaction across an entire repository, organization, or workspace.

Six Instruction Types

Path-specific instructions example:

---
applyTo: "**/*.bicep"
---
When writing Bicep files, always use parameter
decorators, follow naming conventions, and include
resource descriptions for documentation.

Layer 0: Personal Instructions (VS Code Settings)          ← Highest priority
Layer 1: copilot-instructions.md (repo-wide)                ← Always-on
Layer 2: *.instructions.md (matched by applyTo glob)        ← Conditionally loaded
Layer 3: AGENTS.md (when coding agent is operating)         ← Agent-scoped
Layer 4: Skill (if the task matches a skill description)    ← On-demand
Layer 5: Custom Agent prompt (if a specific agent selected) ← Explicitly selected

All applicable instructions are provided simultaneously — contradictions between layers should be avoided.

📄 Prompt Files

Reusable, named tasks invoked on demand as slash commands — bridging always-on instructions and full custom agents.

---
mode: agent
tools: ['search/codebase', 'edit/editFiles',
        'read/problems']
description: Create a structured implementation
             plan for a new feature
---
# Feature Planning

You are a senior software architect.
Create an implementation plan for the
following feature: ${input:featureDescription}

## Requirements
- Break down into discrete tasks
- Identify affected files using codebase search
- Estimate complexity per task

👤 Custom Agents

Specialized AI personas with defined roles, tool boundaries, and collaboration patterns. Defined as .agent.md files with YAML frontmatter.

Collaboration Patterns

Handoffs example:

---
name: Planner
description: Generate implementation plans
tools: ['search', 'fetch']
handoffs:
  - label: Start Implementation
    agent: Implementer
    prompt: "Implement the plan above."
    send: false  # User must click
---

Handoff flow: Planner → [User clicks] → Implementer → [User clicks] → Reviewer

• Human-in-the-loop control
• Shared conversation history
• Unlimited depth

Sub-agents example:

---
name: Feature Builder
description: Build features by researching
             first, then implementing
tools: ['agent']
agents: ['Researcher', 'Implementer']
---

Sub-agent flow: Feature Builder autonomously delegates → Researcher → Implementer

• Agent-autonomous (no user clicks)
• Isolated context (clean session)
• Single level depth only

MCP Servers in Agent Profiles

---
name: my-custom-agent-with-mcp
description: Custom agent description
tools: ['tool-a', 'tool-b', 'custom-mcp/tool-1']
mcp-servers:
  custom-mcp:
    type: 'local'
    command: 'some-command'
    args: ['--arg1', '--arg2']
    tools: ["*"]
    env:
      ENV_VAR_NAME: ${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}
---

Secret syntax supports: $COPILOT_MCP_*, ${COPILOT_MCP_*}, and ${{ secrets.COPILOT_MCP_* }}.

📋 Agent Skills

The workflow packaging layer — reusable runbooks that bundle instructions, scripts, templates, and reference materials into self-contained capability packages.

Progressive Loading Model (Three-Tier)

At startup, agents load only the name and description of each available skill — just enough to know when it might be relevant. Full content is loaded progressively.

Directory structure:

.github/skills/incident-triage/
├── SKILL.md              # Required: primary instructions
├── LICENSE.txt            # Recommended: license terms
├── scripts/               # Optional: executable scripts
│   ├── collect-metrics.sh
│   └── notify-oncall.ps1
├── references/            # Optional: on-demand docs
│   ├── runbook.md
│   └── escalation-matrix.md
├── assets/                # Optional: static resources
│   └── triage-template.md
└── templates/             # Optional: scaffolds
    └── incident-report.md

SKILL.md format:

---
name: github-actions-failure-debugging
description: >
  Guide for debugging failing GitHub Actions
  workflows. Use this when asked to debug
  failing GitHub Actions workflows.
---

To debug failing GitHub Actions workflows:

1. Use `list_workflow_runs` to look up
   recent runs and their status
2. Use `summarize_job_log_failures` for
   an AI summary of failed jobs
3. Use `get_job_logs` for full failure
   logs if needed
4. Reproduce locally, then fix and verify

Storage Locations

Real-World Skill Examples

Skills vs Instructions

🔌 MCP Integration

Model Context Protocol — an open standard defining how applications share context with large language models, connecting AI agents to live external systems.

Four Capability Categories

GitHub MCP Server

Remote MCP config:

{
  "servers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

Uses one-click OAuth — no PAT or additional software required.

Coding agent MCP config:

{
  "mcpServers": {
    "sentry": {
      "command": "npx",
      "args": ["-y", "@sentry/mcp-server"],
      "env": {
        "SENTRY_AUTH_TOKEN":
          "$COPILOT_MCP_SENTRY_TOKEN"
      }
    }
  }
}

Secrets must be prefixed with COPILOT_MCP_ and stored in the copilot environment.

Configuration Locations

Toolsets

🔒 Hooks System

The policy enforcement layer — deterministic shell commands that run at strategic points in an agent’s workflow. Unlike instructions (advisory), hooks are deterministic: a deny is a deny.

Eight Hook Types

Hook configuration example:

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "./scripts/session-banner.sh",
        "powershell": "./scripts/session-banner.ps1",
        "cwd": ".github/hooks",
        "timeoutSec": 10
      }
    ],
    "preToolUse": [
      {
        "type": "command",
        "bash": "./scripts/security-check.sh",
        "powershell": "./scripts/security-check.ps1",
        "cwd": "scripts",
        "env": {
          "LOG_LEVEL": "INFO"
        }
      }
    ]
  }
}

preToolUse input:

{
  "timestamp": 1704614600000,
  "cwd": "/path/to/project",
  "toolName": "bash",
  "toolArgs": "{\"command\":\"rm -rf /\"}"
}

preToolUse output (to deny):

{
  "decision": "deny",
  "reason": "Destructive command blocked"
}

postToolUse input includes results:

{
  "toolResult": {
    "resultType": "success",
    "result": "..."
  }
}

Where Hooks Run

Governance Example: Comprehensive Audit Trail

{
  "version": 1,
  "hooks": {
    "sessionStart":          [{ "type": "command", "bash": "./audit/log-session-start.sh" }],
    "userPromptSubmitted":   [{ "type": "command", "bash": "./audit/log-prompt.sh" }],
    "preToolUse":            [{ "type": "command", "bash": "./audit/log-tool-use.sh" }],
    "postToolUse":           [{ "type": "command", "bash": "./audit/log-tool-result.sh" }],
    "sessionEnd":            [{ "type": "command", "bash": "./audit/log-session-end.sh" }]
  }
}

Governance Audit Hook (Community)

Configure governance level in hooks.json env:

{
  "env": {
    "GOVERNANCE_LEVEL": "strict",
    "BLOCK_ON_THREAT": "true"
  }
}

🔗 How They Compose

The six primitives are designed to layer together. They compose — they don’t replace each other.

Composition Rules

Comprehensive Comparison

A Mature gh-aw Repository

.github/
├── copilot-instructions.md              # Global standards
├── instructions/
│   ├── terraform.instructions.md        # applyTo: "**/*.tf"
│   ├── typescript.instructions.md       # applyTo: "**/*.ts"
│   └── pipeline.instructions.md         # applyTo: "**/*.yml"
├── prompts/
│   ├── security-review.prompt.md        # /security-review
│   ├── release-notes.prompt.md          # /release-notes
│   └── generate-module.prompt.md        # /generate-module
├── agents/
│   ├── planner.agent.md                 # Planning specialist
│   ├── implementer.agent.md             # Code implementation
│   ├── security-reviewer.agent.md       # Read-only security review
│   └── cost-optimizer.agent.md          # Cloud cost analysis
├── skills/
│   ├── incident-triage/
│   │   ├── SKILL.md
│   │   ├── scripts/collect-metrics.sh
│   │   └── templates/incident-report.md
│   ├── postmortem/
│   │   ├── SKILL.md
│   │   └── references/rca-template.md
│   └── ci-troubleshooting/
│       ├── SKILL.md
│       └── scripts/diagnose-pipeline.sh
├── hooks/
│   ├── security-gates.json              # preToolUse: block risky commands
│   └── audit-logging.json               # postToolUse: log all tool calls
AGENTS.md                                # Multi-agent operational procedures

📅 Ecosystem Evolution

Key milestones in the gh-aw ecosystem.