Skip to content

Commit cee2d67

Browse files
SamMorrowDrumsCopilot
SamMorrowDrums
and
Copilot
committed
docs: add skill resources documentation
Document the 27 workflow-oriented skills, their structure (frontmatter with name, description, allowed-tools + markdown body), and design decisions (workflow-oriented, identity-aware, trigger-friendly). Explains the migration from server instructions to skill:// resources and links to the mcpi-ext server developer guide, skills mechanism docs, and progressive tool discovery documentation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 1a39440 commit cee2d67

1 file changed

Lines changed: 193 additions & 0 deletions

File tree

‎docs/skills.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# Skill Resources for Progressive Tool Discovery
2+
3+
This document describes how the GitHub MCP Server uses **skill resources** to enable progressive tool discovery — letting clients load only the tools and guidance relevant to the current task, rather than exposing everything at once.
4+
5+
## Background: From Server Instructions to Skills
6+
7+
Earlier versions of this server injected a single large system prompt (server instructions) covering all tools into every MCP session. This approach had drawbacks:
8+
9+
- **Context waste**: Every session loaded guidance for all tools, regardless of what the user needed.
10+
- **No progressive disclosure**: Clients couldn't selectively load tool subsets based on the task at hand.
11+
- **Weak tool alignment**: Bold markdown references (e.g., `**search_repositories**`) didn't reliably trigger models to call the actual MCP tools.
12+
13+
This version **replaces server instructions with skill resources** — structured SKILL.md documents served via `skill://` URIs. Each skill covers a specific workflow, lists exactly which tools it needs, and provides targeted guidance. Clients that support skills can progressively discover and load only what's relevant.
14+
15+
For the broader design rationale, see:
16+
- [Progressive Tool Discovery](https://github.com/SamMorrowDrums/mcpi/blob/main/docs/progressive-tool-discovery.md)
17+
- [Skills Mechanism](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/docs/skills.md)
18+
- [Server Developer Guide](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/docs/server-developer-guide.md)
19+
- [Skills-as-Groups Proposal](https://github.com/modelcontextprotocol/experimental-ext-grouping/pull/13)
20+
21+
## How It Works
22+
23+
### Skill Structure
24+
25+
Each skill is registered as an MCP resource at `skill://github/{name}/SKILL.md` with the MIME type `text/markdown`. The content is a Markdown document with YAML frontmatter:
26+
27+
```yaml
28+
---
29+
name: review-pr
30+
description: Conduct a thorough code review of a pull request. Use when reviewing someone else's PR, checking code changes, leaving review comments, approving or requesting changes.
31+
allowed-tools:
32+
- pull_request_read
33+
- get_file_contents
34+
- search_code
35+
- create_pull_request_review
36+
- add_pull_request_review_comment
37+
- add_comment_to_pending_review
38+
- submit_pending_pull_request_review
39+
- delete_pending_pull_request_review
40+
- add_reply_to_pull_request_comment
41+
- resolve_review_thread
42+
- unresolve_review_thread
43+
---
44+
45+
# Review Pull Request
46+
47+
You are reviewing someone else's PR. Be thorough, constructive, and decisive.
48+
49+
## Available Tools
50+
- `pull_request_read` — get diff, files, status, review comments, check runs
51+
- `get_file_contents` / `search_code` — read context beyond the diff
52+
...
53+
```
54+
55+
### Frontmatter Fields
56+
57+
| Field | Purpose |
58+
|-------|---------|
59+
| `name` | Skill identifier, used in the URI path |
60+
| `description` | What the skill does AND when to use it — this is the primary mechanism clients use to decide whether to load a skill |
61+
| `allowed-tools` | MCP tool names this skill gates. When a client loads the skill, these tools become active |
62+
63+
### Client Flow
64+
65+
1. Client calls `resources/list` → sees all `skill://github/*/SKILL.md` resources with descriptions.
66+
2. Client reads the description to decide if a skill is relevant to the current task.
67+
3. Client calls `resources/read` on the skill URI → gets the full SKILL.md content.
68+
4. Client activates the tools listed in `allowed-tools` and uses the body as workflow guidance.
69+
70+
### Implementation
71+
72+
Skills are defined in `pkg/github/skill_resources.go` as `skillDefinition` structs:
73+
74+
```go
75+
type skillDefinition struct {
76+
name string
77+
description string
78+
allowedTools []string
79+
body string
80+
}
81+
```
82+
83+
The `buildSkillContent()` function assembles the YAML frontmatter and body into a SKILL.md document. `RegisterSkillResources()` registers all skills as MCP resources at server startup.
84+
85+
## Available Skills
86+
87+
The server defines 27 workflow-oriented skills. Skills map to **user intents** (what the user wants to accomplish), not API domains. Tools overlap across skills based on workflow needs.
88+
89+
### PR Workflows
90+
91+
| Skill | Description | Key Tools |
92+
|-------|-------------|-----------|
93+
| `create-pr` | Create a well-structured pull request | `create_pull_request`, `get_file_contents`, `push_files`, `request_pull_request_reviewers` |
94+
| `review-pr` | Review someone else's PR | `pull_request_read`, `create_pull_request_review`, `add_pull_request_review_comment`, `submit_pending_pull_request_review` |
95+
| `self-review-pr` | Self-check your own PR before requesting review | `pull_request_read`, `actions_get`, `get_job_logs`, `update_pull_request` |
96+
| `address-pr-feedback` | Handle review comments and push fixes | `pull_request_read`, `add_reply_to_pull_request_comment`, `resolve_review_thread`, `push_files` |
97+
| `merge-pr` | Get a PR to merge-ready state and merge it | `pull_request_read`, `merge_pull_request`, `update_pull_request_branch`, `update_pull_request_draft_state` |
98+
99+
### Issue Workflows
100+
101+
| Skill | Description | Key Tools |
102+
|-------|-------------|-----------|
103+
| `triage-issues` | Categorize, deduplicate, and prioritize issues | `list_issues`, `search_issues`, `list_issue_types`, `update_issue_labels`, `update_issue_state` |
104+
| `create-issue` | Create well-structured, searchable issues | `create_issue`, `search_issues`, `list_issue_types`, `get_file_contents` |
105+
| `manage-sub-issues` | Break down large issues into sub-tasks | `issue_read`, `create_issue`, `add_sub_issue`, `reprioritize_sub_issue` |
106+
107+
### CI/CD
108+
109+
| Skill | Description | Key Tools |
110+
|-------|-------------|-----------|
111+
| `debug-ci` | Investigate failing GitHub Actions workflows | `actions_get`, `get_job_logs`, `actions_list`, `get_file_contents` |
112+
| `trigger-workflow` | Run, rerun, or cancel workflow runs | `actions_run_trigger`, `actions_get`, `actions_list` |
113+
114+
### Security
115+
116+
| Skill | Description | Key Tools |
117+
|-------|-------------|-----------|
118+
| `security-audit` | Review code scanning, secret, and dependency alerts | `list_code_scanning_alerts`, `list_secret_scanning_alerts`, `list_dependabot_alerts`, `search_code` |
119+
| `fix-dependabot` | Handle vulnerable dependency alerts | `list_dependabot_alerts`, `get_dependabot_alert`, `search_pull_requests` |
120+
| `research-vulnerability` | Query the GitHub Advisory Database | `list_global_security_advisories`, `get_global_security_advisory` |
121+
122+
### Code Exploration
123+
124+
| Skill | Description | Key Tools |
125+
|-------|-------------|-----------|
126+
| `explore-repo` | Understand an unfamiliar codebase | `get_repository_tree`, `get_file_contents`, `search_code`, `list_commits` |
127+
| `search-code` | Find code patterns across GitHub | `search_code`, `search_repositories`, `get_file_contents` |
128+
| `trace-history` | Understand why code changed via commits and PRs | `list_commits`, `get_commit`, `search_pull_requests`, `pull_request_read` |
129+
130+
### Project Management
131+
132+
| Skill | Description | Key Tools |
133+
|-------|-------------|-----------|
134+
| `manage-project` | Track and update GitHub Projects (v2) items | `projects_list`, `projects_get`, `projects_write` |
135+
| `handle-notifications` | Process GitHub notifications efficiently | `list_notifications`, `get_notification_details`, `dismiss_notification` |
136+
| `prepare-release` | Compile release notes from commits and PRs | `list_releases`, `get_latest_release`, `list_commits`, `search_pull_requests` |
137+
138+
### Repository Management
139+
140+
| Skill | Description | Key Tools |
141+
|-------|-------------|-----------|
142+
| `manage-repo` | Create repos, manage branches, push files | `create_repository`, `fork_repository`, `create_branch`, `push_files` |
143+
| `manage-labels` | Set up and maintain a label scheme | `list_labels`, `label_write`, `search_issues` |
144+
145+
### Collaboration
146+
147+
| Skill | Description | Key Tools |
148+
|-------|-------------|-----------|
149+
| `contribute-oss` | Fork, branch, and submit PRs to external repos | `fork_repository`, `create_branch`, `push_files`, `create_pull_request` |
150+
| `browse-discussions` | Read and explore GitHub Discussions | `list_discussions`, `get_discussion`, `get_discussion_comments` |
151+
| `delegate-to-copilot` | Assign Copilot to issues and request reviews | `assign_copilot_to_issue`, `request_copilot_review` |
152+
153+
### Discovery
154+
155+
| Skill | Description | Key Tools |
156+
|-------|-------------|-----------|
157+
| `get-context` | Understand the current user and permissions | `get_me`, `get_teams`, `get_team_members` |
158+
| `discover-github` | Search for users, orgs, and repositories | `search_users`, `search_orgs`, `search_repositories`, `star_repository` |
159+
| `share-snippet` | Create and manage code snippets via Gists | `create_gist`, `update_gist`, `list_gists`, `get_gist` |
160+
161+
## Design Decisions
162+
163+
### Workflow-Oriented, Not Toolset-Oriented
164+
165+
Skills map to what users want to accomplish, not GitHub API domains. For example, there's no "pull requests" skill — instead there are `review-pr`, `self-review-pr`, `create-pr`, `address-pr-feedback`, and `merge-pr`, each with different tools and different guidance. Tools overlap across skills based on workflow needs.
166+
167+
### Identity-Aware
168+
169+
Different skills exist for different perspectives on the same resource. `review-pr` assumes you're reviewing someone else's work (be thorough, submit with a verdict), while `self-review-pr` assumes you're checking your own work (catch debug code, verify CI, polish description).
170+
171+
### Trigger-Friendly Descriptions
172+
173+
Following the [agent skills specification](https://agentskills.io/specification), each description includes "Use when..." clauses listing specific user intents. The description is the primary mechanism clients use to decide whether to load a skill.
174+
175+
### All Toolsets Enabled by Default
176+
177+
All toolsets have `Default: true`, so every tool is registered out of the box. Skills handle progressive disclosure on the client side — the server exposes the full tool surface and lets skills control what's visible for each workflow.
178+
179+
## Test Coverage
180+
181+
Tests in `pkg/github/skill_resources_test.go` ensure:
182+
183+
- **`TestAllSkillsCoverAllToolsets`**: Every registered MCP tool appears in at least one skill's `allowedTools`. Adding a new tool without including it in a skill fails CI.
184+
- **`TestBuildSkillContent`**: Verifies YAML frontmatter assembly.
185+
- **`TestSkillResourceURIs`**: Checks for duplicate URIs/names and ensures every skill has non-empty description, tools, and body.
186+
- **`TestRegisterSkillResources`**: Verifies registration completes and the correct number of skills exist.
187+
188+
## Related Projects
189+
190+
- [mcpi-ext](https://github.com/SamMorrowDrums/mcpi-ext) — MCP client extensions that implement progressive tool discovery via skills
191+
- [Server Developer Guide](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/docs/server-developer-guide.md) — Guide for MCP server developers implementing skill:// resources
192+
- [Progressive Tool Discovery](https://github.com/SamMorrowDrums/mcpi/blob/main/docs/progressive-tool-discovery.md) — Design rationale for progressive disclosure
193+
- [Skills-as-Groups Proposal](https://github.com/modelcontextprotocol/experimental-ext-grouping/pull/13) — Proposed MCP spec extension for skills

0 commit comments

Comments
 (0)