Appendix 01: GitHub Copilot Spaces — persistent context beyond the repository

tech

prompt-engineering

github-copilot

copilot-spaces

Understand how GitHub Copilot Spaces provides persistent, shareable context that complements repository-level customization files for grounding Copilot’s responses

Author

Dario Airoldi

Published

February 22, 2026

Appendix 01: GitHub Copilot Spaces — persistent context beyond the repository

This appendix extends the series overview by covering a context mechanism that operates outside your repository: GitHub Copilot Spaces. Where prompt files, instructions, agents, and MCP servers all live inside your codebase, Spaces let you organize context at the GitHub platform level—persistent, shareable, and independent of any single repo.

Feature status: Copilot Spaces is in public preview as of February 2026. The feature is available to anyone with a Copilot license, including Copilot Free.

🎯 Why Spaces matter for prompt engineering
🏗️ What a Space contains
💡 How Spaces complement repository-level files
🛠️ Creating and populating a Space
💻 Using Spaces in your IDE
🤝 Collaboration and sharing
⚠️ Current limitations
📊 When to use what: decision guide
🎯 Conclusion
📚 References

🎯 Why Spaces matter for prompt engineering

Throughout this series, you’ve learned to provide Copilot with context through repository-level files: .github/prompts/, .github/instructions/, .github/agents/, and MCP servers. These mechanisms work well for project-specific context that lives alongside the code.

But some context doesn’t belong in a repository:

Cross-project knowledge — Architecture decisions that span multiple repos
Ephemeral context — Sprint plans, meeting transcripts, design documents that don’t belong in version control
External references — Pull requests, issues, uploaded documents, and images you want Copilot to reason about
Team onboarding — Curated knowledge bases that help new developers get up to speed

Copilot Spaces fills this gap. A Space is a persistent container for context that grounds Copilot’s responses in specific, curated information—without requiring that information to live in your repository.

🏗️ What a Space contains

A Space has two types of content:

Instructions

Free-text guidance that tells Copilot what to focus on within this Space. Think of these as the Space-level equivalent of a .instructions.md file—they set the role, scope, and boundaries.

You are a SQL generator. Your job is to take the sample queries
and data schemas defined in the attached files and generate SQL
queries based on the user's goals.

Instructions don’t get indexed for search—they’re injected directly into Copilot’s system prompt when you chat in the Space.

Sources

Content that Copilot uses to ground its responses. You can add four types of sources:

Source type	What it provides	How Copilot uses it
Files and repositories	Code, docs, configs from GitHub repos	Searches or loads into context window
Links	URLs to pull requests, issues, other GitHub content	Fetches and references the linked content
Uploaded files	Local documents, images, spreadsheets	Loads into context window
Text content	Pasted notes, transcripts, free-form text	Loads into context window

Key behavior difference between attaching a repository vs. individual files:

Repository: Copilot searches it—it doesn’t load everything into memory. Good for broad, large-scale context (e.g., “answer questions about our entire documentation”).
Individual files: Copilot loads the full contents into the context window for every query. Good for pinpointing specific documents you want Copilot to consistently prioritize.

GitHub-based sources stay automatically in sync. When a file changes on the main branch, the Space reflects the latest version.

💡 How Spaces complement repository-level files

Spaces don’t replace the customization stack you’ve learned in this series—they add a new layer. The table below shows how each context mechanism fits into the overall picture:

Mechanism	Scope	Lives in	Persistence	Best for
Prompt files (`.prompt.md`)	Project	Repository	Versioned with code	Reusable task templates
Instruction files (`.instructions.md`)	Project or path	Repository	Versioned with code	Coding standards, project rules
Agent files (`.agent.md`)	Project	Repository	Versioned with code	Specialized assistant roles
MCP servers	Project or global	Config files	Session-based	External tool access
Copilot Spaces	Cross-project	GitHub platform	Persistent, shareable	Curated knowledge bases, onboarding, ephemeral context

