[Mate] Add skill lifecycle: discovery, copy install and state in extensions.php

[wachterjohannes]

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:

'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 ">-".

[kbond]

I've added the BC Break label.

To clarify, symlinking to the vendor dir is no longer an option, they're always copied now? I just read the UPGRADE. I think this is the right move - now it's closer to a Flex recipe and mate/extensions.php is like symfony.lock

[chr-hertel]

feels a bit edge-casey - would be also fine to add that in a later iteration if the issue comes up

[chr-hertel]

Looks pretty good to me 👍

few things to consider:

• would filesystem component remove a bit of load?
• is the feature set in this depth needed already
• after all PRs land we should take a look at the docs, to make sure Mate is easy to understand - maybe even waiting on the MCP removal

Feel free to go ahead please 🙏

[wachterjohannes]

@chr-hertel Thanks, all pushed.

Filesystem component: yes. SkillInstaller now uses mirror(), remove(), mkdir() and dumpFile(), about 90 lines lighter. One caveat worth knowing: mirror() recreates symlinks it finds inside a skill folder, so it gets an iterator that filters those out.

Mispointed mirror: good catch. isUpToDate() accepted any resolvable symlink, so skills:install never repaired what skills:validate kept reporting. There is now a shared mirrorState() that both use, plus two regression tests.

Feature depth / skills:prune: kept for now, because prune is the only remedy for the stray folder warning skills:validate raises, so dropping the command means dropping that check too. And there will be more commands to manage the state of the skills in the nearer future

Docs: agreed, one pass after the remaining PRs and the MCP removal beats tuning them per PR. This one only flips the config section to lead with the commands instead of the file.

Also rebased onto main, the UPGRADE.md conflict is gone.

[chr-hertel]

Thank you @wachterjohannes.