Skip to content

feat: replace server instructions with skill resources#2374

Draft
SamMorrowDrums wants to merge 7 commits intomainfrom
sammorrowdrums/skills-over-mcp-refactor
Draft

feat: replace server instructions with skill resources#2374
SamMorrowDrums wants to merge 7 commits intomainfrom
sammorrowdrums/skills-over-mcp-refactor

Conversation

@SamMorrowDrums
Copy link
Copy Markdown
Collaborator

@SamMorrowDrums SamMorrowDrums commented Apr 23, 2026

Summary

Replaces the server instructions system with MCP skill resources that follow the skill:// URI convention, enabling MCP clients (like pi-mcp-agent) to discover and load domain-specific guidance on demand.

Related: https://github.com/SamMorrowDrums/pi-mcp-agent/issues/2

What changed

Added

  • pkg/github/skill_resources.go — 16 skill resources covering all toolsets, registered as skill://github/{name}/SKILL.md static resources
  • pkg/github/skill_resources_test.go — tests verifying all tools are covered, content format, URI uniqueness, and registration

Removed

  • Server instructions — InstructionsFunc on ToolsetMetadata, generateInstructions(), WithServerInstructions() builder method, and the Instructions field from MCP server options
  • pkg/github/toolset_instructions.go — instruction generator functions
  • pkg/inventory/instructions.go — the generateInstructions function
  • pkg/inventory/instructions_test.go — associated tests

Skills created (16 total)

Skill Tools covered
context get_me, get_teams, get_team_members
repos search_repositories, get_file_contents, list_commits, search_code, etc.
issues issue_read, search_issues, list_issues, issue_write, etc.
pull-requests pull_request_read, create_pull_request, merge_pull_request, etc.
code-security code scanning, secret scanning, dependabot alerts
actions actions_list, actions_get, actions_run_trigger, get_job_logs
discussions list_discussions, get_discussion, etc.
projects projects_list, projects_get, projects_write
notifications list_notifications, dismiss_notification, etc.
gists list_gists, get_gist, create_gist, update_gist
users-orgs search_users, search_orgs
security-advisories global and repository security advisories
labels list_label, list_labels, label_write
git get_repository_tree
stargazers list_starred_repositories, star/unstar
copilot assign_copilot_to_issue, request_copilot_review

How it works

  1. Skills are registered as static MCP resources with skill://github/{name}/SKILL.md URIs
  2. MCP clients discover skills via resources/list (filtering for skill:// URIs)
  3. Each skill has YAML frontmatter with name, description, and allowed-tools
  4. The markdown body contains usage guidance (previously in server instructions)
  5. All tools remain available by default — skills provide context, not gating

Testing

  • script/lint ✅
  • script/test ✅ (all tests pass)
  • New tests verify coverage, content format, and registration

@SamMorrowDrums
feat: replace server instructions with skill resources
2140dd3 
Replace the server instructions system with MCP skill resources that
follow the skill:// URI convention for discovery by MCP clients.

Each skill resource covers a domain of tools and provides YAML
frontmatter (name, description, allowed-tools) plus markdown guidance.

All tools remain available by default (all tools mode). Skills provide
contextual guidance that clients can discover via resources/list.

16 skills covering all toolsets: context, repos, issues, pull-requests,
code-security, actions, discussions, projects, notifications, gists,
users-orgs, security-advisories, labels, git, stargazers, copilot.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@SamMorrowDrums SamMorrowDrums force-pushed the sammorrowdrums/skills-over-mcp-refactor branch from 118f25c to 2140dd3 Compare April 23, 2026 20:35
SamMorrowDrums and others added 6 commits April 24, 2026 10:50
@SamMorrowDrums
refactor: use backtick tool references in skill body content
d820b49 
Update all 16 skill definitions to use explicit backtick-formatted
tool names with '## Available Tools' sections instead of bold markdown
references. This makes tool names more reliably parseable by models
that consume the SKILL.md content via load_skill.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@SamMorrowDrums
refactor: replace toolset-oriented skills with 27 workflow-oriented s…
d79de8c 
…kills

Replace 16 toolset-oriented skills (repos, issues, pull-requests, etc.)
with 27 workflow-oriented skills that map to real user intents:

PR workflows: create-pr, review-pr, self-review-pr, address-pr-feedback, merge-pr
Issue workflows: triage-issues, create-issue, manage-sub-issues
CI/CD: debug-ci, trigger-workflow
Security: security-audit, fix-dependabot, research-vulnerability
Code exploration: explore-repo, search-code, trace-history
Projects: manage-project
Notifications: handle-notifications
Releases: prepare-release
Repository management: manage-repo, manage-labels
Collaboration: contribute-oss, browse-discussions, delegate-to-copilot
Discovery: discover-github, share-snippet, get-context

Each skill focuses on a specific workflow with non-obvious guidance,
anti-patterns, and identity-aware instructions (e.g., reviewing someone
else's PR vs self-reviewing your own). Tools overlap across skills
based on workflow needs rather than API domain.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@SamMorrowDrums
refactor: make skill descriptions trigger-friendly per agent skills spec
184979c 
Update all 27 skill descriptions to include both what the skill does
AND when to use it, following the agent skills specification guidance
that descriptions are the primary triggering mechanism. Descriptions
now explicitly list user intents that should activate each skill.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@SamMorrowDrums
fix: filter skill allowedTools against registered tools at startup
eb1865f 
Skills now only include tools that are actually registered with the
MCP server, based on the active toolset configuration. Skills with
no available tools are skipped entirely. This prevents skills from
referencing non-existent tools (e.g., gist tools when the gists
toolset isn't enabled).

RegisterSkillResources now accepts a map of available tool names
built from the inventory at startup time.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@SamMorrowDrums
fix: register all tools from all toolsets when skills are enabled
209f851 
When skills handle progressive disclosure, the server should expose
all tools via tools/list regardless of toolset configuration. The
client decides tool visibility through skill allowedTools, not the
server.

This replaces the previous filtering approach — now inv.AllTools()
registers every tool with the MCP server, and skills reference the
full tool surface.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@SamMorrowDrums
feat: make all toolsets default so skills have full tool surface
1a39440 
All toolsets are now enabled by default (Default: true). This ensures
every tool is registered out of the box, which is required for skills
to work — skills handle progressive tool discovery, so the server
should expose the full surface. Users can still restrict with
--toolsets if needed.

Reverts the inv.AllTools() registration workaround from server.go
since the normal RegisterAll path now picks up everything.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Awaiting requested review from Copilot Copilot will automatically review once the pull request is marked ready for review

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@SamMorrowDrums