holocron/plugins/kyberforge/docs/research/docs/github-copilot-plugins/configuration.md

topic, source_keys

topic	source_keys
configuration	github-cli-plugin-reference github-plugins-creating github-custom-agents-configuration context7-github-en-copilot

Configuration

plugin.json — Plugin Manifest

Located at one of these paths (checked in order, first found wins):

• .plugin/plugin.json
• plugin.json
• .github/plugin/plugin.json
• .claude-plugin/plugin.json

Required field

Field	Type	Notes
name	string	Kebab-case; letters, numbers, hyphens only; max 64 chars

Optional metadata fields

Field	Type	Notes
description	string	Max 1024 chars
version	string	SemVer
author	object	{ name (required), email?, url? }
homepage	string
repository	string
license	string	SPDX identifier
keywords	string[]	Discoverability tags
category	string
tags	string[]

Component path fields

Field	Type	Default	Purpose
agents	string or string[]	agents/	Agent file directories
skills	string or string[]	skills/	Skill directories
commands	string or string[]	—	Command directories
hooks	string or object	—	Hooks config file path or inline object
extensions	string, string[], or object	—	Extension dirs; { paths: [...], exclusive: true } disables all built-ins
mcpServers	string or object	—	MCP server config path or inline definitions
lspServers	string or object	—	LSP server config path or inline definitions

hooks.json — Lifecycle Hooks

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "echo 'started'",
        "powershell": "Write-Output 'started'",
        "cwd": ".",
        "timeoutSec": 30,
        "env": { "MY_VAR": "value" }
      }
    ]
  }
}

version: 1 is required. Available lifecycle hook points:

• sessionStart
• sessionEnd
• userPromptSubmitted
• preToolUse
• postToolUse
• errorOccurred
• agentStop

Each entry must have type: "command". Provide bash for Linux/macOS and powershell for Windows — the correct script is selected automatically at runtime.

Hook files outside plugins live in .github/hooks/NAME.json (repo) or ~/.copilot/hooks/ (user).

.mcp.json — MCP Server Configuration

{
  "mcpServers": {
    "serverName": {
      "type": "local",
      "command": "string",
      "args": ["array"],
      "env": {},
      "tools": ["*"]
    }
  }
}

Supported type values:

• local / stdio — launches a local process
• http — remote server, Streamable transport (preferred for new remote servers)
• sse — remote server, deprecated

The tools field accepts ["*"] for all tools or an explicit list. For http type, use url and headers fields instead of command.

Skill Configuration

Skills live in named subdirectories within a skills/ directory:

skills/
└── deploy/
    └── SKILL.md

SKILL.md frontmatter:

Field	Required	Notes
name	Yes	Lowercase, hyphens for spaces
description	Yes	Drives automatic skill selection
allowed-tools	No	Pre-approves tools (e.g. shell) to skip per-use permission prompts
license	No

Only set allowed-tools if you have fully reviewed the skill and trust its source — it bypasses interactive confirmation for the listed tools.

Environment Variables

Variable	Purpose
COPILOT_HOME	Override the Copilot CLI config directory (default: ~/.copilot/)
COPILOT_CACHE_HOME	Override the marketplace cache directory
COPILOT_SKILLS_DIRS	Additional skill search paths (colon-separated)
COPILOT_PLUGIN_DATA	Persistent writable data directory for a plugin (unique per plugin, survives updates)
CLAUDE_PLUGIN_DATA	Alias for COPILOT_PLUGIN_DATA
PLUGIN_ROOT	Available in LSP cwd and script paths; resolves to the installed plugin directory

LSP Server Configuration

Can be declared inline in plugin.json or in a separate lsp-config/servers.json file. Supports platform-specific launch scripts via bash and powershell keys.

Field	Required	Description
command	One of these three	Executable path
bash	^	Bash script, run via bash -c SCRIPT
powershell	^	PowerShell script, run via pwsh -c SCRIPT
fileExtensions	Yes	Map of .ext → language ID
cwd	No	Working dir; supports ${PLUGIN_ROOT}
args	No	Arguments to command
env	No	Environment variables
rootUri	No	Project root relative to git root (default: .)
initializationOptions	No	LSP init options