The key distinction: repository-level files are developer-authored, code-adjacent, and versioned. Spaces are curator-managed, platform-level, and independent of any single codebase.

Practical combination patterns

Pattern 1: Space as research context, repo files as execution rules A Space containing architecture documents, ADRs, and design specs grounds Copilot in what to build. Your repository’s instruction files and agent definitions control how to build it.

Pattern 2: Space for team standards, instructions for project conventions An org-wide Space with coding standards, review checklists, and accessibility guidelines provides the baseline. Project-level .instructions.md files add repo-specific conventions on top.

Pattern 3: Space for onboarding, agents for workflows A “Getting Started” Space curates the documents a new developer needs. Project agents automate the actual development workflows they’ll use daily.

🛠️ Creating and populating a Space

Create a Space

Go to github.com/copilot/spaces
Click Create space
Name it and choose an owner (personal account or organization)
Add a description (optional—helps others understand the Space’s purpose but doesn’t affect Copilot’s responses)

Add context

Once inside the Space, add sources:

Add files and repositories — Browse GitHub repos and select files, folders, or entire repositories
Link content — Paste URLs to pull requests, issues, or other GitHub content
Upload files — Drag in local documents, images, or spreadsheets
Add text — Paste free-form notes, meeting transcripts, or specifications

You can also add files to a Space directly from the code view on GitHub—click the Add to space icon at the top of any file.

Write instructions

Add instructions that define the Space’s focus:

You are an expert in our authentication system. Help developers understand
and work with our OAuth 2.0 implementation.

Focus on:
- The authentication flow defined in the API gateway docs
- Token refresh patterns from the backend service
- Error handling conventions from our coding standards

Don't make assumptions about config values—always reference the attached files.

💻 Using Spaces in your IDE

You can access Space context from any IDE that supports the GitHub Copilot extension and the GitHub MCP server.

Prerequisites

Set up the remote GitHub MCP server for your IDE
Enable the Spaces toolset in your MCP configuration—it’s not included by default

Add the X-MCP-Toolsets header to enable both default tools and Spaces:

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "X-MCP-Toolsets": "default,copilot_spaces"
      }
    }
  }
}

Alternatively, use the dedicated Spaces-only endpoint: https://api.githubcopilot.com/mcp/x/copilot_spaces (this provides only Spaces tools, without other GitHub MCP server functionality).

Access Space context

Spaces work in agent mode only, since they’re accessed via MCP tools.

Open Copilot Chat and select Agent mode
Verify the Spaces tools are enabled: click the tools icon and confirm get_copilot_space and list_copilot_spaces appear under MCP Server: github
Reference the Space by name in your prompt:

Using the Copilot space "Checkout Flow Redesign" owned by myorganization,
summarize the implementation plan.

Copilot automatically uses list_copilot_spaces to find matching Spaces. Follow-up prompts in the same conversation have access to the same Space context without re-referencing it.

IDE limitation: When using Spaces in your IDE, repository context within the Space isn’t supported. You’ll have access to all other sources and instructions from the Space.

🤝 Collaboration and sharing

Spaces support GitHub’s permission model for sharing:

Organization-owned Spaces

Role	Permissions
Viewer	Use the Space to ask questions, view sources and instructions
Editor	Update sources, description, name, instructions (plus all Viewer permissions)
Admin	Update sharing settings, delete the Space (plus all Editor permissions)
No access	Space is hidden from other organization members

Personal Spaces

Personal Spaces can be shared publicly (view-only), shared with specific GitHub users, or kept private.

Collaboration use cases

Onboarding: Share a Space with code, documentation, and checklists so new developers get started faster
System knowledge: Create a Space for a complex system (authentication, CI pipelines) that others can reference
Style guides: Document standards and examples that Copilot references when suggesting changes
Accessibility reviews: Combine internal checklists, product guidelines, and WCAG documentation into a single Space

