Wardn HubTrusted MCP server directory.

Registry

  • MCP Servers
  • Skills
  • Categories

Resources

  • API docs
  • Score method

Contribute

  • Submit server
  • Advertise
© 2026 Wardn Hub
Wardn Hub
MCP ServersSkillsCategoriesAPI docsSubmit server
Submit server
skills/sickn33/agentic-awesome-skills/copilot-sdk

copilot-sdk

1
sickn33/agentic-awesome-skills·Review advised·Snapshot 6dc26c6bfc7a

Summary

This source did not publish a separate summary. Review SKILL.md before using the skill.

SKILL.md

GitHub Copilot SDK

Build applications that programmatically interact with GitHub Copilot. The SDK wraps the Copilot CLI via JSON-RPC, providing session management, custom tools, hooks, MCP server integration, and streaming across Node.js, Python, Go, and .NET.

Prerequisites

  • GitHub Copilot CLI installed and authenticated (copilot --version to verify)
  • GitHub Copilot subscription (Individual, Business, or Enterprise) — not required for BYOK
  • Runtime: Node.js 18+ / Python 3.8+ / Go 1.21+ / .NET 8.0+

Installation

LanguagePackageInstall
Node.js@github/copilot-sdknpm install @github/copilot-sdk
Pythongithub-copilot-sdkpip install github-copilot-sdk
Gogithub.com/github/copilot-sdk/gogo get github.com/github/copilot-sdk/go
.NETGitHub.Copilot.SDKdotnet add package GitHub.Copilot.SDK

Core Pattern: Client → Session → Message

All SDK usage follows this pattern: create a client, create a session, send messages.

Node.js / TypeScript

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
const session = await client.createSession({ model: "gpt-4.1" });

const response = await session.sendAndWait({ prompt: "What is 2 + 2?" });
console.log(response?.data.content);

await client.stop();

Python

import asyncio
from copilot import CopilotClient

async def main():
    client = CopilotClient()
    await client.start()
    session = await client.create_session({"model": "gpt-4.1"})
    response = await session.send_and_wait({"prompt": "What is 2 + 2?"})
    print(response.data.content)
    await client.stop()

asyncio.run(main())

Go

client := copilot.NewClient(nil)
if err := client.Start(ctx); err != nil { log.Fatal(err) }
defer client.Stop()

session, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: "gpt-4.1"})
response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "What is 2 + 2?"})
fmt.Println(*response.Data.Content)

.NET

await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-4.1" });
var response = await session.SendAndWaitAsync(new MessageOptions { Prompt = "What is 2 + 2?" });
Console.WriteLine(response?.Data.Content);

Streaming Responses

Enable real-time output by setting streaming: true and subscribing to delta events.

const session = await client.createSession({ model: "gpt-4.1", streaming: true });

session.on("assistant.message_delta", (event) => {
    process.stdout.write(event.data.deltaContent);
});
session.on("session.idle", () => console.log());

await session.sendAndWait({ prompt: "Tell me a joke" });

Python equivalent:

from copilot.generated.session_events import SessionEventType

session = await client.create_session({"model": "gpt-4.1", "streaming": True})

def handle_event(event):
    if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
        sys.stdout.write(event.data.delta_content)
        sys.stdout.flush()

session.on(handle_event)
await session.send_and_wait({"prompt": "Tell me a joke"})

Event Subscription

MethodDescription
on(handler)Subscribe to all events; returns unsubscribe function
on(eventType, handler)Subscribe to specific event type (Node.js only)

Custom Tools

Define tools that Copilot can call to extend its capabilities.

Node.js

import { CopilotClient, defineTool } from "@github/copilot-sdk";

const getWeather = defineTool("get_weather", {
    description: "Get the current weather for a city",
    parameters: {
        type: "object",
        properties: { city: { type: "string", description: "The city name" } },
        required: ["city"],
    },
    handler: async ({ city }) => ({ city, temperature: "72°F", condition: "sunny" }),
});

const session = await client.createSession({
    model: "gpt-4.1",
    tools: [getWeather],
});

Python

from copilot.tools import define_tool
from pydantic import BaseModel, Field

class GetWeatherParams(BaseModel):
    city: str = Field(description="The city name")

