|
| 1 | +--- |
| 2 | +name: copilot-spaces |
| 3 | +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.' |
| 4 | +--- |
| 5 | + |
| 6 | +# Copilot Spaces |
| 7 | + |
| 8 | +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. |
| 9 | + |
| 10 | +## Available Tools |
| 11 | + |
| 12 | +### MCP Tools (Read-only) |
| 13 | + |
| 14 | +| Tool | Purpose | |
| 15 | +|------|---------| |
| 16 | +| `mcp__github__list_copilot_spaces` | List all spaces accessible to the current user | |
| 17 | +| `mcp__github__get_copilot_space` | Load a space's full context by owner and name | |
| 18 | + |
| 19 | +### REST API via `gh api` (Full CRUD) |
| 20 | + |
| 21 | +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. |
| 22 | + |
| 23 | +**User Spaces:** |
| 24 | + |
| 25 | +| Method | Endpoint | Purpose | |
| 26 | +|--------|----------|---------| |
| 27 | +| `POST` | `/users/{username}/copilot-spaces` | Create a space | |
| 28 | +| `GET` | `/users/{username}/copilot-spaces` | List spaces | |
| 29 | +| `GET` | `/users/{username}/copilot-spaces/{number}` | Get a space | |
| 30 | +| `PUT` | `/users/{username}/copilot-spaces/{number}` | Update a space | |
| 31 | +| `DELETE` | `/users/{username}/copilot-spaces/{number}` | Delete a space | |
| 32 | + |
| 33 | +**Organization Spaces:** Same pattern under `/orgs/{org}/copilot-spaces/...` |
| 34 | + |
| 35 | +**Collaborators:** Add, list, update, and remove collaborators at `.../collaborators` |
| 36 | + |
| 37 | +**Scope requirements:** PAT needs `read:user` for reads, `user` for writes. Add with `gh auth refresh -h github.com -s user`. |
| 38 | + |
| 39 | +**Note:** This API is functional but not yet in the public REST API docs. It may require the `copilot_spaces_api` feature flag. |
| 40 | + |
| 41 | +## When to Use Spaces |
| 42 | + |
| 43 | +- User mentions "Copilot space" or asks to "load a space" |
| 44 | +- User wants answers grounded in specific project docs, code, or standards |
| 45 | +- User asks "what spaces are available?" or "find a space for X" |
| 46 | +- User needs onboarding context, architecture docs, or team-specific guidance |
| 47 | +- User wants to follow a structured workflow defined in a Space (templates, checklists, multi-step processes) |
| 48 | + |
| 49 | +## Workflow |
| 50 | + |
| 51 | +### 1. Discover Spaces |
| 52 | + |
| 53 | +When a user asks what spaces are available or you need to find the right space: |
| 54 | + |
| 55 | +``` |
| 56 | +Call mcp__github__list_copilot_spaces |
| 57 | +``` |
| 58 | + |
| 59 | +This returns all spaces the user can access, each with a `name` and `owner_login`. Present relevant matches to the user. |
| 60 | + |
| 61 | +To filter for a specific user's spaces, match `owner_login` against the username (e.g., "show me my spaces"). |
| 62 | + |
| 63 | +### 2. Load a Space |
| 64 | + |
| 65 | +When a user names a specific space or you've identified the right one: |
| 66 | + |
| 67 | +``` |
| 68 | +Call mcp__github__get_copilot_space with: |
| 69 | + owner: "org-or-user" (the owner_login from the list) |
| 70 | + name: "Space Name" (exact space name, case-sensitive) |
| 71 | +``` |
| 72 | + |
| 73 | +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. |
| 74 | + |
| 75 | +### 3. Follow the Breadcrumbs |
| 76 | + |
| 77 | +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: |
| 78 | +- A space references an initiative tracking issue. Use `issue_read` to get the latest comments. |
| 79 | +- A space links to a project board. Use project tools to check current status. |
| 80 | +- A space mentions a repo's masterplan. Use `get_file_contents` to read it. |
| 81 | + |
| 82 | +### 4. Answer or Execute |
| 83 | + |
| 84 | +Once loaded, use the space content based on what it contains: |
| 85 | + |
| 86 | +**If the space contains reference material** (docs, code, standards): |
| 87 | +- Answer questions about the project's architecture, patterns, or standards |
| 88 | +- Generate code that follows the team's conventions |
| 89 | +- Debug issues using project-specific knowledge |
| 90 | + |
| 91 | +**If the space contains workflow instructions** (templates, step-by-step processes): |
| 92 | +- Follow the workflow as defined, step by step |
| 93 | +- Gather data from the sources the workflow specifies |
| 94 | +- Produce output in the format the workflow defines |
| 95 | +- Show progress after each step so the user can steer |
| 96 | + |
| 97 | +### 5. Manage Spaces (via `gh api`) |
| 98 | + |
| 99 | +When a user wants to create, update, or delete a space, use `gh api`. First, find the space number from the list endpoint. |
| 100 | + |
| 101 | +**Update a space's instructions:** |
| 102 | +```bash |
| 103 | +gh api users/{username}/copilot-spaces/{number} \ |
| 104 | + -X PUT \ |
| 105 | + -f general_instructions="New instructions here" |
| 106 | +``` |
| 107 | + |
| 108 | +**Update name, description, or instructions together:** |
| 109 | +```bash |
| 110 | +gh api users/{username}/copilot-spaces/{number} \ |
| 111 | + -X PUT \ |
| 112 | + -f name="Updated Name" \ |
| 113 | + -f description="Updated description" \ |
| 114 | + -f general_instructions="Updated instructions" |
| 115 | +``` |
| 116 | + |
| 117 | +**Create a new space:** |
| 118 | +```bash |
| 119 | +gh api users/{username}/copilot-spaces \ |
| 120 | + -X POST \ |
| 121 | + -f name="My New Space" \ |
| 122 | + -f general_instructions="Help me with..." \ |
| 123 | + -f visibility="private" |
| 124 | +``` |
| 125 | + |
| 126 | +**Attach resources (replaces entire resource list):** |
| 127 | +```json |
| 128 | +{ |
| 129 | + "resources_attributes": [ |
| 130 | + { "resource_type": "free_text", "metadata": { "name": "Notes", "text": "Content here" } }, |
| 131 | + { "resource_type": "github_issue", "metadata": { "repository_id": 12345, "number": 42 } }, |
| 132 | + { "resource_type": "github_file", "metadata": { "repository_id": 12345, "file_path": "docs/guide.md" } } |
| 133 | + ] |
| 134 | +} |
| 135 | +``` |
| 136 | + |
| 137 | +**Delete a space:** |
| 138 | +```bash |
| 139 | +gh api users/{username}/copilot-spaces/{number} -X DELETE |
| 140 | +``` |
| 141 | + |
| 142 | +**Updatable fields:** `name`, `description`, `general_instructions`, `icon_type`, `icon_color`, `visibility` ("private"/"public"), `base_role` ("no_access"/"reader"), `resources_attributes` |
| 143 | + |
| 144 | +## Examples |
| 145 | + |
| 146 | +### Example 1: User Asks for a Space |
| 147 | + |
| 148 | +**User**: "Load the Accessibility copilot space" |
| 149 | + |
| 150 | +**Action**: |
| 151 | +1. Call `mcp__github__get_copilot_space` with owner `"github"`, name `"Accessibility"` |
| 152 | +2. Use the returned context to answer questions about accessibility standards, MAS grades, compliance processes, etc. |
| 153 | + |
| 154 | +### Example 2: User Wants to Find Spaces |
| 155 | + |
| 156 | +**User**: "What copilot spaces are available for our team?" |
| 157 | + |
| 158 | +**Action**: |
| 159 | +1. Call `mcp__github__list_copilot_spaces` |
| 160 | +2. Filter/present spaces relevant to the user's org or interests |
| 161 | +3. Offer to load any space they're interested in |
| 162 | + |
| 163 | +### Example 3: Context-Grounded Question |
| 164 | + |
| 165 | +**User**: "Using the security space, what's our policy on secret scanning?" |
| 166 | + |
| 167 | +**Action**: |
| 168 | +1. Call `mcp__github__get_copilot_space` with the appropriate owner and name |
| 169 | +2. Find the relevant policy in the space content |
| 170 | +3. Answer based on the actual internal documentation |
| 171 | + |
| 172 | +### Example 4: Space as a Workflow Engine |
| 173 | + |
| 174 | +**User**: "Write my weekly update using the PM Weekly Updates space" |
| 175 | + |
| 176 | +**Action**: |
| 177 | +1. Call `mcp__github__get_copilot_space` to load the space. It contains a template format and step-by-step instructions. |
| 178 | +2. Follow the space's workflow: pull data from attached initiative issues, gather metrics, draft each section. |
| 179 | +3. Fetch external resources referenced by the space (tracking issues, dashboards) using other MCP tools. |
| 180 | +4. Show the draft after each section so the user can review and fill in gaps. |
| 181 | +5. Produce the final output in the format the space defines. |
| 182 | + |
| 183 | +### Example 5: Update Space Instructions Programmatically |
| 184 | + |
| 185 | +**User**: "Update my PM Weekly Updates space to include a new writing guideline" |
| 186 | + |
| 187 | +**Action**: |
| 188 | +1. Call `mcp__github__list_copilot_spaces` and find the space number (e.g., 19). |
| 189 | +2. Call `mcp__github__get_copilot_space` to read current instructions. |
| 190 | +3. Modify the instructions text as requested. |
| 191 | +4. Push the update: |
| 192 | +```bash |
| 193 | +gh api users/labudis/copilot-spaces/19 -X PUT -f general_instructions="updated instructions..." |
| 194 | +``` |
| 195 | + |
| 196 | +## Tips |
| 197 | + |
| 198 | +- Space names are **case-sensitive**. Use the exact name from `list_copilot_spaces`. |
| 199 | +- Spaces can be owned by users or organizations. Always provide both `owner` and `name`. |
| 200 | +- 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. |
| 201 | +- If a space isn't found, suggest listing available spaces to find the right name. |
| 202 | +- Spaces auto-update as underlying repos change, so the context is always current. |
| 203 | +- Some spaces contain custom instructions that should guide your behavior (coding standards, preferred patterns, workflows). Treat these as directives, not suggestions. |
| 204 | +- **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`. |
| 205 | +- 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. |
0 commit comments