Tools: Use native agent skill discovery - #80811

Size Change: 0 B

Total Size: 7.76 MB

_{compressed-size-action}

Flaky tests detected in 37f1da4.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/30465864292
📝 Reported issues:

• [Flaky Test] Should navigate inner blocks with arrow keys #39607 in /test/e2e/specs/editor/various/writing-flow.spec.js

The postintall script is responsible for creating the correct agent-specific (ie. claude) aliases depending on which platform (macos, linux, windows). It is based off what the skills npm package does when installing a skill

Without that script, I guess our best alternative would be to manually commit those alias files as real skills that internally re-direct to the equivalent .agents/skills — although I don't know if I like that alternative; it would be extra manual work, it would more expensive to run (claude would need to load an addiitonal skill), and it's not adhering to the tranditional conventions.

The postintall script is responsible for creating the correct agent-specific (ie. claude) aliases depending on which platform (macos, linux, windows). It is based off what the skills npm package does when installing a skill

Gotcha. I'm understanding the framework more and seeing your point. What about when we remove or add new skills - does the npm run test:agents:setup need to get run again? Does it handle pruning old skills and adding new symlinks as needed?

Good questions, and actually a few missing gaps that I now addressed. npm run agents:setup now:

• Adds aliases for supported agents (symlinks, if not available Windows junctions, if not available a full copy)
• Prunes removed skills aliases (only for managed skills)
• Preserves unmanaged aliases

I also updated the guide to mention to re-run the setup script after changing the skill catalog.

Edit: see update

This looks like it's in the right direction 👍 What we had before was not skills, it was a folder of markdown files that we called "skills". Skills, as I understand them, have their existence mechanically understood by agents because they scan specific folders. .agents/ seems like the sensible cross-agent default, and adding whatever backfills for other popular clients that use their proprietary setup (e.g. Claude).

@jeryj and @aduth — following this suggestion, I pushed an update that greatly simplifies the setup script (and related tests) by assuming that the entire .claude/skills folder is disposable (and git ignored).

@jeryj and @aduth — following this suggestion, I pushed an update that greatly simplifies the setup script (and related tests) by assuming that the entire .claude/skills folder is disposable (and git ignored).

I think it's still possible developers might have their own personal skills and I don't know that I'd go as far as to say it's entirely disposable. The command I shared in the thread would have preserved a developer's own, with the exception of any which have conflicting names (not super likely, and we'd have the option to choose to either force-override or skip in these cases). Is that possible to retain? It feels like removing the rm would suffice. I guess the risk there is that it could accumulate stale skills for things that have been removed, but how likely is it that we'd be frequently removing skills?

The command I shared in the thread would have preserved a developer's own, with the exception of any which have conflicting names

That setup would work well on a first pass, but it would not work well in a bunch of edge cases (naming conflicts, skill renaming / removal, etc). And as we cover all of these edge cases, we'd basically go back to the previous version.

More in general, I believe that we should favor agent-agnostic tooling (ie. .agents/skills over .claude/skills). We already do that for AGENTS.md and CLAUDE.md, so the current approach feels consistent ?

If a consumer of the repo has a skill in .claude/skills, we could argue that they should switch to one of the following:

• if it's a useful skill for everyone, propose it as a repo-wide skill in .agents/skills
• it's a personal skill, move it to whatever local configuration they have on their machine

If we're worried about wiping out existing .claude/skills files, we could add a check in the setup script?

Maybe it's fine. I'm not as sure on the point of "it's a personal skill, move it to whatever local configuration they have on their machine". Is it possible to have a personal skill tailored to a particular project that lives outside the project itself? I guess it could be a "global" skill and using description to provide clues to an agent that it's relevant to a particular project.

Maybe it's fine. I'm not as sure on the point of "it's a personal skill, move it to whatever local configuration they have on their machine". Is it possible to have a personal skill tailored to a particular project that lives outside the project itself? I guess it could be a "global" skill and using description to provide clues to an agent that it's relevant to a particular project.

that's what I personally do — in the skill description and body, I specify that it targets a specific project.

Would you be ok to merge as-is, and refine the approach if/as needed?

If agents:setup is run manually, then it seems a bit more reasonable that it would supersede personal skills as an explicit choice to perform that setup. It'd be more concerning if it was done automatically. We'd probably want to document this. The setup script documentation is a bit buried here 😅

Nice! I've pushed a final commit which adds some docs refinements, and also adds a prompt when running the setup script if we find claude-specific skills that don't have a match in the .agents/skills folder (this is mostly to avoid wiping out a personal skill sitting in that folder)

I think this is a good starting point!

@aduth Follow-up: postinstall now refreshed the aliases, but stops conservatively if it finds a mismatch.

Running the script again manually allows to force the override, hopefully a good compromise between automatizing the process without wiping out files unexpectedly.