How to Use Prompts with the GitHub Copilot SDK

Learn how to consume prompt files, agent definitions, instruction files, and MCP servers from SDK-based applications using the GitHub Copilot SDK

Author

Dario Airoldi

Published

February 20, 2026

How to Use Prompts with the GitHub Copilot SDK

The GitHub Copilot SDK (announced January 2026, technical preview) brings Copilot’s agentic loop to any application—not just VS Code or the CLI. Available for Node.js, Python, Go, and .NET, it lets you embed the same agent runtime that powers Copilot Chat into your own apps.

This article focuses on how SDK-based applications consume the same prompt engineering artifacts documented throughout this series: prompt files, instruction files, agent definitions, skills, and MCP servers. If you’ve been following articles 01–13, everything you’ve learned applies directly to SDK apps.

🎯 What the SDK is and how it differs
🏗️ Architecture overview
⚡ Setting up the SDK
📝 Prompt file consumption in SDK apps
🤖 Agent definitions and skill files
📋 Instruction files for behavioral constraints
🔌 MCP server integration
🎚️ Multi-model routing
💾 Memory and persistence
🔧 Practical example: documentation review agent
⚠️ Limitations and considerations
🎯 Conclusion
📚 References

🎯 What the SDK is and how it differs

Editor vs. SDK: two surfaces, one prompt format

The key insight for prompt engineers is simple: the SDK consumes the same files you already write.

Surface	How you interact	Prompt discovery	Tool access
VS Code	Chat panel, slash commands	`/promptName` from `.github/prompts/`	Built-in + MCP servers
Copilot CLI	Terminal commands	Workspace scanning	Built-in + MCP servers
SDK Apps	Programmatic API calls	Workspace scanning via SDK client	Custom tools + MCP servers

The SDK doesn’t introduce a new prompt format. It reuses .prompt.md, .agent.md, .instructions.md, and SKILL.md files exactly as documented in articles 01–06 of this series.

What’s different

The SDK surface lacks an editor UI, which means:

❌ No #file references (there’s no file picker)
❌ No slash commands or hashtag commands (there’s no chat input with autocomplete)
❌ No chat modes (Agent, Plan, Ask, Edit)
✅ Prompts are loaded programmatically or via workspace scanning
✅ All behavioral rules from instruction files still apply
✅ MCP servers work identically

🏗️ Architecture overview

The SDK uses a client-server architecture where your application communicates with the Copilot CLI running in server mode:

┌─────────────────────────┐
│    Your Application     │
│  (Node.js/Python/Go/.NET) │
└────────┬────────────────┘
         │ JSON-RPC
         ▼
┌─────────────────────────┐
│   Copilot CLI           │
│   (server mode)         │
│                         │
│  ┌───────────────────┐  │
│  │ Prompt Files      │  │
│  │ Agent Definitions │  │
│  │ Instruction Files │  │
│  │ MCP Servers       │  │
│  └───────────────────┘  │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│   Copilot API → Models  │
│   (GPT-5, Claude, etc.) │
└─────────────────────────┘

The SDK manages the CLI process lifecycle automatically. The CLI performs workspace scanning to discover your prompt engineering artifacts—just as it would when running in terminal mode.

⚡ Setting up the SDK

Prerequisites

GitHub Copilot subscription — Required (free tier available with limited usage)
Copilot CLI — Must be installed separately; the SDK communicates with it in server mode
Supported runtime — Node.js 18+, Python 3.10+, Go 1.21+, or .NET 8.0+

Installation

# Node.js / TypeScript
npm install @github/copilot-sdk

# Python
pip install github-copilot-sdk

# Go
go get github.com/github/copilot-sdk/go

# .NET
dotnet add package GitHub.Copilot.SDK

Quick start (TypeScript)

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

// Initialize and start the client
const client = new CopilotClient();
await client.start();

// Create a session with a specific model
const session = await client.createSession({
    model: "gpt-5",
});