@define_tool(description="Get the current weather for a city")
async def get_weather(params: GetWeatherParams) -> dict:
    return {"city": params.city, "temperature": "72°F", "condition": "sunny"}

session = await client.create_session({"model": "gpt-4.1", "tools": [get_weather]})

Go

type WeatherParams struct {
    City string `json:"city" jsonschema:"The city name"`
}

getWeather := copilot.DefineTool("get_weather", "Get weather for a city",
    func(params WeatherParams, inv copilot.ToolInvocation) (WeatherResult, error) {
        return WeatherResult{City: params.City, Temperature: "72°F"}, nil
    },
)

session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
    Model: "gpt-4.1",
    Tools: []copilot.Tool{getWeather},
})

.NET

var getWeather = AIFunctionFactory.Create(
    ([Description("The city name")] string city) => new { city, temperature = "72°F" },
    "get_weather", "Get the current weather for a city");

await using var session = await client.CreateSessionAsync(new SessionConfig {
    Model = "gpt-4.1", Tools = [getWeather],
});

Hooks

Intercept and customize session behavior at key lifecycle points.

HookTriggerUse Case
onPreToolUseBefore tool executesPermission control, argument modification
onPostToolUseAfter tool executesResult transformation, logging
onUserPromptSubmittedUser sends messagePrompt modification, filtering
onSessionStartSession beginsAdd context, configure session
onSessionEndSession endsCleanup, analytics
onErrorOccurredError happensCustom error handling, retry logic

Example: Tool Permission Control

const session = await client.createSession({
    hooks: {
        onPreToolUse: async (input) => {
            if (["shell", "bash"].includes(input.toolName)) {
                return { permissionDecision: "deny", permissionDecisionReason: "Shell access not permitted" };
            }
            return { permissionDecision: "allow" };
        },
    },
});

Pre-Tool Use Output

FieldTypeDescription
permissionDecision"allow" | "deny" | "ask"Whether to allow the tool call
permissionDecisionReasonstringExplanation for deny/ask
modifiedArgsobjectModified arguments to pass
additionalContextstringExtra context for conversation
suppressOutputbooleanHide tool output from conversation

MCP Server Integration

Connect to MCP servers for pre-built tool capabilities.

Remote HTTP Server

const session = await client.createSession({
    mcpServers: {
        github: { type: "http", url: "https://api.githubcopilot.com/mcp/" },
    },
});

Local Stdio Server

const session = await client.createSession({
    mcpServers: {
        filesystem: {
            type: "local",
            command: "npx",
            args: ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
            tools: ["*"],
        },
    },
});

MCP Config Fields

FieldTypeDescription
type"local" | "http"Server transport type
commandstringExecutable path (local)
argsstring[]Command arguments (local)
urlstringServer URL (http)
toolsstring[]["*"] or specific tool names
envobjectEnvironment variables
cwdstringWorking directory (local)
timeoutnumberTimeout in milliseconds

Authentication

Methods (Priority Order)

  1. Explicit token — githubToken in constructor
  2. Environment variables — COPILOT_GITHUB_TOKEN → GH_TOKEN → GITHUB_TOKEN
  3. Stored OAuth — From copilot auth login
  4. GitHub CLI — gh auth credentials

Programmatic Token

const client = new CopilotClient({ githubToken: process.env.GITHUB_TOKEN });

BYOK (Bring Your Own Key)

Use your own API keys — no Copilot subscription required.

const session = await client.createSession({
    model: "gpt-5.2-codex",
    provider: {
        type: "openai",
        baseUrl: "https://your-resource.openai.azure.com/openai/v1/",
        wireApi: "responses",
        apiKey: process.env.FOUNDRY_API_KEY,
    },
});
ProviderTypeNotes
OpenAI"openai"OpenAI API and compatible endpoints
Azure OpenAI"azure"Native Azure endpoints (don't include /openai/v1)
Azure AI Foundry"openai"OpenAI-compatible Foundry endpoints
Anthropic"anthropic"Claude models
Ollama"openai"Local models, no API key needed

Wire API: Use "responses" for GPT-5 series, "completions" (default) for others.

Session Persistence

Resume sessions across restarts by providing your own session ID.

// Create with explicit ID
const session = await client.createSession({
    sessionId: "user-123-task-456",
    model: "gpt-4.1",
});

// Resume later
const resumed = await client.resumeSession("user-123-task-456");
await resumed.sendAndWait({ prompt: "What did we discuss?" });

Session management:

const sessions = await client.listSessions();          // List all
await client.deleteSession("user-123-task-456");       // Delete
await session.destroy();                                // Destroy active

BYOK sessions: Must re-provide provider config on resume (keys are not persisted).

Infinite Sessions

For long-running workflows that may exceed context limits:

const session = await client.createSession({
    infiniteSessions: {
        enabled: true,
        backgroundCompactionThreshold: 0.80,
        bufferExhaustionThreshold: 0.95,
    },
});

Custom Agents

Define specialized AI personas:

const session = await client.createSession({
    customAgents: [{
        name: "pr-reviewer",
        displayName: "PR Reviewer",
        description: "Reviews pull requests for best practices",
        prompt: "You are an expert code reviewer. Focus on security, performance, and maintainability.",
    }],
});

System Message

Control AI behavior and personality:

const session = await client.createSession({
    systemMessage: { content: "You are a helpful assistant. Always be concise." },
});

Skills Integration

Load skill directories to extend Copilot's capabilities:

const session = await client.createSession({
    skillDirectories: ["./skills/code-review", "./skills/documentation"],
    disabledSkills: ["experimental-feature"],
});

Permission & Input Handlers

Handle tool permissions and user input requests programmatically:

const session = await client.createSession({
    onPermissionRequest: async (request) => {
        // Auto-approve git commands only
        if (request.kind === "shell") {
            return { approved: request.command.startsWith("git") };
        }
        return { approved: true };
    },
    onUserInputRequest: async (request) => {
        // Handle ask_user tool calls
        return { response: "yes" };
    },
});

External CLI Server

Connect to a separately running CLI instead of auto-managing the process:

copilot --headless --port 4321

const client = new CopilotClient({ cliUrl: "localhost:4321" });

Client Configuration

OptionTypeDescription
cliPathstringPath to Copilot CLI executable
cliUrlstringURL of external CLI server
githubTokenstringGitHub token for auth
useLoggedInUserbooleanUse stored CLI credentials (default: true)
logLevelstring"none" | "error" | "warning" | "info" | "debug"
autoRestartbooleanAuto-restart CLI on crash (default: true)
useStdiobooleanUse stdio transport (default: true)

Session Configuration

OptionTypeDescription
modelstringModel to use (e.g., "gpt-4.1")
sessionIdstringCustom ID for resumable sessions
streamingbooleanEnable streaming responses
toolsTool[]Custom tools
mcpServersobjectMCP server configurations
hooksobjectSession hooks
providerobjectBYOK provider config
customAgentsobject[]Custom agent definitions
systemMessageobjectSystem message override
skillDirectoriesstring[]Directories to load skills from
disabledSkillsstring[]Skills to disable
reasoningEffortstringReasoning effort level
availableToolsstring[]Restrict available tools
excludedToolsstring[]Exclude specific tools
infiniteSessionsobjectAuto-compaction config
workingDirectorystringWorking directory

Debugging

Enable debug logging to troubleshoot issues:

const client = new CopilotClient({ logLevel: "debug" });

Common issues:

  • CLI not found → Install CLI or set cliPath
  • Not authenticated → Run copilot auth login or provide githubToken
  • Session not found → Don't use session after destroy()
  • Connection refused → Check CLI process, enable autoRestart

Key API Summary

LanguageClientSession CreateSendStop
Node.jsnew CopilotClient()client.createSession()session.sendAndWait()client.stop()
PythonCopilotClient()client.create_session()session.send_and_wait()client.stop()
Gocopilot.NewClient(nil)client.CreateSession()session.SendAndWait()client.Stop()
.NETnew CopilotClient()client.CreateSessionAsync()session.SendAndWaitAsync()client.DisposeAsync()

References

  • GitHub Copilot SDK
  • Copilot CLI Installation
  • MCP Protocol Specification

When to Use

This skill is applicable to execute the workflow or actions described in the overview.

Limitations

  • Use this skill only when the task clearly matches the scope described above.
  • Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
  • Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

Related skills

amazon-alexakubernetes-architectpostgresql-optimizationgit-workflow-and-versioningnextjs-app-router-patterns