From 1ab54a680f946e4f8b129c5498f37089fe2760a5 Mon Sep 17 00:00:00 2001 From: Tadas Labudis Date: Thu, 5 Mar 2026 11:36:12 +0000 Subject: [PATCH 1/3] Add copilot-spaces skill for loading project-specific context New skill that teaches agents to use Copilot Spaces MCP tools (list_copilot_spaces, get_copilot_space) to discover and load curated project context into conversations. Covers discovery workflow, loading spaces by owner/name, and using space content to ground responses in team-specific docs, code, and standards. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/README.skills.md | 1 + skills/copilot-spaces/SKILL.md | 92 ++++++++++++++++++++++++++++++++++ 2 files changed, 93 insertions(+) create mode 100644 skills/copilot-spaces/SKILL.md diff --git a/docs/README.skills.md b/docs/README.skills.md index e90a64b73..ca41e425a 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -64,6 +64,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [copilot-cli-quickstart](../skills/copilot-cli-quickstart/SKILL.md) | Use this skill when someone wants to learn GitHub Copilot CLI from scratch. Offers interactive step-by-step tutorials with separate Developer and Non-Developer tracks, plus on-demand Q&A. Just say "start tutorial" or ask a question! Note: This skill targets GitHub Copilot CLI specifically and uses CLI-specific tools (ask_user, sql, fetch_copilot_cli_documentation). | None | | [copilot-instructions-blueprint-generator](../skills/copilot-instructions-blueprint-generator/SKILL.md) | Technology-agnostic blueprint generator for creating comprehensive copilot-instructions.md files that guide GitHub Copilot to produce code consistent with project standards, architecture patterns, and exact technology versions by analyzing existing codebase patterns and avoiding assumptions. | None | | [copilot-sdk](../skills/copilot-sdk/SKILL.md) | Build agentic applications with GitHub Copilot SDK. Use when embedding AI agents in apps, creating custom tools, implementing streaming responses, managing sessions, connecting to MCP servers, or creating custom agents. Triggers on Copilot SDK, GitHub SDK, agentic app, embed Copilot, programmable agent, MCP server, custom agent. | None | +| [copilot-spaces](../skills/copilot-spaces/SKILL.md) | Use Copilot Spaces to provide project-specific context to conversations. Use this skill when users mention a "Copilot space", want to load context from a shared knowledge base, discover available spaces, or ask questions grounded in curated project documentation, code, and instructions. | None | | [copilot-usage-metrics](../skills/copilot-usage-metrics/SKILL.md) | Retrieve and display GitHub Copilot usage metrics for organizations and enterprises using the GitHub CLI and REST API. | `get-enterprise-metrics.sh`
`get-enterprise-user-metrics.sh`
`get-org-metrics.sh`
`get-org-user-metrics.sh` | | [cosmosdb-datamodeling](../skills/cosmosdb-datamodeling/SKILL.md) | Step-by-step guide for capturing key application requirements for NoSQL use-case and produce Azure Cosmos DB Data NoSQL Model design using best practices and common patterns, artifacts_produced: "cosmosdb_requirements.md" file and "cosmosdb_data_model.md" file | None | | [create-agentsmd](../skills/create-agentsmd/SKILL.md) | Prompt for generating an AGENTS.md file for a repository | None | diff --git a/skills/copilot-spaces/SKILL.md b/skills/copilot-spaces/SKILL.md new file mode 100644 index 000000000..fed6f6b61 --- /dev/null +++ b/skills/copilot-spaces/SKILL.md @@ -0,0 +1,92 @@ +--- +name: copilot-spaces +description: 'Use Copilot Spaces to provide project-specific context to conversations. Use this skill when users mention a "Copilot space", want to load context from a shared knowledge base, discover available spaces, or ask questions grounded in curated project documentation, code, and instructions.' +--- + +# Copilot Spaces + +Use Copilot Spaces to bring curated, project-specific context into conversations. A Space is a shared collection of repositories, files, documentation, and instructions that grounds Copilot responses in your team's actual code and knowledge. + +## Available MCP Tools + +| Tool | Purpose | +|------|---------| +| `mcp__github__list_copilot_spaces` | List all spaces accessible to the current user | +| `mcp__github__get_copilot_space` | Load a space's full context by owner and name | + +## When to Use Spaces + +- User mentions "Copilot space" or asks to "load a space" +- User wants answers grounded in specific project docs, code, or standards +- User asks "what spaces are available?" or "find a space for X" +- User needs onboarding context, architecture docs, or team-specific guidance +- User wants to debug or understand code using curated project context + +## Workflow + +### 1. Discover Spaces + +When a user asks what spaces are available or you need to find the right space: + +``` +Call mcp__github__list_copilot_spaces +``` + +This returns all spaces the user can access, each with a `name` and `owner_login`. Present relevant matches to the user. + +### 2. Load a Space + +When a user names a specific space or you've identified the right one: + +``` +Call mcp__github__get_copilot_space with: + owner: "org-or-user" (the owner_login from the list) + name: "Space Name" (exact space name, case-sensitive) +``` + +This returns the space's full content: attached documentation, code context, custom instructions, and any other curated materials. Use this context to inform your responses. + +### 3. Answer Using Space Context + +Once loaded, the space content becomes part of your context. Use it to: +- Answer questions about the project's architecture, patterns, or standards +- Generate code that follows the team's conventions +- Explain how specific systems work based on internal docs +- Debug issues using project-specific knowledge + +## Examples + +### Example 1: User Asks for a Space + +**User**: "Load the Accessibility copilot space" + +**Action**: +1. Call `mcp__github__get_copilot_space` with owner `"github"`, name `"Accessibility"` +2. Use the returned context to answer questions about accessibility standards, MAS grades, compliance processes, etc. + +### Example 2: User Wants to Find Spaces + +**User**: "What copilot spaces are available for our team?" + +**Action**: +1. Call `mcp__github__list_copilot_spaces` +2. Filter/present spaces relevant to the user's org or interests +3. Offer to load any space they're interested in + +### Example 3: Context-Grounded Question + +**User**: "Using the security space, what's our policy on secret scanning?" + +**Action**: +1. Call `mcp__github__get_copilot_space` with the appropriate owner and name +2. Find the relevant policy in the space content +3. Answer based on the actual internal documentation + +## Tips + +- Space names are **case-sensitive** -- use the exact name from `list_copilot_spaces` +- Spaces can be owned by users or organizations -- always provide both `owner` and `name` +- Space content can be large (docs, code, instructions) -- focus on the parts relevant to the user's question +- If a space isn't found, suggest listing available spaces to find the right name +- Spaces auto-update as underlying repos change, so the context is always current +- Some spaces contain custom instructions that should guide your behavior (coding standards, preferred patterns, etc.) From b65ec8988a889214054c04f817418408e482249d Mon Sep 17 00:00:00 2001 From: Tadas Labudis Date: Thu, 5 Mar 2026 12:24:43 +0000 Subject: [PATCH 2/3] Improve copilot-spaces skill with real-world usage patterns - Add 'Spaces as workflow engines' pattern for multi-step processes - Add 'Follow the breadcrumbs' step for fetching referenced resources - Document read-only API limitation (no create/update/delete) - Add filtering tip for list_copilot_spaces by owner - Add large output handling guidance (20KB+ spaces) - Add Example 4: Space as a workflow engine - Strengthen tips with actionable guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- skills/copilot-spaces/SKILL.md | 50 +++++++++++++++++++++++++++------- 1 file changed, 40 insertions(+), 10 deletions(-) diff --git a/skills/copilot-spaces/SKILL.md b/skills/copilot-spaces/SKILL.md index fed6f6b61..6f582e178 100644 --- a/skills/copilot-spaces/SKILL.md +++ b/skills/copilot-spaces/SKILL.md @@ -14,13 +14,15 @@ Use Copilot Spaces to bring curated, project-specific context into conversations | `mcp__github__list_copilot_spaces` | List all spaces accessible to the current user | | `mcp__github__get_copilot_space` | Load a space's full context by owner and name | +**Note:** Spaces are **read-only** via the API. You can list and load spaces, but cannot create, update, or delete them. If a user wants to edit a Space, direct them to the web UI at `github.com/copilot/spaces`. + ## When to Use Spaces - User mentions "Copilot space" or asks to "load a space" - User wants answers grounded in specific project docs, code, or standards - User asks "what spaces are available?" or "find a space for X" - User needs onboarding context, architecture docs, or team-specific guidance -- User wants to debug or understand code using curated project context +- User wants to follow a structured workflow defined in a Space (templates, checklists, multi-step processes) ## Workflow @@ -34,6 +36,8 @@ Call mcp__github__list_copilot_spaces This returns all spaces the user can access, each with a `name` and `owner_login`. Present relevant matches to the user. +To filter for a specific user's spaces, match `owner_login` against the username (e.g., "show me my spaces"). + ### 2. Load a Space When a user names a specific space or you've identified the right one: @@ -46,14 +50,28 @@ Call mcp__github__get_copilot_space with: This returns the space's full content: attached documentation, code context, custom instructions, and any other curated materials. Use this context to inform your responses. -### 3. Answer Using Space Context +### 3. Follow the Breadcrumbs + +Space content often references external resources: GitHub issues, dashboards, repos, discussions, or other tools. Proactively fetch these using other MCP tools to gather complete context. For example: +- A space references an initiative tracking issue. Use `issue_read` to get the latest comments. +- A space links to a project board. Use project tools to check current status. +- A space mentions a repo's masterplan. Use `get_file_contents` to read it. + +### 4. Answer or Execute + +Once loaded, use the space content based on what it contains: -Once loaded, the space content becomes part of your context. Use it to: +**If the space contains reference material** (docs, code, standards): - Answer questions about the project's architecture, patterns, or standards - Generate code that follows the team's conventions -- Explain how specific systems work based on internal docs - Debug issues using project-specific knowledge +**If the space contains workflow instructions** (templates, step-by-step processes): +- Follow the workflow as defined, step by step +- Gather data from the sources the workflow specifies +- Produce output in the format the workflow defines +- Show progress after each step so the user can steer + ## Examples ### Example 1: User Asks for a Space @@ -82,11 +100,23 @@ Once loaded, the space content becomes part of your context. Use it to: 2. Find the relevant policy in the space content 3. Answer based on the actual internal documentation +### Example 4: Space as a Workflow Engine + +**User**: "Write my weekly update using the PM Weekly Updates space" + +**Action**: +1. Call `mcp__github__get_copilot_space` to load the space. It contains a template format and step-by-step instructions. +2. Follow the space's workflow: pull data from attached initiative issues, gather metrics, draft each section. +3. Fetch external resources referenced by the space (tracking issues, dashboards) using other MCP tools. +4. Show the draft after each section so the user can review and fill in gaps. +5. Produce the final output in the format the space defines. + ## Tips -- Space names are **case-sensitive** -- use the exact name from `list_copilot_spaces` -- Spaces can be owned by users or organizations -- always provide both `owner` and `name` -- Space content can be large (docs, code, instructions) -- focus on the parts relevant to the user's question -- If a space isn't found, suggest listing available spaces to find the right name -- Spaces auto-update as underlying repos change, so the context is always current -- Some spaces contain custom instructions that should guide your behavior (coding standards, preferred patterns, etc.) +- Space names are **case-sensitive**. Use the exact name from `list_copilot_spaces`. +- Spaces can be owned by users or organizations. Always provide both `owner` and `name`. +- Space content can be large (20KB+). If returned as a temp file, use grep or view_range to find relevant sections rather than reading everything at once. +- If a space isn't found, suggest listing available spaces to find the right name. +- Spaces auto-update as underlying repos change, so the context is always current. +- Some spaces contain custom instructions that should guide your behavior (coding standards, preferred patterns, workflows). Treat these as directives, not suggestions. +- Spaces cannot be edited via the API. Direct users to `github.com/copilot/spaces` to modify Space settings, attached files, or instructions. From 6e11951db7e0cb83d1bbcf865ab36e26283e8bcc Mon Sep 17 00:00:00 2001 From: Tadas Labudis Date: Thu, 5 Mar 2026 12:41:00 +0000 Subject: [PATCH 3/3] Add Spaces CRUD REST API to copilot-spaces skill - Document full CRUD API endpoints (create, update, delete, collaborators) - Add 'Managing Spaces' workflow section with gh api examples - Add Example 5: updating Space instructions programmatically - Fix incorrect 'read-only' claim - MCP is read-only, REST API is full CRUD - Add scope requirements (user scope for writes) - Add resource management tips (array replacement, _destroy) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- skills/copilot-spaces/SKILL.md | 89 ++++++++++++++++++++++++++++++++-- 1 file changed, 86 insertions(+), 3 deletions(-) diff --git a/skills/copilot-spaces/SKILL.md b/skills/copilot-spaces/SKILL.md index 6f582e178..616952af9 100644 --- a/skills/copilot-spaces/SKILL.md +++ b/skills/copilot-spaces/SKILL.md @@ -7,14 +7,36 @@ description: 'Use Copilot Spaces to provide project-specific context to conversa Use Copilot Spaces to bring curated, project-specific context into conversations. A Space is a shared collection of repositories, files, documentation, and instructions that grounds Copilot responses in your team's actual code and knowledge. -## Available MCP Tools +## Available Tools + +### MCP Tools (Read-only) | Tool | Purpose | |------|---------| | `mcp__github__list_copilot_spaces` | List all spaces accessible to the current user | | `mcp__github__get_copilot_space` | Load a space's full context by owner and name | -**Note:** Spaces are **read-only** via the API. You can list and load spaces, but cannot create, update, or delete them. If a user wants to edit a Space, direct them to the web UI at `github.com/copilot/spaces`. +### REST API via `gh api` (Full CRUD) + +The Spaces REST API supports creating, updating, deleting spaces, and managing collaborators. The MCP server only exposes read operations, so use `gh api` for writes. + +**User Spaces:** + +| Method | Endpoint | Purpose | +|--------|----------|---------| +| `POST` | `/users/{username}/copilot-spaces` | Create a space | +| `GET` | `/users/{username}/copilot-spaces` | List spaces | +| `GET` | `/users/{username}/copilot-spaces/{number}` | Get a space | +| `PUT` | `/users/{username}/copilot-spaces/{number}` | Update a space | +| `DELETE` | `/users/{username}/copilot-spaces/{number}` | Delete a space | + +**Organization Spaces:** Same pattern under `/orgs/{org}/copilot-spaces/...` + +**Collaborators:** Add, list, update, and remove collaborators at `.../collaborators` + +**Scope requirements:** PAT needs `read:user` for reads, `user` for writes. Add with `gh auth refresh -h github.com -s user`. + +**Note:** This API is functional but not yet in the public REST API docs. It may require the `copilot_spaces_api` feature flag. ## When to Use Spaces @@ -72,6 +94,53 @@ Once loaded, use the space content based on what it contains: - Produce output in the format the workflow defines - Show progress after each step so the user can steer +### 5. Manage Spaces (via `gh api`) + +When a user wants to create, update, or delete a space, use `gh api`. First, find the space number from the list endpoint. + +**Update a space's instructions:** +```bash +gh api users/{username}/copilot-spaces/{number} \ + -X PUT \ + -f general_instructions="New instructions here" +``` + +**Update name, description, or instructions together:** +```bash +gh api users/{username}/copilot-spaces/{number} \ + -X PUT \ + -f name="Updated Name" \ + -f description="Updated description" \ + -f general_instructions="Updated instructions" +``` + +**Create a new space:** +```bash +gh api users/{username}/copilot-spaces \ + -X POST \ + -f name="My New Space" \ + -f general_instructions="Help me with..." \ + -f visibility="private" +``` + +**Attach resources (replaces entire resource list):** +```json +{ + "resources_attributes": [ + { "resource_type": "free_text", "metadata": { "name": "Notes", "text": "Content here" } }, + { "resource_type": "github_issue", "metadata": { "repository_id": 12345, "number": 42 } }, + { "resource_type": "github_file", "metadata": { "repository_id": 12345, "file_path": "docs/guide.md" } } + ] +} +``` + +**Delete a space:** +```bash +gh api users/{username}/copilot-spaces/{number} -X DELETE +``` + +**Updatable fields:** `name`, `description`, `general_instructions`, `icon_type`, `icon_color`, `visibility` ("private"/"public"), `base_role` ("no_access"/"reader"), `resources_attributes` + ## Examples ### Example 1: User Asks for a Space @@ -111,6 +180,19 @@ Once loaded, use the space content based on what it contains: 4. Show the draft after each section so the user can review and fill in gaps. 5. Produce the final output in the format the space defines. +### Example 5: Update Space Instructions Programmatically + +**User**: "Update my PM Weekly Updates space to include a new writing guideline" + +**Action**: +1. Call `mcp__github__list_copilot_spaces` and find the space number (e.g., 19). +2. Call `mcp__github__get_copilot_space` to read current instructions. +3. Modify the instructions text as requested. +4. Push the update: +```bash +gh api users/labudis/copilot-spaces/19 -X PUT -f general_instructions="updated instructions..." +``` + ## Tips - Space names are **case-sensitive**. Use the exact name from `list_copilot_spaces`. @@ -119,4 +201,5 @@ Once loaded, use the space content based on what it contains: - If a space isn't found, suggest listing available spaces to find the right name. - Spaces auto-update as underlying repos change, so the context is always current. - Some spaces contain custom instructions that should guide your behavior (coding standards, preferred patterns, workflows). Treat these as directives, not suggestions. -- Spaces cannot be edited via the API. Direct users to `github.com/copilot/spaces` to modify Space settings, attached files, or instructions. +- **Write operations** (`gh api` for create/update/delete) require the `user` PAT scope. If you get a 404 on write operations, run `gh auth refresh -h github.com -s user`. +- Resource updates **replace the entire array**. To add a resource, include all existing resources plus the new one. To remove one, include `{ "id": 123, "_destroy": true }` in the array.