// Send a prompt
const response = await session.send({
    prompt: "Review this code for security vulnerabilities",
});

Quick start (Python)

from github_copilot_sdk import CopilotClient

# Initialize and start the client
client = CopilotClient()
await client.start()

# Create a session
session = await client.create_session(model="claude-sonnet-4")

# Send a prompt
response = await session.send(
    prompt="Analyze this architecture for scalability issues"
)

Quick start (.NET)

using GitHub.Copilot.SDK;

// Initialize and start the client
var client = new CopilotClient();
await client.StartAsync();

// Create a session
var session = await client.CreateSessionAsync(new SessionOptions
{
    Model = "gpt-5"
});

// Send a prompt
var response = await session.SendAsync("Review this code for security issues");

📝 Prompt file consumption in SDK apps

Workspace detection

When the SDK client starts, the CLI server scans the workspace for prompt files. The scanning follows the same rules documented in article 01:

.github/prompts/*.prompt.md — Workspace prompt files
.github/instructions/*.instructions.md — Path-specific instruction files
.github/copilot-instructions.md — Repo-level instructions
.github/agents/*.agent.md — Agent definitions
.github/skills/*/SKILL.md — Agent skills

Loading prompts programmatically

The most common pattern in SDK apps is to load prompt content directly rather than relying on slash commands:

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

// Load your prompt file content
const promptContent = readFileSync(
    ".github/prompts/security-review.prompt.md",
    "utf-8"
);

const client = new CopilotClient();
await client.start();

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

// Send the prompt content as a message
await session.send({ prompt: promptContent });

YAML frontmatter in SDK context

The YAML frontmatter fields in .prompt.md files behave differently in SDK apps:

Field	VS Code behavior	SDK behavior
`name`	Sets slash command name	Used for identification only
`description`	Shown in picker	Metadata only
`agent`	Sets chat mode	Agent definitions still applied
`model`	Sets session model	Respected if session allows override
`tools`	Restricts available tools	Restricts available tools ✅

The tools field is particularly important for SDK apps—it provides the same tool restriction behavior as in VS Code, ensuring your prompts don’t access tools they shouldn’t.

🤖 Agent definitions and skill files

Using agents with the SDK

Agent definitions (.agent.md) work in SDK apps by defining specialized personas with restricted tool sets. The SDK client can switch between agents just as VS Code switches chat modes:

const session = await client.createSession({
    model: "claude-opus-4.6",
    agent: "security-reviewer", // References .github/agents/security-reviewer.agent.md
});

The agent’s system prompt, tool restrictions, and behavioral instructions are automatically loaded from the .agent.md file. All the agent design patterns from article 04 apply directly.

Using skills with the SDK

Agent Skills (SKILL.md) are automatically discovered by the CLI’s workspace scanning. The SDK client can invoke skills that match the user’s intent:

// The CLI automatically matches skills based on the prompt content
await session.send({
    prompt: "Create a new article following our documentation standards",
    // The CLI identifies and loads the matching SKILL.md
});

For details on creating effective skills, see article 06.

📋 Instruction files for behavioral constraints

Instruction files (.instructions.md) are automatically applied by the CLI server based on applyTo glob patterns—exactly as in VS Code. You don’t need to load them manually.

How it works in SDK apps

The CLI server scans .github/instructions/ for instruction files
The applyTo pattern in the YAML frontmatter determines which files trigger the instructions
When your SDK app references a file matching the pattern, the instructions are injected into the context

This means all the instruction file patterns from article 05 work without modification.

Example: enforcing coding standards

If your workspace has .github/instructions/csharp.instructions.md with:

---
applyTo: "**/*.cs"
---

Then whenever the SDK session involves C# files, those instructions are automatically applied—the same behavior you’d see in VS Code.

🔌 MCP server integration

MCP servers are a first-class feature of the SDK. They work identically to VS Code’s MCP integration (see article 07 for building MCP servers).

