Skip to content

feat: add skill:// resource templates for Agent Skills discovery#2129

Draft
SamMorrowDrums wants to merge 1 commit intomainfrom
skills-resources
Draft

feat: add skill:// resource templates for Agent Skills discovery#2129
SamMorrowDrums wants to merge 1 commit intomainfrom
skills-resources

Conversation

@SamMorrowDrums
Copy link
Copy Markdown
Collaborator

@SamMorrowDrums SamMorrowDrums commented Mar 3, 2026

Summary

Spike PR adding MCP resource templates that expose Agent Skills from GitHub repositories via the skill:// URI scheme, following the skills-as-resources approach discussed in the MCP Skills Interest Group.

Resource Templates

Template Description
skill://{owner}/{repo}/{skill_name}/SKILL.md Fetch a skill's instruction content
skill://{owner}/{repo}/{skill_name}/_manifest JSON manifest listing files with repo:// URIs

The manifest composes with existing repo:// resource templates — each file entry includes a working repo:// URI that clients can read directly using the already-registered repository content resources.

Discovery Conventions

Skills are discovered using the Git Trees API (recursive), matching these directory conventions from the agentskills.io ecosystem:

Convention Example
skills/*/SKILL.md Standard agentskills.io spec
skills/{namespace}/*/SKILL.md Namespaced skills (multi-author repos)
plugins/*/skills/*/SKILL.md Plugin marketplace convention
*/SKILL.md Root-level skill directories

Hidden directories (.github/, etc.) and convention prefixes (skills/, plugins/) are excluded from root-level matching.

Completions

Full completions support wired into the CompletionsHandler:

  • owner / repo — reuses existing resolvers
  • skill_name — discovers available skills via tree search

Toolset

Registered under a new non-default skills toolset. Enable with:

--toolsets=skills
--toolsets=default,skills

Example manifest output

{
  "skill": "my-skill",
  "files": [
    {"path": "SKILL.md", "uri": "repo://owner/repo/contents/skills/my-skill/SKILL.md", "size": 256},
    {"path": "references/REFERENCE.md", "uri": "repo://owner/repo/contents/skills/my-skill/references/REFERENCE.md", "size": 1024}
  ]
}

References

Add MCP resource templates that expose Agent Skills (per agentskills.io
spec) from GitHub repositories via the skill:// URI scheme.

Resource templates:
- skill://{owner}/{repo}/{skill_name}/SKILL.md — fetch skill content
- skill://{owner}/{repo}/{skill_name}/_manifest — JSON manifest with
  repo:// URIs for each file, composing with existing repo:// resources

Discovery uses the Git Trees API to find SKILL.md files under known
paths (.github/skills/, skills/, .copilot/skills/).

Completions support for owner, repo (reusing existing resolvers), and
skill_name (discovers skills via tree search).

Registered under a new non-default 'skills' toolset. Enable with
--toolsets=skills or --toolsets=default,skills.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
olaservo added a commit to olaservo/github-mcp-server that referenced this pull request Apr 28, 2026
Expands the Agent Skills surface from 2 to 28 bundled skills, adds a
per-repo resource template covering arbitrary GitHub repositories, and
introduces a model-facing discovery tool to bridge the gap left by the
SEP's UI-only completion mechanism.

- Import 25 workflow-oriented skills from github#2374
  as standalone SKILL.md files (skip review-pr and handle-notifications
  due to overlap with our pull-requests / inbox-triage). Migrate URI
  shape to skill://github/<name>/SKILL.md to match github#2374's prefix style.

- Remove the legacy Instructions / InstructionsFunc / WithServerInstructions
  machinery (~300 lines). Skills are now the only guidance surface.

- Add a SEP-aligned per-repo resource template
  skill://{owner}/{repo}/{skill_name}/{+file_path} (from PR github#2129, with
  the non-SEP _manifest endpoint dropped). Gated on a new non-default
  `skills` toolset. Index now advertises both SEP entry types
  (skill-md and mcp-resource-template).

- Add list_repo_skills tool that wraps the existing discoverSkills() and
  returns each discovered skill plus a skill:// URL ready for
  resources/read. Workaround for autonomous-agent discovery on unbounded
  template namespaces — documented as such.

- Add discover-mcp-skills meta-skill (always-on) that teaches the model
  the discover-then-read workflow for both bundled and repo-hosted
  surfaces.

Verified end-to-end against anthropics/skills via stdio JSON-RPC: full
loop from index read through SKILL.md to relative-file resolution works.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
olaservo added a commit to olaservo/github-mcp-server that referenced this pull request May 3, 2026
Adds the SEP-2640-aligned per-repo Agent Skills surface: a single
parameterized MCP resource template that lets any GitHub repo expose
its skills/ directory through the same skill:// URI scheme used for
bundled skills.

Template:
  skill://{owner}/{repo}/{skill_name}/{+file_path}

`{+file_path}` is RFC 6570 reserved expansion, so a multi-segment
relative path inside the skill directory (e.g. references/GUIDE.md)
round-trips through the template as a single value. SKILL.md and any
relative references mentioned inside it both resolve via this one
template handler.

Discovery on the server:
- Recognizes the four agentskills.io directory conventions:
  skills/<name>/SKILL.md, skills/<namespace>/<name>/SKILL.md,
  plugins/<plugin>/skills/<name>/SKILL.md, and root-level
  <name>/SKILL.md (excluding hidden + convention-prefix dirs).
- Skill discovery happens at request time via the Git Trees API.
- skill:// completion is wired through CompletionsHandler so MCP
  hosts can offer interactive autocomplete on owner/repo/skill_name.

Index integration:
- skills.Registry extended with BundledTemplate + AddTemplate +
  EnabledTemplates so skill://index.json now publishes both
  type:"skill-md" entries (the 27 bundled skills) and a single
  type:"mcp-resource-template" entry (the per-repo template).
- IndexEntry.Name is now omitempty since the SEP example shows
  template entries without a name.
- DeclareCapability fires for either type of entry being enabled.

Toolset gating:
- New non-default `skills` toolset gates the per-repo template's
  index entry. With --toolsets=default the per-repo surface is hidden;
  with --toolsets=default,skills (or --toolsets=all) it's published.
- The per-repo template is defined in pkg/github/skills_resource.go;
  registered via AllResources so the inventory wires it up alongside
  repo:// templates.

Adapted from the resource-template work in
github#2129. The non-SEP _manifest endpoint from
that PR is intentionally NOT ported — multi-file skill discovery is
handled by the SEP's per-file URI resolution, not a manifest JSON.

Tests cover: template definition, file handler with SKILL.md, file
handler with multi-segment relative path, missing-arg errors, path
traversal rejection, agentskills.io convention discovery,
URI parsing, completion handler, and the index-entry presence/absence
based on toolset gating.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant