GitHub Copilot

Overview

@stax/github-copilot is the canonical stax adapter for GitHub Copilot.

GitHub Copilot spans both VS Code (local) and GitHub.com (hosted coding agent). Its configuration uses .github/copilot-instructions.md for repo-wide instructions, .github/instructions/*.instructions.md for path-scoped instructions, .vscode/mcp.json for MCP, and .github/skills/ for skills.

This adapter targets the documented Copilot file contract described in 17 — Runtime File Contracts.

Scope model

In stax 1.0.0, @stax/github-copilot SHOULD default to workspace scope.

Adapter interface

interface GithubCopilotAdapterOptions {
  model?: string;
  modelParams?: Record<string, unknown>;

  scope?: "workspace" | "user";
  exact?: boolean;

  writeInstructions?: boolean; // default: true
  writePathInstructions?: boolean; // default: true
  writeMcp?: boolean; // default: true
  writeSkills?: boolean; // default: true
  writeAgents?: boolean; // default: false — subagent .agent.md files
  writeAgentsMd?: boolean; // default: true — AGENTS.md at root

  config?: Record<string, unknown>; // Copilot-specific settings
}

The compiled adapter config SHOULD use:

{
  "type": "github-copilot",
  "runtime": "github-copilot",
  "adapterVersion": "1.0.0"
}

Exact target mapping

Workspace scope

User scope

Instructions generation

Repo-wide instructions

The adapter SHOULD write .github/copilot-instructions.md from the first available source:

1. surfaces/instructions.md
2. prompt
3. synthesized composition

This file is automatically included in all Copilot chat requests.

Path-specific instructions

stax rules with scope: 'glob' SHOULD be translated to .github/instructions/<rule-id>.instructions.md files with the following frontmatter:

---
applyTo: "**/*.ts,**/*.tsx"
---

Rule content here.

Frontmatter mapping

Lossy translations

• stax priority and severity have no Copilot equivalent and MUST be dropped with a warning
• stax triggers have no Copilot equivalent and MUST be dropped with a warning
• stax scope: 'manual' rules cannot be represented; the adapter SHOULD embed them in instructions or warn

AGENTS.md support

Copilot reads AGENTS.md at the workspace root (and subdirectories with chat.useNestedAgentsMdFiles). When writeAgentsMd is true, the adapter MAY also write AGENTS.md alongside .github/copilot-instructions.md.

When an artifact includes 38 — Instruction Trees, the adapter MAY materialize nested AGENTS.md files at the corresponding scoped paths when the target Copilot environment enables nested AGENTS support.

MCP mapping

Copilot uses .vscode/mcp.json for MCP server configuration.

Output format

{
  "servers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${input:github-token}"
      }
    },
    "remote-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

Key differences from other runtimes

• the root key is "servers" (not "mcpServers")
• each server entry requires an explicit "type" field ("stdio", "http", or "sse")
• environment variables support VS Code variable syntax: ${input:id}, ${workspaceFolder}, ${userHome}
• an optional top-level "inputs" array defines user-prompted variables

Mapping rules

• stdio servers map to type: "stdio", command, args, and optional env
• remote servers map to type: "http", url, and optional headers
• secret values SHOULD use ${input:variable} syntax for user prompting
• unsupported canonical MCP fields MUST trigger warnings

Skills mapping

Copilot supports skills in .github/skills/<name>/SKILL.md, compatible with the stax skill format.

• target directory: .github/skills/ or ~/.copilot/skills/
• each top-level skill directory MUST be preserved
• SKILL.md content SHOULD be preserved byte-for-byte
• Copilot also reads .claude/skills/ and .agents/skills/ as compatible paths

Subagents mapping

When writeAgents is enabled and a subagents layer is present, the adapter SHOULD materialize each named subagent to .github/agents/<name>.agent.md.

Consumers SHOULD preserve the compiled instruction bytes and warn when a canonical subagent field cannot be represented in Copilot's .agent.md shape.

Feature map

{
  "prompt": "native",
  "persona": "embedded",
  "rules": "translated",
  "skills": "native",
  "mcp": "translated",
  "surfaces": "embedded",
  "secrets": "consumer-only",
  "toolPermissions": "unsupported",
  "modelConfig": "native",
  "exactMode": true
}

What the adapter MUST NOT own

• VS Code user settings.json (machine-specific)
• .vscode/settings.json copilot enable/disable keys (user preference)
• auth tokens or GitHub credentials
• .github/prompts/*.prompt.md (reusable prompt files are user-authored, not stax-managed)
• .github/agents/*.agent.md by default (opt-in via writeAgents)

Exactness requirements

An implementation claiming exact GitHub Copilot support SHOULD:

1. write .github/copilot-instructions.md for repo-wide instructions
2. write .github/instructions/*.instructions.md with correct applyTo frontmatter for glob-scoped rules
3. write .vscode/mcp.json with servers root key and explicit type fields
4. preserve skill directory structure exactly under .github/skills/
5. materialize subagents to .github/agents/*.agent.md when enabled and present
6. materialize nested AGENTS.md files from instructionTree when the target environment supports them
7. avoid writing user preferences or auth files
8. warn or fail when lossy translations occur in exact mode