[Mate] Add Symfony bridge skills anticipating the MCP Skills extension - #2132
Draft
wachterjohannes wants to merge 1 commit into
Draft
[Mate] Add Symfony bridge skills anticipating the MCP Skills extension#2132wachterjohannes wants to merge 1 commit into
wachterjohannes wants to merge 1 commit into
Conversation
wachterjohannes
requested review from
Nyholm,
OskarStark and
chr-hertel
as code owners
June 1, 2026 16:57
carsonbot
added
Status: Needs Review
Feature
wachterjohannes
marked this pull request as draft
June 1, 2026 16:57
This was referenced Jun 2, 2026
docs(findings): PHP MCP SDK + Symfony AI Mate skills-as-resources
modelcontextprotocol/ext-skills#95
Merged
Ship two Agent Skills (SKILL.md) colocated with the Symfony bridge tools they orchestrate: * symfony-profiler-debugging — request debugging workflow over the profiler tools/resources, with a references/collectors.md field guide * symfony-container-introspection — search/detail workflow over the container service tools Skills follow the agentskills.io format and SEP-2640 layout (directory name matches the frontmatter name), so they work as filesystem skills today and as skill:// resources once the SDK serves them. Restructure the bridge INSTRUCTIONS.md into a thin tool overview that points at the skills for the how-to, moving orchestration detail out of the init-time instructions field.
wachterjohannes
force-pushed
the
mate-symfony-bridge-skills
branch
from
July 18, 2026 04:49
f0bf25f to
11f9aba
Compare
chr-hertel
added a commit
that referenced
this pull request
Jul 21, 2026
…or coding agents (wachterjohannes) This PR was squashed before being merged into the main branch. Discussion ---------- [Mate] Add skills:install to install extension skills for coding agents | Q | A | ------------- | --- | Bug fix? | no | New feature? | yes | Docs? | yes | Issues | - | License | MIT Agent Skills (`SKILL.md`) shipped by Mate extensions are now installed onto the filesystem where coding agents read them — a polyfill until skills can be served over MCP directly. ### Background — MCP Skills (SEP-2640) This is the **consumer/polyfill side** of the MCP Skills effort: - **SEP-2640** proposes serving Agent Skills over MCP's Resources primitive as `skill://` resources — modelcontextprotocol/modelcontextprotocol#2640. - **#2132** already added skill *content* to the Mate Symfony bridge, anticipating the extension (agentskills.io + SEP-2640 layout) — #2132. - **modelcontextprotocol/php-sdk#372** implements the *serving* half in the PHP SDK (`skill://` resources + discovery index). The missing piece is **getting those skills onto the filesystem**: Claude Code and other agents do not consume MCP-served skills yet (June 2026) — they only read skills from disk. This PR bridges that gap and can be retired once agents consume MCP-served skills end-to-end. ### How it works Extensions declare one or more skills directories via a new `extra.ai-mate.skills` key: ```json { "extra": { "ai-mate": { "scan-dirs": ["src"], "skills": ["skills"] } } } ``` Each immediate subdirectory holding a `SKILL.md` is one skill. Mate **symlinks** each one — under a `mate-` prefixed directory name (e.g. `mate-system-information`) to avoid clashing with skills you maintain from other sources — into `.agents/skills/` (read by Codex, OpenCode and GitHub Copilot) and mirrors it into `.claude/skills/` for Claude Code, which only reads its own directory. The links point into the gitignored `vendor/`, so skills auto-update on `composer update`. ### Usage Skills install automatically as part of `discover`, which already runs after `composer require`, so there's usually nothing to run: ```terminal $ vendor/bin/mate discover ``` For an explicit re-sync: ```terminal $ vendor/bin/mate skills:install ``` The core package ships a built-in `system-information` skill to demonstrate the format and dogfood the mechanism. ### Notes - Documentation added under `docs/components/mate.rst` and `docs/components/mate/creating-extensions.rst`; `CHANGELOG.md` updated. - Covered by tests (installer, command, discovery, and the `discover` auto-sync); PHPStan clean. Commits ------- 6a88faf [Mate] Add skills:install to install extension skills for coding agents
chr-hertel
added a commit
that referenced
this pull request
Aug 23, 2026
… state in extensions.php (wachterjohannes)
This PR was merged into the main branch.
Discussion
----------
[Mate] Add skill lifecycle: discovery, copy install and state in extensions.php
| Q | A
| ------------- | ---
| Bug fix? | no
| New feature? | yes
| Docs? | yes
| Issues | -
| License | MIT
First of three PRs building the Mate skill lifecycle. Follow-Ups will add `skills:override`/`skills:reset` and `skills:enable`/`skills:disable`.
Skills are the workflow/knowledge layer above tools: inert `SKILL.md` procedures the agent reads, managed — never executed — by the CLI. The `extra.ai-mate.skills` config key already exists as a list of directories, so extensions that ship skills need no change; this PR builds the metadata, install and state layer on top of it.
### Install as a copy
A skill is installed as a real copy under `.agents/skills/mate-<name>/`, with its frontmatter `name` rewritten to the installed name so it cannot collide with a skill the user maintains.
Copies rather than symlinks into `vendor/` are the point: what the agent loads is a file you can open and diff, and a package update cannot change it underneath you. Only the `.claude/skills/` mirror is a relative symlink to that copy, so the two can never drift apart — falling back to a second copy where `symlink()` is unavailable (Windows without developer mode), which is isolated behind a `LinkerInterface` so the fallback is reachable in tests.
### One state file
Everything lives in `mate/extensions.php`, next to the intent it derives from:
```php
'vendor/package' => [
'enabled' => true,
'skills' => [
'demo-skill' => [
'enabled' => true, // yours to edit
'mode' => 'managed', // yours to edit: managed|override
'state' => 'managed', // written by mate below this point
'source' => 'vendor/vendor/package/skills/demo-skill',
'source_hash' => 'sha256:...',
'hash' => 'sha256:...',
'targets' => [
'.agents/skills/mate-demo-skill',
'.claude/skills/mate-demo-skill',
],
],
],
],
```
`SkillStateRepository` is the sole reader and writer of that path. `ContainerFactory` includes it independently and treats a non-array result as *every extension disabled*, so writes go through a temp file + `rename()`, and reads are served from cache once written in the same process (a mutating command does write → install → read, and opcache can otherwise hand back the pre-write file).
Two hashes are recorded because the copy is never byte-identical to its source — the rewritten `name` line: `hash` detects hand-edited output, `source_hash` detects an upstream change that has not been installed yet.
### Commands
* `skills:install` — idempotent reconciler. Rebuilds from source or from the user's `mate/skills/` copy, prunes skills whose source or extension vanished, and never writes into `mate/skills/`. `discover` runs it automatically.
* `skills:list` — read-only overview: enabled, mode, state, status (`ok`, `disabled`, `not installed`, `stale`, `broken`). Table, JSON or TOON.
* `skills:validate [name] [--strict]` — checks the generated folders against the record. Errors on hand-edited content, missing folders, a mispointed mirror, an overridden skill with no copy, and a disabled skill that still has folders; warns on a moved-on source, a never-installed skill, a copied mirror and strays. Exits non-zero on errors, or on warnings with `--strict`.
* `skills:prune [--dry-run]` — removes leftover generated folders. Only `mate-` prefixed entries are ever touched.
### Deliberately not git-ignored
The generated folders are **not** added to `.gitignore`. Because they are plain copies, committing them turns an upstream skill change into a reviewable diff instead of something that lands silently. (An earlier iteration managed a `.gitignore` block that ignored `/.agents/skills/` and `/.claude/skills/` wholesale — that would also have hidden skills the user maintains, including the five tracked `.claude/skills/*` files in this monorepo.)
### Notes for review
This is a BC break for anyone who configured skills under `0.12` — the `UPGRADE.md` entry covers it, and the PR needs the **BC Break** label (I cannot add it myself).
It also touches the `0.13` section of `src/mate/CHANGELOG.md`, which #2132 touches as well; whichever lands second needs a trivial rebase. Worth noting that #2132's skills use `description: >-` block scalars, which the front matter parser in this PR handles — on `0.12` they parse to the literal `">-"`.
Commits
-------
ffbc7cb [Mate] Add skill lifecycle: discovery, copy install and state in extensions.php
olaservo
added a commit
to modelcontextprotocol/ext-skills
that referenced
this pull request
Aug 28, 2026
* docs(findings): add PHP MCP SDK + Symfony AI Mate skills-as-resources entry First PHP-ecosystem implementation of SEP-2640: php-sdk#372 serves a directory of SKILL.md files as skill:// resources, symfony/ai#2132 ships the skill content in the Mate MCP server. Records what was verified (serving via MCP Inspector snapshots), the spec-text frictions hit (_meta namespace, resource name charset, empty-payload serialization), and the Claude Code consumption gap. * docs(findings): reframe _meta and resource-name notes per SEP-2640 review The SEP PR specifies the io.modelcontextprotocol.skills/ _meta prefix (our SDK independently converged on it); the resource-name point is an SDK registration-uniqueness detail, not a spec gap. Reframe both and note the PR-vs-repo-draft drift on the _meta sentence. * docs: note PHP SDK findings were written against the pre-v1 draft --------- Co-authored-by: olaservo <olahungerford@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Ships the first Agent Skills (
SKILL.md) for the Mate Symfony bridge, colocated with the tools they orchestrate. Skills are structured "how-to" knowledge — multi-step workflows that tell an agent how to combine tools to reach a goal, which plain tool descriptions can't express.What's added
src/mate/src/Bridge/Symfony/skills/symfony-profiler-debugging/— a request-debugging workflow over the profiler capabilities (symfony-profiler-list/-get, thesymfony-profiler://resources), following Mate's own triage → detail principle: locate the profile, read the overview, then open only the collector that explains the symptom. Includes areferences/collectors.mdfield guide to exercise the multi-file / progressive-disclosure model.symfony-container-introspection/— a search → detail workflow oversymfony-servicesandsymfony-service-detailforServiceNotFoundException, autowiring, tag queries, and "how is this service built" questions.Both follow the agentskills.io format and the SEP-2640 layout (directory name == frontmatter
name), so they are consumable as filesystem skills today (e.g. dropped into.claude/skills/) and asskill://resources once php-sdk#372 lands — with no change to the content.INSTRUCTIONS.md restructure
The Symfony bridge
INSTRUCTIONS.mdis slimmed from an orchestration manual into a thin tool overview that points at the skills for the how-to. This moves the bulky workflow detail out of the init-timeinstructionshandshake field (which loads once and is size-bounded) and into on-demand skills — the exact limitation the Skills-over-MCP work targets — while keeping a minimal tool table so agents stay aware of the tools even before any skill is loaded.No runtime/behavioral code changes; this is skill content + instructions and a CHANGELOG entry.