Skip to content

[Mate] Add Symfony bridge skills anticipating the MCP Skills extension#2132

Draft
wachterjohannes wants to merge 1 commit into
symfony:mainfrom
wachterjohannes:mate-symfony-bridge-skills
Draft

[Mate] Add Symfony bridge skills anticipating the MCP Skills extension#2132
wachterjohannes wants to merge 1 commit into
symfony:mainfrom
wachterjohannes:mate-symfony-bridge-skills

Conversation

@wachterjohannes

@wachterjohannes wachterjohannes commented Jun 1, 2026

Copy link
Copy Markdown
Contributor
Q A
Bug fix? no
New feature? yes
Docs? yes
Issues -
License MIT

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.

Companion PR: the serving half lives in modelcontextprotocol/php-sdk#372, which adds io.modelcontextprotocol/skills (SEP-2640) support to the PHP MCP SDK so a directory of SKILL.md files is served as skill:// resources. This PR provides the skill content; that PR provides the transport.

What's added

src/mate/src/Bridge/Symfony/skills/

  • symfony-profiler-debugging/ — a request-debugging workflow over the profiler capabilities (symfony-profiler-list/-get, the symfony-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 a references/collectors.md field guide to exercise the multi-file / progressive-disclosure model.
  • symfony-container-introspection/ — a search → detail workflow over symfony-services and symfony-service-detail for ServiceNotFoundException, 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 as skill:// resources once php-sdk#372 lands — with no change to the content.

INSTRUCTIONS.md restructure

The Symfony bridge INSTRUCTIONS.md is 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-time instructions handshake 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.

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
wachterjohannes force-pushed the mate-symfony-bridge-skills branch from f0bf25f to 11f9aba Compare July 18, 2026 04:49
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Feature New feature Mate Issues & PRs about the AI Mate component Status: Needs Review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants