Poorgramer Zack Copilot CLI Things Copilot CLI Configurator

name: copilot-cli-configurator description: "GitHub Copilot CLI configuration and setup: custom instructions (copilot-instructions.md, AGENTS.md), managing skills, configuring hooks (hooks.json), MCP servers (mcp-config.json), custom agents (.agent.md), installing plugins, extensions placement. Use when choosing between customization surfaces, setting up config files, managing installed components, or debugging configuration loading order."

Copilot CLI Configurator

Set up and configure GitHub Copilot CLI customization surfaces. For creating skills, extensions, or MCP servers from scratch, use the dedicated skill-creator, create-extension, or mcp-builder skills instead.

Choosing the Right Customization

Read references/feature-comparison.md for detailed trade-offs between each surface.

1. Custom Instructions

Persistent guidance loaded at session start — tells Copilot how to behave across all tasks.

File Locations

Also supports CLAUDE.md and GEMINI.md at repo root.

Path-Specific Instructions

Require YAML frontmatter with applyTo glob:

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

Use strict TypeScript with no `any` types. Prefer interfaces over type aliases.

Optional excludeAgent field to exclude "code-review" or "coding-agent".

When to Use

• Style and quality rules (e.g., "prefer small PRs, write tests")
• Repository conventions (e.g., "use pnpm, keep CHANGELOG.md updated")
• Communication preferences (e.g., "explain tradeoffs briefly")

When NOT to Use

• Behavior needed only in one workflow → use a skill
• Instructions are too large or specific → use a skill or custom agent

2. Skills

Skills are folders loaded on demand for specialized tasks. Use skill-creator for building new skills — this section covers management only.

Storage Locations

• Project: .github/skills/ or .claude/skills/
• Personal: ~/.copilot/skills/ or ~/.claude/skills/

CLI Commands

Invoking a Skill

• Slash command: /my-skill do something
• Copilot auto-triggers based on the skill's description field

3. Hooks

Hooks execute shell commands at lifecycle points during a session. Read references/hooks-reference.md for the full schema.

Configuration

Place hooks.json in .github/hooks/ (repo) or configure via CLI.

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "echo \"Session started: $(date)\" >> logs/session.log",
        "powershell": "Add-Content -Path logs/session.log -Value \"Session started: $(Get-Date)\"",
        "cwd": ".",
        "timeoutSec": 10
      }
    ],
    "preToolUse": [],
    "postToolUse": [],
    "userPromptSubmitted": [],
    "sessionEnd": [],
    "errorOccurred": [],
    "agentStop": [],
    "subagentStop": []
  }
}

Available Triggers

Hook Entry Properties

• type: Always "command"
• bash / powershell: Shell command (provide both for cross-platform)
• cwd: Working directory (optional)
• timeoutSec: Timeout in seconds (default 30)
• env: Environment variables as key-value object (optional)

When to Use

• Tool guardrails (e.g., block edits to infra/ without a ticket)
• Session lifecycle automation (e.g., archive transcripts)
• Error handling policy
• Subagent workflow control

4. MCP Servers

Connect external tools and data sources via the Model Context Protocol. The GitHub MCP server is built in — these steps are for adding other servers. Use mcp-builder for developing new MCP servers.

Adding via CLI

In interactive mode: /mcp add — fill in the form (Tab to navigate, Ctrl+S to save).

Server types:

• Local / STDIO: Starts a local process, communicates over stdin/stdout
• HTTP / SSE: Connects to a remote server

Configuration File

Edit ~/.copilot/mcp-config.json directly:

{
  "mcpServers": {
    "playwright": {
      "type": "local",
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {},
      "tools": ["*"]
    },
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "YOUR-API-KEY"
      },
      "tools": ["*"]
    }
  }
}

CLI Commands

Tools Property

• "*" — all tools from the server
• Comma-separated list of tool names
• Namespace prefix: some-mcp-server/some-tool

5. Custom Agents