⚠️ Current limitations

As a public preview feature, Spaces has some boundaries to keep in mind:

Limitation	Impact	Workaround
IDE: no repository context	Repository sources in a Space aren’t available when accessed from IDE	Attach individual files instead of full repositories
Agent mode only (IDE)	Can’t use Spaces in ask mode or edit mode	Switch to agent mode when you need Space context
No API for automation	Can’t programmatically create or update Spaces	Use the GitHub web UI
Usage counts toward limits	Each query counts as a Copilot Chat request; premium models apply multipliers	Choose standard models for high-volume Space usage

📊 When to use what: decision guide

Use this flowchart to decide which context mechanism fits your need:

Does this context belong in version control?
├── Yes → Is it project-specific?
│   ├── Yes → Use .instructions.md, .prompt.md, or .agent.md
│   └── No (cross-project) → Consider user-level instructions or context files
└── No → Does it need to be shared with a team?
    ├── Yes → Use Copilot Spaces (organization-owned)
    └── No → Is it ephemeral (sprint notes, transcripts)?
        ├── Yes → Use Copilot Spaces (personal)
        └── No → Use .copilot/context/ for local context

Quick rules:

Code conventions, project rules → .instructions.md (versioned, path-scoped)
Reusable task templates → .prompt.md (versioned, slash-command accessible)
External tool access → MCP servers (configurable, session-scoped)
Cross-repo knowledge, onboarding, ephemeral docs → Copilot Spaces (persistent, shareable)

🎯 Conclusion

Copilot Spaces adds a platform-level context mechanism that complements the repository-level customization stack. Here are the key takeaways:

Spaces organize persistent context that doesn’t belong in your codebase—architecture docs, transcripts, external references, and curated knowledge bases
They don’t replace repository-level files—they fill the gap for cross-project and ephemeral context that prompt files, instructions, agents, and MCP servers don’t cover
IDE access requires MCP configuration with the copilot_spaces toolset explicitly enabled
GitHub sources stay in sync automatically, keeping your Space context current as code evolves
Sharing uses GitHub’s permission model, making Spaces practical for team onboarding and collaborative knowledge management

For the repository-level customization stack, see The GitHub Copilot customization stack. For external tool integration, see article 07: How to Create MCP Servers for Copilot.

📚 References

About GitHub Copilot Spaces 📘 [Official]
Conceptual overview of what Spaces are, who can use them, sharing options, and usage costs. Start here for the big picture.

Creating GitHub Copilot Spaces 📘 [Official]
Step-by-step guide for creating Spaces, adding sources (repos, files, uploads, text), and writing instructions. The primary how-to reference.

Using GitHub Copilot Spaces 📘 [Official]
Covers using Spaces in GitHub’s web UI and in your IDE via the GitHub MCP server, including the X-MCP-Toolsets configuration.

Collaborating with others using GitHub Copilot Spaces 📘 [Official]
Sharing options for organization-owned and personal Spaces, permission roles (viewer, editor, admin), and collaboration use cases.

Setting up the GitHub MCP Server 📘 [Official]
Prerequisites for accessing Spaces from your IDE. Covers MCP server setup, authentication, and toolset configuration.

The GitHub Copilot customization stack [📙 Internal]
The series overview article. Covers the full repository-level customization stack that Spaces complements.

Appendix 01: GitHub Copilot Spaces — persistent context beyond the repository

Table of contents

🎯 Why Spaces matter for prompt engineering

🏗️ What a Space contains

Instructions

Sources

💡 How Spaces complement repository-level files

Practical combination patterns

🛠️ Creating and populating a Space

Create a Space

Add context

Write instructions

💻 Using Spaces in your IDE

Prerequisites

Access Space context

🤝 Collaboration and sharing

Organization-owned Spaces

Personal Spaces

Collaboration use cases

⚠️ Current limitations

📊 When to use what: decision guide

🎯 Conclusion

📚 References