Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
Expand Up @@ -7,5 +7,6 @@ third-party
**/*.yml
**/*.yaml
**/*.md
!pkg/skills/catalog/skills/**/*.md
**/*_test.go
LICENSE
19 changes: 13 additions & 6 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,12 +189,19 @@ All workflows run on push/PR unless noted. Located in `.github/workflows/`:

1. Add tool implementation in `pkg/github/` (e.g., `foo_tools.go`)
2. Register tool in appropriate toolset in `pkg/github/` or `pkg/toolsets/`
3. Write unit tests following the tool test pattern
4. Run `UPDATE_TOOLSNAPS=true go test ./...` to create snapshot
5. Run `script/generate-docs` to update README
6. Run `script/lint` and `script/test` before committing
7. If e2e tests are relevant, update `e2e/e2e_test.go` using existing test style
8. Commit code + snapshots + README changes together
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.
4. Write unit tests following the tool test pattern
5. Run `UPDATE_TOOLSNAPS=true go test ./...` to create snapshot
6. Run `script/generate-docs` to update README
7. Run `script/lint` and `script/test` before committing
8. If e2e tests are relevant, update `e2e/e2e_test.go` using existing test style
9. Commit code + snapshots + README changes together

When adding or changing a toolset `InstructionsFunc`, update the associated
skills as well: skills mode suppresses those instructions. The
`TestToolsetInstructionsAreCoveredBySkills` failure names the skills to revisit;
after updating them, refresh its digest with
`UPDATE_SKILLS_INSTRUCTIONS=true go test ./pkg/github -run TestToolsetInstructionsAreCoveredBySkills -count=1`.

### Fixing a Bug

Expand Down
4 changes: 4 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,3 +49,7 @@ Note: if you're renaming tools, you *must* add the tool aliases. For more inform

- [ ] Not needed
- [ ] Updated (README / docs / examples)

## Skills
<!-- If this PR adds or changes MCP tools or toolset instructions, update the relevant bundled skills or explain why no skill applies. -->
- [ ] Updated relevant skills or confirmed no bundled skill applies
1 change: 1 addition & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ For UI dependency upgrades, compare all four views (`get-me`, `issue-write`, `pr
- If renaming a tool, add a deprecation alias (see [Tool Renaming Guide](docs/tool-renaming.md))
- For toolset and icon configuration, see [Toolsets and Icons Guide](docs/toolsets-and-icons.md)
- For typed tool registration and compatibility schemas, see [Typed Tool Schemas](docs/typed-tool-schemas.md)
- 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.
6. Push to your fork and [submit a pull request][pr] targeting the `main` branch
7. Pat yourself on the back and wait for your pull request to be reviewed and merged.

Expand Down
28 changes: 28 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -626,6 +626,34 @@ The following sets of tools are available:
| `copilot_spaces` | Copilot Spaces related tools |
| `github_support_docs_search` | Search docs to answer GitHub product and support questions |

## MCP Skills

The local server bundles workflow skills that replace server instructions when
enabled with `--features=skills` (or Insiders Mode). Skills are off by default
and are filtered to the tools available in the connection, so a restricted
toolset may expose only part of the catalog.

<!-- START AUTOMATED SKILLS -->
- [`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.
- [`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.
- [`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.
- [`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.
- [`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.
- [`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.
- [`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.
- [`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.
- [`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.
- [`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.
- [`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.
- [`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.
- [`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.
- [`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.
- [`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.
- [`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.
- [`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.
- [`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.
<!-- END AUTOMATED SKILLS -->

## Tools

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`.
Expand Down
34 changes: 33 additions & 1 deletion cmd/github-mcp-server/generate_docs.go
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import (

"github.com/github/github-mcp-server/v2/pkg/github"
"github.com/github/github-mcp-server/v2/pkg/inventory"
"github.com/github/github-mcp-server/v2/pkg/skills/catalog"
"github.com/github/github-mcp-server/v2/pkg/translations"
"github.com/google/jsonschema-go/jsonschema"
"github.com/spf13/cobra"
Expand All @@ -19,7 +20,7 @@ import (
var generateDocsCmd = &cobra.Command{
Use: "generate-docs",
Short: "Generate documentation for tools and toolsets",
Long: `Generate the automated sections of README.md and docs/remote-server.md with current tool and toolset information.`,
Long: `Generate the automated sections of README.md and docs/remote-server.md with current tool, toolset, and bundled skill information.`,
RunE: func(_ *cobra.Command, _ []string) error {
return generateAllDocs()
},
Expand Down Expand Up @@ -72,6 +73,11 @@ func generateReadmeDocs(readmePath string) error {
// Generate toolsets documentation
toolsetsDoc := generateToolsetsDoc(r)

skillsDoc, err := generateSkillsDoc()
if err != nil {
return err
}

// Generate tools documentation
toolsDoc := generateToolsDoc(r)

Expand All @@ -88,6 +94,11 @@ func generateReadmeDocs(readmePath string) error {
return err
}

updatedContent, err = replaceSection(updatedContent, "START AUTOMATED SKILLS", "END AUTOMATED SKILLS", skillsDoc)
if err != nil {
return err
}

// Replace tools section
updatedContent, err = replaceSection(updatedContent, "START AUTOMATED TOOLS", "END AUTOMATED TOOLS", toolsDoc)
if err != nil {
Expand All @@ -103,6 +114,27 @@ func generateReadmeDocs(readmePath string) error {
return nil
}

func generateSkillsDoc() (string, error) {
source, err := catalog.New()
if err != nil {
return "", fmt.Errorf("load bundled skills for README: %w", err)
}
entries, err := source.List(context.Background())
if err != nil {
return "", fmt.Errorf("list bundled skills for README: %w", err)
}
sort.Slice(entries, func(i, j int) bool {
return entries[i].Frontmatter.Name() < entries[j].Frontmatter.Name()
})

var buf strings.Builder
for _, entry := range entries {
name := entry.Frontmatter.Name()
fmt.Fprintf(&buf, "- [`%s`](pkg/skills/catalog/skills/%s/SKILL.md) — %s\n", name, name, entry.Frontmatter.Description())
}
return strings.TrimSuffix(buf.String(), "\n"), nil
}

func generateRemoteServerDocs(docsPath string) error {
content, err := os.ReadFile(docsPath) //#nosec G304
if err != nil {
Expand Down
62 changes: 62 additions & 0 deletions docs/feature-flags.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,68 @@ Only flags listed in
[`AllowedFeatureFlags`](../pkg/github/feature_flags.go) can be enabled by
end users. Insiders-only flags are not user-toggleable.

## MCP skills

The `skills` flag replaces server instructions with bundled workflow skills
served through the `io.modelcontextprotocol/skills` extension. It is off by
default and enabled automatically in Insiders Mode:

```bash
github-mcp-server stdio --features=skills
# Equivalent opt-in: GITHUB_FEATURES=skills
github-mcp-server stdio --insiders
```

When enabled, both initialization and `server/discover` omit instructions entirely.
There is no discovery blurb or fallback instructions for clients without skills
support. Without the flag, the existing server instructions are unchanged and
the skills extension is not advertised.

Clients discover skills with paginated `skills/list`, resolve one with
`skills/get`, and read `skill://github.com/<name>/SKILL.md` and supporting files
through `resources/read`. Directory reads are also supported. Entries contain
the file manifests, byte lengths and SHA-256 digests defined by the
[beta extension specification](https://github.com/modelcontextprotocol/ext-skills/blob/main/specification/beta/skills.mdx).

The catalog is filtered against the current connection's tools: toolsets,
explicit tools, exclusions, read-only mode, feature variants and token-scope
filters apply. All required core tools must be available; missing optional tools
are allowed. A withheld skill is unavailable through listing, direct get,
directory reads and file reads alike. Tool associations remain server-side:
there is no `allowed-tools` frontmatter or skill metadata on tools, and loading
a skill grants no tool permissions.

For a Copilot CLI build with experimental MCP skills support, enable
`MCP_SKILLS=true` and add a stdio server:

```bash
MCP_SKILLS=true copilot --additional-mcp-config \
'{"mcpServers":{"github":{"type":"local","command":"/absolute/path/to/github-mcp-server","args":["stdio","--features=skills","--toolsets=context"],"tools":["*"]}}}'
```

In the CLI, use `/skills list` and invoke the discovered server-qualified skill
command. For the `github` server above, the account skill command is
`/mcp:github:skill:github.com:account-and-team-context`. Remove the context-only
toolset restriction to expose workflows supported by the default toolsets.

Supply credentials through the normal server environment, not configuration
arguments or transcripts. Skill activation requires the client's explicit skill
consent even with `/allow-all` or `--yolo`. Discovery, command naming and consent
behavior depend on the CLI build; this flag alone does not establish client
conformance.

VS Code Insiders can opt into its skills client with
`chat.agentHost.mcpSkills.enabled: true`, using the same server configuration.
That setting is a client prerequisite, not a claim that every VS Code build
supports every extension feature.

Library integrators can extend `catalog.Source()` using `Registry.WithSkills`
and supply the resulting registry as `MCPServerConfig.SkillsSource`. Set each
additional skill's `RequiredTools` (groups of alternative tool names) and
`OptionalTools` before building the registry. The shared constructor filters the
catalog per request and removes instructions when its feature checker enables
`github.FeatureFlagSkillsExtension`.

## Declaring tool availability

### Issue artifacts
Expand Down
13 changes: 13 additions & 0 deletions docs/insiders-features.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,19 @@ Because this changes list tool response shape, clients that require JSON list re

---

## Skills instead of server instructions

Insiders Mode enables the `skills` feature flag. The server advertises the MCP
skills extension and serves a tool-filtered catalog of workflow guidance instead
of sending server instructions. Clients that do not consume skills receive no
replacement instructions. Use the normal non-insiders configuration without the
`skills` flag to retain existing server instructions.

See [MCP skills](./feature-flags.md#mcp-skills) for activation, protocol details
and client configuration.

---

## How feature flags are resolved

> [!NOTE]
Expand Down
2 changes: 1 addition & 1 deletion go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ require (
github.com/spf13/viper v1.21.0
github.com/stretchr/testify v1.12.1
github.com/yosida95/uritemplate/v3 v3.0.2
go.yaml.in/yaml/v3 v3.0.5
golang.org/x/net v0.61.0
golang.org/x/oauth2 v0.37.0
)
Expand All @@ -38,7 +39,6 @@ require (
github.com/spf13/cast v1.10.0 // indirect
github.com/stretchr/objx v0.5.3 // indirect
github.com/subosito/gotenv v1.6.0 // indirect
go.yaml.in/yaml/v3 v3.0.5 // indirect
golang.org/x/sync v0.24.0 // indirect
golang.org/x/sys v0.49.0 // indirect
golang.org/x/text v0.43.0 // indirect
Expand Down
4 changes: 3 additions & 1 deletion internal/ghmcp/server.go
Original file line number Diff line number Diff line change
Expand Up @@ -214,8 +214,10 @@ func NewStdioMCPServer(ctx context.Context, cfg github.MCPServerConfig) (*mcp.Se
WithToolsets(github.ResolvedEnabledToolsets(cfg.EnabledToolsets, cfg.EnabledTools)).
WithTools(github.CleanTools(cfg.EnabledTools)).
WithExcludeTools(cfg.ExcludeTools).
WithServerInstructions().
WithFeatureChecker(featureChecker)
if !deps.IsFeatureEnabled(ctx, github.FeatureFlagSkillsExtension) {
inventoryBuilder.WithServerInstructions()
}

// Apply token scope filtering if scopes are known (for PAT filtering)
if cfg.TokenScopes != nil {
Expand Down
5 changes: 5 additions & 0 deletions pkg/github/feature_flags.go
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,9 @@ const FeatureFlagDuplicateDetection = "duplicate_detection"
// FeatureFlagThreadResolutionReason exposes resolution reasons for Copilot review threads.
const FeatureFlagThreadResolutionReason = "thread_resolution_reason"

// FeatureFlagSkillsExtension replaces server instructions with MCP-served skills.
const FeatureFlagSkillsExtension = "skills"

// AllowedFeatureFlags is the allowlist of feature flags that can be enabled
// by users via --features CLI flag, X-MCP-Features HTTP header, or the
// features URL query parameter.
Expand All @@ -58,6 +61,7 @@ var AllowedFeatureFlags = []string{
FeatureFlagIssueArtifacts,
FeatureFlagDuplicateDetection,
FeatureFlagThreadResolutionReason,
FeatureFlagSkillsExtension,
}

// InsidersFeatureFlags is the list of feature flags that insiders mode enables.
Expand All @@ -68,6 +72,7 @@ var InsidersFeatureFlags = []string{
FeatureFlagCSVOutput,
FeatureFlagFileBlame,
FeatureFlagIssueDependencies,
FeatureFlagSkillsExtension,
}

// FeatureFlags defines runtime feature toggles that adjust tool behavior.
Expand Down
Loading
Loading