Custom agents define specialized expertise for specific task types, running as subagents with their own context window. Read references/custom-agents-reference.md for the full property list and tool aliases.

File Locations

• Project: .github/agents/
• User: ~/.copilot/agents/

User-level agents override project-level agents with the same name.

Agent File Format

Each agent is a .agent.md file:

---
name: security-auditor
description: Checks code for security vulnerabilities. Use when security review/check/audit is requested.
tools: ["read", "search", "bash"]
---

You are a security specialist. Check for exposed secrets, XSS/SQL injection risks, vulnerable dependencies, and auth bypass opportunities.

Tools Configuration

• Omit tools or use tools: ["*"] → all tools enabled
• tools: [] → no tools (analysis-only agent)
• tools: ["read", "search", "edit"] → specific tools only

Common aliases: execute/shell (shell), read (files), edit/Write (editing), search/Grep/Glob (search), agent/Task (subagents), web (web access).

MCP Servers in Agent Profiles

Agents can define their own MCP connections in frontmatter:

mcp-servers:
  custom-mcp:
    type: "local"
    command: "some-command"
    args: ["--arg1"]
    tools: ["*"]
    env:
      API_KEY: ${{ secrets.MY_API_KEY }}

Using Custom Agents

• /agent → select from list interactively
• Explicit: Use the security-auditor agent on src/
• Copilot auto-delegates based on agent description
• CLI: copilot --agent security-auditor --prompt "Check src/"

CLI Creation Wizard

In interactive mode: /agent → Create new agent → choose Project or User → describe or fill manually → select tools → restart CLI.

6. Extensions

Extensions are Node.js child processes that add custom tools, programmatic hooks, and event-driven behaviors via @github/copilot-sdk. Use create-extension for developing new extensions — this section covers placement and management.

File Locations

.github/extensions/my-extension/
  extension.mjs        ← Entry point (required, must be .mjs)

• Project: .github/extensions/ (relative to git root)
• User: ~/.copilot/extensions/
• Project extensions shadow user extensions on name collision

CLI Commands

Lifecycle

• Discovered and forked at CLI startup
• Reloaded on /clear (in-memory state is lost)
• Stopped on CLI exit (SIGTERM, then SIGKILL after 5s)

When to Use (vs Other Surfaces)

7. Plugins

Plugins bundle agents, skills, hooks, and MCP configs into distributable packages. Read references/plugin-reference.md for full schemas.

Installing Plugins

Managing Plugins

Plugin Storage

• Via marketplace: ~/.copilot/state/installed-plugins/MARKETPLACE/PLUGIN-NAME/
• Direct install: ~/.copilot/state/installed-plugins/PLUGIN-NAME/

8. Plugin Marketplaces

CLI Commands

Default marketplaces: copilot-plugins, awesome-copilot.

Loading Order & Precedence

Agents & Skills — first-found-wins:

1. ~/.copilot/agents/ (user, .github convention)
2. <project>/.github/agents/ (project)
3. Parent directories (monorepo)
4. ~/.claude/agents/ (user, .claude convention)
5. <project>/.claude/agents/ (project, .claude convention)
6. Plugin agents (by install order)
7. Remote org/enterprise (via API)

Extensions — project shadows user:

1. ~/.copilot/extensions/ (user)
2. <project>/.github/extensions/ (project, higher priority)

MCP Servers — last-wins:

1. ~/.copilot/mcp-config.json (lowest priority)
2. .vscode/mcp.json (workspace)
3. Plugin MCP configs
4. --additional-mcp-config flag (highest priority)

Built-in tools and agents are always present and cannot be overridden.

Workflow: Helping Users Configure

1. Clarify the goal — what behavior do they want?
2. Recommend the right surface — use the comparison table above
3. Generate config files — create files with proper structure
4. Explain file placement — specify exactly where files go
5. Verify — suggest commands to confirm configuration loaded

For detailed schemas, read the references/ directory.

Source: Poorgramer-Zack/copilot-cli-things — distributed by TomeVault.