Configuration

MCP servers are configured via mcp.json in your workspace, the same file VS Code uses:

{
  "servers": {
    "my-validation-server": {
      "command": "dotnet",
      "args": ["run", "--project", "src/McpServer/"]
    }
  }
}

The SDK client automatically discovers and connects to MCP servers defined in mcp.json.

Tool call flow

SDK App → sends prompt → CLI Server → calls model → model requests tool
                                                           ↓
                                                     MCP Server executes tool
                                                           ↓
                                                     result flows back to model
                                                           ↓
                                                     response to SDK App

The model handles tool invocation planning—you don’t need to manually orchestrate tool calls. The agentic loop in the CLI server manages the conversation turn, tool calls, and follow-up reasoning automatically.

🎚️ Multi-model routing

The SDK supports model selection per session, enabling the multi-model architecture patterns described in article 08.

Available models

SDK apps access models through the Copilot subscription, which currently includes:

Model	Provider	Best for
GPT-4o	OpenAI	General tasks, fast responses
GPT-5	OpenAI	Complex reasoning, broad domains
o3 / o4-mini	OpenAI	Mathematical and scientific reasoning
Claude Sonnet 4	Anthropic	Balanced coding and analysis
Claude Opus 4.6	Anthropic	Frontier agentic tasks, multi-step workflows
Gemini 2.0 Flash	Google	Fast inference, multimodal

Model-per-task pattern

// Use a fast model for simple classification
const triageSession = await client.createSession({ model: "gpt-4o" });
const category = await triageSession.send({
    prompt: "Classify this issue: " + issueText,
});

// Use a frontier model for complex analysis
const analysisSession = await client.createSession({ model: "claude-opus-4.6" });
const analysis = await analysisSession.send({
    prompt: "Perform deep security analysis on: " + codeText,
});

💾 Memory and persistence

The SDK provides persistent conversational memory across interactions within a session:

Session persistence — Context is maintained across multiple send() calls within the same session
Intelligent compaction — The SDK automatically compacts context when approaching token limits, preserving the most relevant information
Infinite sessions — Long-running workflows don’t fail from context overflow; the SDK manages compaction transparently

// Multi-turn conversation with persistent context
const session = await client.createSession({ model: "gpt-5" });

await session.send({ prompt: "Read the file src/auth/handler.ts" });
await session.send({ prompt: "What security issues do you see?" });
await session.send({ prompt: "Fix the SQL injection vulnerability you found" });
// Each turn has full context from previous turns

🔧 Practical example: documentation review agent

Here’s an end-to-end example that combines prompt files, agent definitions, and MCP servers to build a documentation review agent:

1. Agent definition

Create .github/agents/doc-reviewer.agent.md:

---
name: doc-reviewer
description: Reviews documentation articles for quality and consistency
tools:
  - read_file
  - grep_search
  - mcp: iqpilot
---

You're a documentation reviewer that checks articles against the team's writing
standards. For each article, check:

1. Structure follows the Di├ítaxis framework
2. References are properly classified
3. YAML frontmatter is complete
4. Writing tone matches Microsoft Voice Principles

2. Instruction file

The existing .github/instructions/documentation.instructions.md automatically applies to all .md files—no changes needed.

3. SDK application

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

async function reviewArticles() {
    const client = new CopilotClient();
    await client.start();

    // Create a session using the doc-reviewer agent
    const session = await client.createSession({
        model: "claude-opus-4.6",
        agent: "doc-reviewer",
    });

    // Find all articles to review
    const articles = readdirSync("03.00-tech/05.02-prompt-engineering/")
        .filter((f) => f.endsWith(".md"));

    for (const article of articles) {
        const result = await session.send({
            prompt: `Review the article: 03.00-tech/05.02-prompt-engineering/${article}`,
        });
        console.log(`Review for ${article}:`, result);
    }

    await client.stop();
}

