Skill manager: view, add, edit, and link skills across every harness

[n0mahd]

Problem

Skills live in a different directory for every harness: ~/.claude/skills, ~/.agents/skills, <repo>/.claude/skills, <repo>/.agents/skills, ~/.pi/agent/skills, and so on. Users who move between providers end up with duplicated copies that drift apart, or skills that one harness sees and another doesn't. T3 Code already scans every one of these locations per provider for the $ picker, but there's no way to see the gaps or fix them (see #6987, #6883).

Proposal

Revive #4630's read-only Settings → Skills page and extend it to every supported provider (Claude, Codex, Cursor, Grok, OpenCode, Antigravity, Pi), with a small set of actions:

• View: skills grouped by user scope and by project, with per-harness coverage (which harnesses actually load it), its source (one real copy, a symlink, or a drifted duplicate) and the rendered SKILL.md. One view per connected environment, so multi-machine setups can compare.
• Add: create a SKILL.md in the Agent Skills standard location, .agents/skills/, at user scope or project scope.
• Edit: a SKILL.md editor that saves to the symlink's resolved target, so editing a linked skill edits its source.
• Link into all harnesses: symlink the skill into each harness directory that doesn't read .agents/skills (for example .claude/skills/<name>, the same pattern this repo already uses). It never overwrites a real directory. Same-name duplicates with different contents are shown as conflicts for the user to resolve. Precedence is keyed by (scope, location, directory), not by name, per the edge case raised in [Feature]: Discover repo-local `.agents/skills` (Agent Skills standard) provider-agnostically, not per provider #6883.
• Reverse: unlink from one harness, and delete a skill with confirmation.

Server-side these are service methods behind the existing environment auth, so MCP tools for agents are a small follow-up.

Out of scope for the first PR: a mobile UI, MCP tools, marketplace or remote installs, and copying skills between machines (git or dotfiles already do that).

Question for maintainers: would you accept a PR with this scope, or would you rather it ship as a read-only view first with editing and linking as a second PR? I'm happy to share a working prototype in this thread for feedback on the UX before opening anything.

[Yuruzuu]

This would actually be very nice. I'd love to see it at some point with MCP servers being editable per provider too :)

[Jdreioe]

It would be very nice

[n0mahd]

Update: before asking for a PR, I built a working prototype to test this idea against real skill folders. Here is what it showed, what it looks like, and a proposed split into small PRs. Nothing is opened yet. I'd like an explicit yes or no on direction and scope first.

What the prototype showed

• There is already a shared layout to build on. Codex reads .agents/skills/<name>/ (project) and ~/.agents/skills/<name>/ (global) directly, and both the skills CLI and OpenKnowledge install skills there and link other agents' folders to them. Claude only reads .claude/skills, so it needs a link. In one real project, Claude could use 1 of its 36 skills because nothing had linked them.
• Reading the agents' skill folders directly is cheap. Reading ~100 skills across every agent's folders takes 25–90 ms on a Raspberry Pi 5, and the page loads with ~34 KB over the WebSocket. There are no provider rescans, no watchers and no cache. My first version asked each provider to rescan a project instead; that took 18 s and started three extra processes.
• Updates are checkable with one GitHub request per source repo. The lock files the skills CLI already writes (skills-lock.json in a repo, ~/.agents/.skill-lock.json globally) record enough to tell "the source changed" apart from "you edited it". In that same project, 32 of 35 installed skills had upstream changes nobody knew about.

Screenshots (demo data)

Skills for a project, with agents shown as icons (✦ = every enabled agent can use it):

A skill is a folder, so the page shows all of its files and flags scripts agents can run:

An update from the skill's source, shown in T3's own diff view before anything changes:

Tidy up: move a third-party pack to Global or link it for every agent, and resolve duplicates:

Select many skills at once, for example a whole pack, and act on them together:

Phone width:

Proposed PRs, one problem each

1. feat(web): see which agents can use each skill: a read-only Settings → Skills page with project, global, and built-in or plugin skills, each skill's folder with a file viewer, and Reveal in Finder. This finishes what feat(web): add cross-harness skill manager #4630 started. It writes nothing.
2. feat: turn skills on or off for each agent: per-agent links, moving a skill between Global and a project, remove or delete, and bulk actions. It never replaces a real folder and only removes links it can prove are links. On Windows it uses directory junctions so it works without Developer Mode (see [Bug]: Codex ChatGPT connection fails on Windows without Developer Mode: shadow home symlinks fail with EPERM #14325). Agents get the same actions as MCP tools.
3. feat(web): create and edit skills: a new skill dialog and editing through the existing project file writes.
4. feat: tidy up a project's skills: a short health note (for example "Claude can't use 35 of this project's skills") and a guided cleanup.
5. feat: update skills from their source: detection, a diff preview, update one or update all, and merge choices for skills you edited. It stays compatible with npx skills update.

Mobile and scheduled update checks would come later.

Questions

1. Is this direction and scope welcome? I'd open (1) first and wait for review before starting (2).
2. Is it OK to treat .agents/skills as each skill's home and link other agents' folders to it?
3. Where should the per-agent folder list live: next to the existing skill scanners in each provider driver, or in one shared table?

_{Prototype and write-up by Claude Opus 5.5 (orchestrating) and Claude Sonnet 5.5 (implementing), run in T3 Code.}

[n0mahd]

Update: I've opened the work as a three-part series so the direction can be judged on working code. Each part builds on the one before, and each PR links the other two:

1. feat(web): see which agents can use each skill (skills 1/3) #17513 feat(web): see which agents can use each skill. A read-only Settings → Skills page that finishes what feat(web): add cross-harness skill manager #4630 started.
2. feat: turn skills on or off for each agent (skills 2/3) #17514 feat: turn skills on or off for each agent. Each agent gets a switch, through a link or that agent's own setting. Use in… chooses this project, Global or only some projects. Delete, bulk actions, and MCP tools for agents.
3. feat: agent instructions, new skills, updates and tidy up on the Skills page (skills 3/3) #17515 feat: see and edit agent instructions on the Skills page. Covers AGENTS.md, CLAUDE.md, CLAUDE.local.md and one Global AGENTS.md shared by every agent. It shows which agent reads which file, and lets you edit them and move a project's CLAUDE.md into AGENTS.md. This wasn't in my list above. It's the same problem as skills: each agent reads a different set of files, and nothing shows which.

Compared with the five-PR plan above:

• turning skills on or off and moving them are now one PR (part 2);
• "create and edit" became Edit skill, which opens the skill in your editor;
• tidy-up and updates are left for later.

All three are rebased onto current main. CI's checks pass at each tip: knip, vp check, typecheck, every test suite and the desktop build. End-to-end checks in a real browser also passed against demo data.

Per CONTRIBUTING, I'd still like an explicit yes or no on direction and scope before anyone spends review time. If you'd rather take only part 1, or have parts 2 and 3 reshaped, say so and I'll adjust.

_{Implemented by Claude Sonnet 5.5 and reviewed by Claude Opus 5.5, run in T3 Code.}

[n0mahd]

Update: part 3 (#17515) now also covers the rest of the plan above, so the series is complete as proposed. On top of instructions, it adds:

• New skill: a name, a one-line description, and this project or Global. It writes SKILL.md in .agents/skills and turns it on for every agent.
• Built in and plugins: Codex's system skills and the skills of installed Claude Code plugins, listed apart. They belong to their agent, so they're never moved or deleted.
• Check for updates: one GitHub request per source repo, a preview before anything is written, and your edits kept, with a per-file choice when both sides changed the same lines. It stays compatible with npx skills update.
• Tidy up: one pass that moves a repo's skills to Global, drops project copies that are also in Global, moves skills out of Claude's own folder and turns skills on for agents that could use them. Nothing changes until you confirm.
• Phone app: Settings → Skills shows the same skills and instruction files, with the switches and fixes. Creating, updating and Tidy up stay web and desktop only.

Each new set of RPCs is its own group, merged into WsRpcGroup, so the wire contract is unchanged. CI's checks pass, and end-to-end checks in a real browser pass against demo data. The PR description has screenshots of each.

I'd still like an explicit yes or no on direction and scope before anyone spends review time. If part 3 is too big, I can split updates and Tidy up into their own PRs.

_{Implemented by Claude Sonnet 5.5 and Claude Opus 5.5, and reviewed by Claude Opus 5.5, run in T3 Code.}

[NK-Works]

Following up from #18637 (closed as dup of #6987, with this thread cited for the manager side):

Support the View/Add/Edit/Link plan here, plus two refinements from our grill:

• Four sibling sections, not skills-only: Skills / Plugins (nested Apps) / MCP / Subagents. Apps (Codex connectors like GitHub/Gmail) render nested inside their parent plugin with per-app toggles. Subagents get their own section like skills but disabled by default, opt-in only.
• Per-harness coverage + per-harness-only flag: the coverage view should also show which items are intentionally single-harness (e.g. Claude-only tool) so gaps don't read as breakage.

Edit-saves-to-symlink-target behavior proposed here is the right call — keeps one real copy.

[MikaMcFlurry]

For anyone mapping the skills work so nobody builds the same thing twice, there are three different "sharing" axes:

1. Across harnesses in one environment (this discussion): which agents see a skill, and filling the gaps.
2. Across environments/machines: feat(settings): browse and sync agent skills and instructions #24377 (@saphid) syncs skills and instruction files between connected environments.
3. Across provider accounts in one environment: several Codex homes (CODEX_HOME per account) or Claude config dirs each get their own skills folder, so a skill installed for one account is missing in the others.

I built 3 in a fork: mika/central-skills. There's one library under T3's state dir. Claude loads it as an additional directory, and each Codex home gets marked copies before probes and sessions. A user's own skill with the same name always wins. Agents can list, install and remove skills through MCP.

It doesn't overlap with 1 or 2 and could sit underneath either (for example #24377 syncing the central library instead of each account's folder). The same axis is the "later rules/skills" part of #14118, which is where I'd take it if there's interest.