Skip to content

Commit 2e1042e

Browse files
authored
Merge branch 'main' into feature/github-packages-support
2 parents 8814cff + 0663b83 commit 2e1042e

67 files changed

Lines changed: 8333 additions & 25 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.dockerignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,5 +7,6 @@ third-party
77
**/*.yml
88
**/*.yaml
99
**/*.md
10+
!pkg/skills/catalog/skills/**/*.md
1011
**/*_test.go
1112
LICENSE

‎.github/copilot-instructions.md‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -189,12 +189,19 @@ All workflows run on push/PR unless noted. Located in `.github/workflows/`:
189189

190190
1. Add tool implementation in `pkg/github/` (e.g., `foo_tools.go`)
191191
2. Register tool in appropriate toolset in `pkg/github/` or `pkg/toolsets/`
192-
3. Write unit tests following the tool test pattern
193-
4. Run `UPDATE_TOOLSNAPS=true go test ./...` to create snapshot
194-
5. Run `script/generate-docs` to update README
195-
6. Run `script/lint` and `script/test` before committing
196-
7. If e2e tests are relevant, update `e2e/e2e_test.go` using existing test style
197-
8. Commit code + snapshots + README changes together
192+
3. Update the relevant bundled skill, or add a reasoned exemption in `pkg/skills/catalog/availability_test.go`. Every tool must be covered or explicitly exempted.
193+
4. Write unit tests following the tool test pattern
194+
5. Run `UPDATE_TOOLSNAPS=true go test ./...` to create snapshot
195+
6. Run `script/generate-docs` to update README
196+
7. Run `script/lint` and `script/test` before committing
197+
8. If e2e tests are relevant, update `e2e/e2e_test.go` using existing test style
198+
9. Commit code + snapshots + README changes together
199+
200+
When adding or changing a toolset `InstructionsFunc`, update the associated
201+
skills as well: skills mode suppresses those instructions. The
202+
`TestToolsetInstructionsAreCoveredBySkills` failure names the skills to revisit;
203+
after updating them, refresh its digest with
204+
`UPDATE_SKILLS_INSTRUCTIONS=true go test ./pkg/github -run TestToolsetInstructionsAreCoveredBySkills -count=1`.
198205

199206
### Fixing a Bug
200207

‎.github/pull_request_template.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,3 +49,7 @@ Note: if you're renaming tools, you *must* add the tool aliases. For more inform
4949

5050
- [ ] Not needed
5151
- [ ] Updated (README / docs / examples)
52+
53+
## Skills
54+
<!-- If this PR adds or changes MCP tools or toolset instructions, update the relevant bundled skills or explain why no skill applies. -->
55+
- [ ] Updated relevant skills or confirmed no bundled skill applies

‎CONTRIBUTING.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@ For UI dependency upgrades, compare all four views (`get-me`, `issue-write`, `pr
6161
- If renaming a tool, add a deprecation alias (see [Tool Renaming Guide](docs/tool-renaming.md))
6262
- For toolset and icon configuration, see [Toolsets and Icons Guide](docs/toolsets-and-icons.md)
6363
- For typed tool registration and compatibility schemas, see [Typed Tool Schemas](docs/typed-tool-schemas.md)
64+
- When adding or changing tools or toolset instructions, update the relevant bundled skills or record why no skill applies. Run `go test ./pkg/skills/catalog -run TestCatalogToolRequirementsAreRegistered -count=1`; if the instruction snapshot fails, update the named skills and refresh it with `UPDATE_SKILLS_INSTRUCTIONS=true go test ./pkg/github -run TestToolsetInstructionsAreCoveredBySkills -count=1`. Run `script/generate-docs` to refresh the README catalog.
6465
6. Push to your fork and [submit a pull request][pr] targeting the `main` branch
6566
7. Pat yourself on the back and wait for your pull request to be reviewed and merged.
6667

‎README.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -627,6 +627,34 @@ The following sets of tools are available:
627627
| `copilot_spaces` | Copilot Spaces related tools |
628628
| `github_support_docs_search` | Search docs to answer GitHub product and support questions |
629629

630+
## MCP Skills
631+
632+
The local server bundles workflow skills that replace server instructions when
633+
enabled with `--features=skills` (or Insiders Mode). Skills are off by default
634+
and are filtered to the tools available in the connection, so a restricted
635+
toolset may expose only part of the catalog.
636+
637+
<!-- START AUTOMATED SKILLS -->
638+
- [`account-and-team-context`](pkg/skills/catalog/skills/account-and-team-context/SKILL.md) — USE FOR: establishing who the authenticated account is, which organisations and teams it belongs to, who sits on a team, and who has write access to a repository. NOT FOR: finding an unfamiliar repository, or choosing what work to do next.
639+
- [`codebase-exploration`](pkg/skills/catalog/skills/codebase-exploration/SKILL.md) — USE FOR: understanding an unfamiliar repository and how it got that way — its layout, where a behaviour is implemented, and when and why a particular function or line last changed. NOT FOR: editing files, or assessing whether a project is healthy overall.
640+
- [`copilot-task-delegation`](pkg/skills/catalog/skills/copilot-task-delegation/SKILL.md) — USE FOR: handing a piece of work to the Copilot coding agent — judging whether an issue is scoped tightly enough to delegate, launching it, and asking for an automated first-pass review of a proposed change. NOT FOR: doing the work directly, or reviewing what comes back.
641+
- [`discussion-participation`](pkg/skills/catalog/skills/discussion-participation/SKILL.md) — USE FOR: taking part in GitHub Discussions — finding the unanswered questions in a category, reading a thread in full, replying to it, and marking the reply that resolved it. NOT FOR: commenting on an issue or a proposed change, or working through a backlog.
642+
- [`issue-authoring`](pkg/skills/catalog/skills/issue-authoring/SKILL.md) — USE FOR: filing one clear bug report or feature request — checking it is not already reported, choosing its type and fields, breaking it into sub-issues, and giving it a title and body someone can act on. NOT FOR: working through an existing backlog, or discussing an open question with a community.
643+
- [`issue-backlog-triage`](pkg/skills/catalog/skills/issue-backlog-triage/SKILL.md) — USE FOR: triaging a backlog of open GitHub issues — judging which are actionable, labelling and typing them, linking duplicates and parents, and closing what is dead. NOT FOR: writing one new issue, scheduling committed work, or reviewing pull requests.
644+
- [`label-scheme-management`](pkg/skills/catalog/skills/label-scheme-management/SKILL.md) — USE FOR: curating the label vocabulary a repository uses — adding ones it lacks, auditing which are actually applied, renaming and recolouring them, merging overlapping ones, and tidying away the unused. NOT FOR: applying an existing label to an issue, or deciding which issues matter.
645+
- [`notification-triage`](pkg/skills/catalog/skills/notification-triage/SKILL.md) — USE FOR: working through a GitHub notification inbox — deciding what needs a reply, what to unsubscribe from, and what to mark read or done. NOT FOR: triaging a repository issue backlog, or answering review threads on one specific pull request.
646+
- [`project-planning`](pkg/skills/catalog/skills/project-planning/SKILL.md) — USE FOR: planning and updating work on a GitHub Projects board — reading fields and views, adding issues or pull requests as items, setting status and iteration, and posting a status update. NOT FOR: triaging a repository issue backlog, or preparing a release.
647+
- [`pull-request-authoring`](pkg/skills/catalog/skills/pull-request-authoring/SKILL.md) — USE FOR: taking a branch of work through to landed — opening the pull request, describing it, requesting reviewers, keeping it current with its base, and merging it once checks and approvals are in. NOT FOR: reviewing someone else's proposal, or acting on review comments left on yours.
648+
- [`pull-request-code-review`](pkg/skills/catalog/skills/pull-request-code-review/SKILL.md) — USE FOR: examining someone else's pull request and delivering a verdict — reading the diff in context, leaving line-anchored comments as a batch, and approving or requesting changes. NOT FOR: replying to review comments left on your own change, or opening and merging one.
649+
- [`pull-request-review-feedback`](pkg/skills/catalog/skills/pull-request-review-feedback/SKILL.md) — USE FOR: working through review feedback left on a pull request — reading each unresolved thread, deciding what to change, replying to the reviewer, and resolving threads. NOT FOR: producing a review of a pull request, merging one, or clearing a notification inbox.
650+
- [`release-preparation`](pkg/skills/catalog/skills/release-preparation/SKILL.md) — USE FOR: cutting a release of a repository — picking the version, assembling the changelog since the last tag, confirming the branch is releasable, and drafting release notes. NOT FOR: assessing overall repository health, triaging security alerts, or working an issue backlog.
651+
- [`repository-content-changes`](pkg/skills/catalog/skills/repository-content-changes/SKILL.md) — USE FOR: changing what a repository holds or whether it exists at all — opening a working branch, committing files remotely, deleting what should go, and creating, forking or removing the repository itself. NOT FOR: proposing those changes for review, or reading code you do not intend to touch.
652+
- [`repository-discovery`](pkg/skills/catalog/skills/repository-discovery/SKILL.md) — USE FOR: finding a library, tool or organisation you cannot yet name, judging whether a candidate project is worth depending on, and keeping a starred shortlist useful. NOT FOR: searching inside a repository you have already chosen, or setting one up.
653+
- [`repository-health-review`](pkg/skills/catalog/skills/repository-health-review/SKILL.md) — USE FOR: judging how well a repository is maintained overall — release cadence, branch and proposal age, issue inflow, build reliability, how many people can maintain it, and outstanding alert counts. NOT FOR: acting on any individual issue, alert or proposed change, or cutting a specific release.
654+
- [`security-alert-triage`](pkg/skills/catalog/skills/security-alert-triage/SKILL.md) — USE FOR: investigating GitHub security alerts — code scanning, Dependabot, secret scanning and advisories — and deciding what to fix now, schedule, dismiss, or escalate. NOT FOR: summarising overall repository health, or reviewing feedback on a pull request.
655+
- [`workflow-failure-triage`](pkg/skills/catalog/skills/workflow-failure-triage/SKILL.md) — USE FOR: diagnosing a failing GitHub Actions workflow run — a build gone red, which jobs failed, what their logs say, where the failing step is, and whether a rerun is justified. NOT FOR: judging long-term reliability trends across a repository, or deciding whether a change is ready to ship.
656+
<!-- END AUTOMATED SKILLS -->
657+
630658
## Tools
631659

632660
Repository tools expose output schemas and typed `structuredContent` when the negotiated MCP protocol version is a supported version `2026-07-28` or newer. Older clients, clients with an unknown protocol version, and clients omitting the version receive the existing content without an output schema or structured output. Unknown versions are not treated as supported merely because they sort after `2026-07-28`.
@@ -1596,11 +1624,13 @@ For negotiated supported protocol versions `2026-07-28` or newer, the consolidat
15961624
- **get_secret_scanning_alert** - Get secret scanning alert
15971625
- **OAuth Challenge Scopes**: `security_events`
15981626
- `alertNumber`: The number of the alert. (number, required)
1627+
- `hide_secret`: Whether to exclude the secret value from the response. Defaults to false. (boolean, optional)
15991628
- `owner`: The owner of the repository. (string, required)
16001629
- `repo`: The name of the repository. (string, required)
16011630

16021631
- **list_secret_scanning_alerts** - List secret scanning alerts
16031632
- **OAuth Challenge Scopes**: `security_events`
1633+
- `hide_secret`: Whether to exclude secret values from the response. Defaults to false. (boolean, optional)
16041634
- `owner`: The owner of the repository. (string, required)
16051635
- `page`: Page number for pagination (min 1) (number, optional)
16061636
- `perPage`: Results per page for pagination (min 1, max 100) (number, optional)

‎cmd/github-mcp-server/generate_docs.go‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ import (
1111

1212
"github.com/github/github-mcp-server/v2/pkg/github"
1313
"github.com/github/github-mcp-server/v2/pkg/inventory"
14+
"github.com/github/github-mcp-server/v2/pkg/skills/catalog"
1415
"github.com/github/github-mcp-server/v2/pkg/translations"
1516
"github.com/google/jsonschema-go/jsonschema"
1617
"github.com/spf13/cobra"
@@ -19,7 +20,7 @@ import (
1920
var generateDocsCmd = &cobra.Command{
2021
Use: "generate-docs",
2122
Short: "Generate documentation for tools and toolsets",
22-
Long: `Generate the automated sections of README.md and docs/remote-server.md with current tool and toolset information.`,
23+
Long: `Generate the automated sections of README.md and docs/remote-server.md with current tool, toolset, and bundled skill information.`,
2324
RunE: func(_ *cobra.Command, _ []string) error {
2425
return generateAllDocs()
2526
},
@@ -72,6 +73,11 @@ func generateReadmeDocs(readmePath string) error {
7273
// Generate toolsets documentation
7374
toolsetsDoc := generateToolsetsDoc(r)
7475

76+
skillsDoc, err := generateSkillsDoc()
77+
if err != nil {
78+
return err
79+
}
80+
7581
// Generate tools documentation
7682
toolsDoc := generateToolsDoc(r)
7783

@@ -88,6 +94,11 @@ func generateReadmeDocs(readmePath string) error {
8894
return err
8995
}
9096

97+
updatedContent, err = replaceSection(updatedContent, "START AUTOMATED SKILLS", "END AUTOMATED SKILLS", skillsDoc)
98+
if err != nil {
99+
return err
100+
}
101+
91102
// Replace tools section
92103
updatedContent, err = replaceSection(updatedContent, "START AUTOMATED TOOLS", "END AUTOMATED TOOLS", toolsDoc)
93104
if err != nil {
@@ -103,6 +114,27 @@ func generateReadmeDocs(readmePath string) error {
103114
return nil
104115
}
105116

117+
func generateSkillsDoc() (string, error) {
118+
source, err := catalog.New()
119+
if err != nil {
120+
return "", fmt.Errorf("load bundled skills for README: %w", err)
121+
}
122+
entries, err := source.List(context.Background())
123+
if err != nil {
124+
return "", fmt.Errorf("list bundled skills for README: %w", err)
125+
}
126+
sort.Slice(entries, func(i, j int) bool {
127+
return entries[i].Frontmatter.Name() < entries[j].Frontmatter.Name()
128+
})
129+
130+
var buf strings.Builder
131+
for _, entry := range entries {
132+
name := entry.Frontmatter.Name()
133+
fmt.Fprintf(&buf, "- [`%s`](pkg/skills/catalog/skills/%s/SKILL.md) — %s\n", name, name, entry.Frontmatter.Description())
134+
}
135+
return strings.TrimSuffix(buf.String(), "\n"), nil
136+
}
137+
106138
func generateRemoteServerDocs(docsPath string) error {
107139
content, err := os.ReadFile(docsPath) //#nosec G304
108140
if err != nil {

‎docs/feature-flags.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,68 @@ Only flags listed in
3535
[`AllowedFeatureFlags`](../pkg/github/feature_flags.go) can be enabled by
3636
end users. Insiders-only flags are not user-toggleable.
3737

38+
## MCP skills
39+
40+
The `skills` flag replaces server instructions with bundled workflow skills
41+
served through the `io.modelcontextprotocol/skills` extension. It is off by
42+
default and enabled automatically in Insiders Mode:
43+
44+
```bash
45+
github-mcp-server stdio --features=skills
46+
# Equivalent opt-in: GITHUB_FEATURES=skills
47+
github-mcp-server stdio --insiders
48+
```
49+
50+
When enabled, both initialization and `server/discover` omit instructions entirely.
51+
There is no discovery blurb or fallback instructions for clients without skills
52+
support. Without the flag, the existing server instructions are unchanged and
53+
the skills extension is not advertised.
54+
55+
Clients discover skills with paginated `skills/list`, resolve one with
56+
`skills/get`, and read `skill://github.com/<name>/SKILL.md` and supporting files
57+
through `resources/read`. Directory reads are also supported. Entries contain
58+
the file manifests, byte lengths and SHA-256 digests defined by the
59+
[beta extension specification](https://github.com/modelcontextprotocol/ext-skills/blob/main/specification/beta/skills.mdx).
60+
61+
The catalog is filtered against the current connection's tools: toolsets,
62+
explicit tools, exclusions, read-only mode, feature variants and token-scope
63+
filters apply. All required core tools must be available; missing optional tools
64+
are allowed. A withheld skill is unavailable through listing, direct get,
65+
directory reads and file reads alike. Tool associations remain server-side:
66+
there is no `allowed-tools` frontmatter or skill metadata on tools, and loading
67+
a skill grants no tool permissions.
68+
69+
For a Copilot CLI build with experimental MCP skills support, enable
70+
`MCP_SKILLS=true` and add a stdio server:
71+
72+
```bash
73+
MCP_SKILLS=true copilot --additional-mcp-config \
74+
'{"mcpServers":{"github":{"type":"local","command":"/absolute/path/to/github-mcp-server","args":["stdio","--features=skills","--toolsets=context"],"tools":["*"]}}}'
75+
```
76+
77+
In the CLI, use `/skills list` and invoke the discovered server-qualified skill
78+
command. For the `github` server above, the account skill command is
79+
`/mcp:github:skill:github.com:account-and-team-context`. Remove the context-only
80+
toolset restriction to expose workflows supported by the default toolsets.
81+
82+
Supply credentials through the normal server environment, not configuration
83+
arguments or transcripts. Skill activation requires the client's explicit skill
84+
consent even with `/allow-all` or `--yolo`. Discovery, command naming and consent
85+
behavior depend on the CLI build; this flag alone does not establish client
86+
conformance.
87+
88+
VS Code Insiders can opt into its skills client with
89+
`chat.agentHost.mcpSkills.enabled: true`, using the same server configuration.
90+
That setting is a client prerequisite, not a claim that every VS Code build
91+
supports every extension feature.
92+
93+
Library integrators can extend `catalog.Source()` using `Registry.WithSkills`
94+
and supply the resulting registry as `MCPServerConfig.SkillsSource`. Set each
95+
additional skill's `RequiredTools` (groups of alternative tool names) and
96+
`OptionalTools` before building the registry. The shared constructor filters the
97+
catalog per request and removes instructions when its feature checker enables
98+
`github.FeatureFlagSkillsExtension`.
99+
38100
## Declaring tool availability
39101

40102
### Issue artifacts

‎docs/insiders-features.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,19 @@ Because this changes list tool response shape, clients that require JSON list re
100100

101101
---
102102

103+
## Skills instead of server instructions
104+
105+
Insiders Mode enables the `skills` feature flag. The server advertises the MCP
106+
skills extension and serves a tool-filtered catalog of workflow guidance instead
107+
of sending server instructions. Clients that do not consume skills receive no
108+
replacement instructions. Use the normal non-insiders configuration without the
109+
`skills` flag to retain existing server instructions.
110+
111+
See [MCP skills](./feature-flags.md#mcp-skills) for activation, protocol details
112+
and client configuration.
113+
114+
---
115+
103116
## How feature flags are resolved
104117

105118
> [!NOTE]

‎go.mod‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ require (
2020
github.com/spf13/viper v1.21.0
2121
github.com/stretchr/testify v1.12.1
2222
github.com/yosida95/uritemplate/v3 v3.0.2
23+
go.yaml.in/yaml/v3 v3.0.5
2324
golang.org/x/net v0.61.0
2425
golang.org/x/oauth2 v0.37.0
2526
)
@@ -38,7 +39,6 @@ require (
3839
github.com/spf13/cast v1.10.0 // indirect
3940
github.com/stretchr/objx v0.5.3 // indirect
4041
github.com/subosito/gotenv v1.6.0 // indirect
41-
go.yaml.in/yaml/v3 v3.0.5 // indirect
4242
golang.org/x/sync v0.24.0 // indirect
4343
golang.org/x/sys v0.49.0 // indirect
4444
golang.org/x/text v0.43.0 // indirect

‎internal/ghmcp/server.go‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -214,8 +214,10 @@ func NewStdioMCPServer(ctx context.Context, cfg github.MCPServerConfig) (*mcp.Se
214214
WithToolsets(github.ResolvedEnabledToolsets(cfg.EnabledToolsets, cfg.EnabledTools)).
215215
WithTools(github.CleanTools(cfg.EnabledTools)).
216216
WithExcludeTools(cfg.ExcludeTools).
217-
WithServerInstructions().
218217
WithFeatureChecker(featureChecker)
218+
if !deps.IsFeatureEnabled(ctx, github.FeatureFlagSkillsExtension) {
219+
inventoryBuilder.WithServerInstructions()
220+
}
219221

220222
// Apply token scope filtering if scopes are known (for PAT filtering)
221223
if cfg.TokenScopes != nil {

0 commit comments

Comments
 (0)