[Mate] Add skills:install to install extension skills for coding agents

[wachterjohannes]

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 — SEP-2640: Skills Extension modelcontextprotocol/modelcontextprotocol#2640.
• [Mate] Add Symfony bridge skills anticipating the MCP Skills extension #2132 already added skill content to the Mate Symfony bridge, anticipating
  the extension (agentskills.io + SEP-2640 layout) — [Mate] Add Symfony bridge skills anticipating the MCP Skills extension #2132.
• [Schema][Server] Add Skills extension (io.modelcontextprotocol/skills) support 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:

{
    "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:

$ vendor/bin/mate discover

For an explicit re-sync:

$ 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.

[Guikingone]

What about using https://packagist.org/packages/guikingone/agent-skills as the retrieval layer for skills? Already implement the specifications and allows to add new loader if needed 🤔

This could also trigger discussion about #1718

[wachterjohannes]

Thanks @Guikingone — looked at both agent-skills and #1718. I think we're solving two different layers, so I don't think the package replaces this PR:

• agent-skills / [Agent] Add support for AgentSkills #1718 load skills into a PHP agent runtime (system-prompt injection, skill-as-tool, eval/grading).
• This PR goes the other way: it materializes skills onto disk (.agents/skills/ + symlinks into .claude/skills/) so external coding-agent CLIs read them — the polyfill side of SEP-2640 until they consume skill:// directly.

The only real overlap is the thin "parse SKILL.md" slice. That's worth sharing — but I'd rather see a common spec/parse abstraction land first-party in the Agent component via #1718 than have Mate core take a third-party dependency. Happy to align this PR with whatever #1718 settles on.

[wachterjohannes]

@kbond i have striped down the scope of this PR i have a few ideas for further PRs but that is not important for the first tests here.

@chr-hertel you can review but i would wait for @kbond to test this feature with maker skills

[kbond]

@wachterjohannes Ok, I finally got around to testing this.

I used zenstruck/foundry as an example package to add skills. Here's the branch.

It worked as expected but I had to run vendor/bin/mate discover explicitly to sync. I have the plugin installed/enabled. Maybe something to do with my local vendor setup?

I love the simplicity of this! Let's discuss how to move forward!

[wachterjohannes]

@kbond thanks for the feedback - this first version is indeed a very simple version that just proves that it works and make sense.

As discussed in slack one-by-one i think your developer setup with the link binary do not trigger the composer plugin and thats the reason why it does not run discover automatically.

The next steps should be following:

1. En/Disable Skills - so that they will not be symlinked or removed from the "blacklist"
2. Overwrite Skills- that will copy the skill into the directory instead of symlink and not overwrite it in any later on run of skills install
3. Make the init command more interactive

• ask for agents (codex, claude, ...) so that the symlinks, wrappers, ... can be build ontop of that information
• ask for the purpose - mcp or skills or both - so that the developer can decide what he actually needs
• maybe other questions to individualize that

5. Some kind of debugging command