# GitHub Copilot: IDE-Native AI Agents with Your Marketplace

**Difficulty**: Beginner-Intermediate | **Prerequisites**: GitHub Copilot license, VS Code

**TL;DR**: Put org rules in `.github/copilot-instructions.md` (auto-generate from marketplace). Use agent mode for multi-step workflows. Add MCP servers for org tool access. Optionally build a Copilot Extension for `@marketplace` in chat.

* * *

## What is GitHub Copilot?

GitHub Copilot provides AI assistance directly in your IDE (VS Code, JetBrains, Neovim) and on GitHub.com. It offers code completions, chat, and now agent mode for multi-step tasks.

**Key differentiators for marketplace integration:**

*   **copilot-instructions.md**: repo-level instructions Copilot follows
    
*   **Copilot Chat**: conversational AI in the IDE sidebar
    
*   **Agent Mode**: autonomous multi-step task execution (VS Code)
    
*   **Copilot Extensions**: custom integrations via GitHub Apps
    
*   **MCP Servers**: Model Context Protocol support in VS Code
    

## Scenario 1: Org Standards via copilot-instructions.md

**Situation**: You want every Copilot suggestion in your repo to follow org rules.

### Create `.github/copilot-instructions.md`:

```markdown
# Copilot Instructions for This Repository

## Organization Rules
You MUST follow these rules for all code suggestions:

### Security (from org marketplace)
- Never suggest hardcoded secrets, API keys, or credentials
- Use parameterized queries for all database operations
- Validate all external input at system boundaries
- Use HTTPS for all external connections

### Coding Standards (from org marketplace)
- Python: snake_case for functions/variables, type hints required
- TypeScript: camelCase, strict mode, no any types
- Functions should be under 50 lines
- No commented-out code
- All new code needs tests

### Compliance
- Never log PII (names, emails, addresses) in plain text
- Flag any cross-region data transfer suggestions
- Include audit logging for state-changing operations

## Project Context
- This is a Python/FastAPI microservice
- Database: PostgreSQL with SQLAlchemy
- Auth: Azure AD JWT tokens
- Testing: pytest with fixtures
```

### How marketplace rules map to copilot-instructions.md

Your `marketplace install` command can auto-generate this file by concatenating rules:

```bash
# In scripts/marketplace.sh, after install
generate_copilot_instructions() {
  local output=".github/copilot-instructions.md"
  mkdir -p .github

  echo "# Copilot Instructions (Auto-generated from AI Agent Marketplace)" > "$output"
  echo "" >> "$output"

  for rule_file in .ai-marketplace/rules/*.md; do
    cat "$rule_file" >> "$output"
    echo "" >> "$output"
  done

  echo "Generated $output from marketplace rules."
}
```

## Scenario 2: Copilot Chat with Marketplace Context

**Situation**: A developer wants Copilot to review code using the marketplace's PR review agent logic.

### Step 1: Reference skills in copilot-instructions.md

```markdown
## Available Review Skills

When asked to review code, follow this process:

### Security Check
[Contents of .ai-marketplace/pr-review-agent/skills/check-security.md]

### Standards Check
[Contents of .ai-marketplace/pr-review-agent/skills/check-standards.md]

### Output Format
For each finding:
- SEVERITY: CRITICAL / WARNING / INFO
- FILE: path and line number
- ISSUE: what's wrong
- FIX: how to fix it
```

### Step 2: Use in Copilot Chat

In VS Code's Copilot Chat:

```plaintext
@workspace Review the changes in my current branch for security issues and coding standard violations
```

Copilot reads the instructions and applies your marketplace's review logic.

## Scenario 3: Agent Mode for Multi-Step Tasks

**Situation**: You need Copilot to autonomously fix a bug, following your org's workflow.

### Enable Agent Mode in VS Code

In Copilot Chat, switch to Agent mode (the sparkle icon) and provide the task:

```plaintext
Fix the authentication timeout bug in src/auth/handler.ts.
Follow our org's bug fix workflow:
1. Reproduce the issue by reading the error logs
2. Locate the root cause
3. Implement the minimal fix
4. Write a regression test
5. Summarize the fix
```

Agent mode will:

*   Read files
    
*   Edit code
    
*   Run terminal commands
    
*   Execute tests
    
*   All while following the rules in `copilot-instructions.md`
    

## Scenario 4: MCP Servers in VS Code

**Situation**: You want Copilot to access ADO work items and internal documentation.

### Configure in `.vscode/settings.json`:

```json
{
  "mcp": {
    "servers": {
      "ado": {
        "command": "agency",
        "args": ["mcp", "ado"]
      },
      "internal-docs": {
        "command": "agency",
        "args": ["mcp", "docs"]
      }
    }
  }
}
```

Now in Copilot Chat:

```plaintext
What are the acceptance criteria for work item #12345?
Search our internal docs for the deployment runbook
```

## Scenario 5: Custom Copilot Extension from Marketplace

**Situation**: Your org wants a custom "@marketplace" extension in Copilot Chat.

### Build a Copilot Extension

Create a GitHub App that surfaces marketplace capabilities:

```plaintext
@marketplace browse        # List available plugins
@marketplace review        # Run the PR review agent
@marketplace explain       # Explain the selected code
@marketplace test          # Generate tests for selected code
```

This requires building a [GitHub Copilot Extension](https://techcommunity.microsoft.com/blog/microsoftmechanicsblog/build-your-own-copilot-new-microsoft-copilot-extensions/4151857), which is a lightweight server that translates marketplace skills into Copilot-compatible responses.

## Scenario 6: Brownfield Integration

**Situation**: Adding marketplace support to an existing repo without disrupting current workflows.

```bash
cd existing-project

# Install marketplace plugins
marketplace install pr-review-agent

# Auto-generate copilot instructions from marketplace rules
marketplace generate-copilot-instructions

# Commit the new files
git add .github/copilot-instructions.md .ai-marketplace/
git commit -m "Add AI Agent Marketplace integration"
```

That's it. Every developer using Copilot in this repo now gets org-standard AI assistance.

## Key GitHub Copilot Concepts for the Marketplace

| Concept | Purpose | Where it lives |
| --- | --- | --- |
| copilot-instructions.md | Repo-level instructions | `.github/copilot-instructions.md` |
| Agent Mode | Multi-step autonomous tasks | VS Code Copilot Chat |
| MCP Servers | External tool integrations | `.vscode/settings.json` |
| Copilot Extensions | Custom chat participants | GitHub App |
| Code Completions | Inline suggestions | Follows copilot-instructions.md |

## Tips for Marketplace Authors Targeting GitHub Copilot

1.  **Keep copilot-instructions.md concise**. Copilot has a limited context window for instructions
    
2.  **Use structured formats**. Numbered lists and clear headers work better than prose
    
3.  **Test with @workspace**. This is how developers will invoke your skills
    
4.  **Provide examples**. Copilot follows examples better than abstract rules
    
5.  **Consider agent mode**. Design workflows that can be executed step-by-step autonomously
    

## Quick Setup Checklist

```bash
# 1. Initialize marketplace
cd /path/to/your/project
marketplace init

# 2. Install plugins
marketplace install pr-review-agent
marketplace install test-writer

# 3. Generate Copilot-specific instructions
marketplace generate-copilot-instructions

# 4. (Optional) Add MCP servers to .vscode/settings.json
mkdir -p .vscode
# Add mcp server configs (see Scenario 4 above)

# 5. Commit
git add .ai-marketplace/ .github/copilot-instructions.md
git commit -m "Add AI Agent Marketplace for Copilot"
```

*   `.github/copilot-instructions.md` exists with org rules
    
*   `.ai-marketplace/rules/` present with org-wide rules
    
*   `.vscode/settings.json` has MCP servers (optional)
    
*   Tested with `@workspace` query in Copilot Chat