reviewArticles();

This example leverages:

Agent definition — The doc-reviewer.agent.md provides the review persona and tool restrictions
Instruction files — Documentation standards are automatically injected via applyTo patterns
MCP server — The IQPilot MCP server provides validation tools
Model choice — Claude Opus 4.6 handles the nuanced writing analysis

⚠️ Limitations and considerations

Technical preview status

The GitHub Copilot SDK is in technical preview as of February 2026. This means:

⚠️ APIs may change in future releases
⚠️ Not recommended for production workloads without fallback strategies
⚠️ Feature parity across languages may vary during preview

Billing

SDK usage follows the same billing as Copilot CLI:

Each prompt counts toward your premium request quota
Enterprise and individual plans have different quotas
For details, see Requests in GitHub Copilot

Network dependency

The SDK requires connectivity to the Copilot service—it can’t run fully offline. The CLI server communicates with GitHub’s API for authentication and model access.

Differences from VS Code

Feature	VS Code	SDK Apps
Interactive file picker (`#file`)	✅	❌
Visual diff review	✅	❌
Chat history UI	✅	❌ (you manage)
Terminal integration	✅	❌ (you manage)
Prompt discovery UI	✅	❌ (programmatic)
MCP servers	✅	✅
Agent definitions	✅	✅
Instruction files	✅	✅

🎯 Conclusion

The GitHub Copilot SDK extends the prompt engineering practices you’ve learned throughout this series to any application surface. The key takeaways:

Same files, new surface — .prompt.md, .agent.md, .instructions.md, and SKILL.md files work in SDK apps without modification
Programmatic control — You get fine-grained control over session creation, model selection, and tool availability
MCP integration — Your custom MCP servers work identically in SDK apps
Multi-model routing — Apply the model-per-task patterns from article 08 with full flexibility
Preview status — The SDK is in technical preview; expect API evolution

Next in the series: Articles 15 and 16 will cover testing/iterating on prompts and versioning prompt libraries—topics that become even more critical when prompts are consumed by SDK applications.

📚 References

GitHub Copilot SDK Repository 📘 [Official]
The official SDK repository with installation guides, API references, and starter examples for all four supported languages.

GitHub Copilot SDK — Building Agents for Any Application 📗 [Verified Community]
Detailed analysis of the SDK announcement with architecture diagrams, comparison tables, and practical implications.

Requests in GitHub Copilot 📘 [Official]
Official GitHub documentation on billing and premium request quotas for Copilot CLI and SDK usage.

Model Context Protocol Specification 📘 [Official]
The MCP standard specification. SDK apps use MCP servers identically to VS Code.

How GitHub Copilot Uses Markdown and Prompt Folders 📗 [Verified Community]
The series overview article covering all Copilot customization surfaces, now updated with SDK Apps support.

How to Use Prompts with the GitHub Copilot SDK

Table of Contents

🎯 What the SDK is and how it differs

Editor vs. SDK: two surfaces, one prompt format

What’s different

🏗️ Architecture overview

⚡ Setting up the SDK

Prerequisites

Installation

Quick start (TypeScript)

Quick start (Python)

Quick start (.NET)

📝 Prompt file consumption in SDK apps

Workspace detection

Loading prompts programmatically

YAML frontmatter in SDK context

🤖 Agent definitions and skill files

Using agents with the SDK

Using skills with the SDK

📋 Instruction files for behavioral constraints

How it works in SDK apps

Example: enforcing coding standards

🔌 MCP server integration

Configuration

Tool call flow

🎚️ Multi-model routing

Available models

Model-per-task pattern

💾 Memory and persistence

🔧 Practical example: documentation review agent

1. Agent definition

2. Instruction file

3. SDK application

⚠️ Limitations and considerations

Technical preview status

Billing

Network dependency

Differences from VS Code

🎯 Conclusion

📚 References

📎 Related articles in this series