feat: install skills from a source, view their files, and let agents change Tools

[juliusmarminge]

Stacked on #17101.

Problem

Settings → Tools (#17101) can switch skills on and off, but it can't install a skill, show what's inside one, tell where it came from, or warn that two different skills share a name. Agents also had no way to change Tools themselves. The outside skills series (#17513–#17515) showed these gaps; this takes the parts that fit #17101's model, where T3 never writes an agent's config files.

Change

Install skills like npx skills

• Add skills takes a GitHub owner/repo, a git URL or a folder on the environment. It lists the source's skills (name, description, file count, and an Includes scripts badge), and installs the ones you pick at the current scope:
  • at environment scope into ~/.agents/skills;
  • at project scope into the project's .agents/skills and skills-lock.json, which can be committed.
• Installs run the real skills CLI (1.7.1, MIT), pinned and bundled into the server, with its telemetry off. So the folders, links and lock files are the same ones npx skills writes, and a terminal npx skills update keeps working.
  • It runs as a hidden t3 skills-cli subcommand of T3 itself (like acp-mcp-bridge). No Node or npm is needed on the environment, and the CLI is a lazily loaded chunk of the server bundle.
  • Arguments are built from typed input only, git can't prompt, and stdin is closed.
• Agents that read only their own folder get a link to the installed skill, chosen from a new per-agent folder table (packages/provider-core/src/server/AgentSkillFolders.ts, adapted from feat(web): see which agents can use each skill (skills 1/3) #17513). Claude gets a .claude/skills link, Grok in projects, and Antigravity globally.
• Update reinstalls a skill from the source its lock records. Remove deletes it with its links and lock entry. Both only apply to skills the CLI installed.

See what's there (the list and skill page follow @n0mahd's design in #17513, credited as co-author)

• The list has dense one-line rows and sections with a count and a hint ("This project · 2 · Lives in this repo"). A ✦ shows when every enabled agent loads a skill; otherwise the row shows the agents that do.
• Packs: skills installed from a source are grouped under a collapsible From owner/repo row, with one switch for the group and the first three skills shown. This covers skills installed here or with npx skills; both read the CLI's lock files.
• Conflict: a mark appears when two copies of a name have different SKILL.md text. Copies reached through links count as one.
• Needs attention filters to conflicts, and to project or global skills an enabled agent doesn't load.
• The skill page opens from a row and goes back on Escape. It shows:
  • Used by chips and the source;
  • Includes scripts, naming the script files;
  • Copy path, Update and Remove;
  • a file tree with script labels, and a read-only viewer that renders SKILL.md (Preview/Source) and reuses projects.readFile;
  • a switch between copies when a name has several.

Agents

• New MCP tools:
  • t3_tools_read and t3_tools_update switch skills and Settings → Tools servers for the environment or a project, in one settings write;
  • t3_skills_install and t3_skills_remove.
• The settings patches they write are shared with the web page (packages/shared/src/agentTools.ts), so both produce the same overrides.

Server and permissions

• A SkillLibrary service backs the new skills.* RPCs: inspect, preview, install, update and remove.
• Inspect only looks at the SKILL.md paths the enabled agents report; a client never names a path.
• Install, update and remove need providers:manage, like adding an MCP server, because a skill can carry scripts every agent can run. Inspect and preview need filesystem:read.
• A project install needs a registered project's folder.
• Install, update and remove run one at a time, because each CLI run rewrites a whole lock file.
• Afterwards every project the agents have listed is rescanned, one agent at a time per folder. Only the first scan is fresh: a fresh scan drops the other agents' lists of that folder, so a second fresh scan would erase the first agent's result.
• ServerSettingsService.updateSettingsWith(build) is new. It builds a patch from the latest settings inside the write lock, so t3_tools_update can't overwrite a concurrent change.
• Project skill switches now match names ignoring case (mergeProjectDisabledSkills), like the environment list and the composer already did.

Docs: docs/user/tools.md.

Not in this PR: a skills.sh search (sources are pasted), separate switches per agent, moving skills between scopes, editing skills, instruction files (#17515), and mobile.

Verification

• Focused tests:
  • SkillLibrary runs the real bundled CLI through bin.ts against a temp HOME and a local source, with no network. It covers preview, a project install with Claude's link, inspect reporting the source, update, remove, and the refusals.
  • The t3_tools_update handler writes one patch for a project and never returns secrets.
  • Logic tests cover source groups, the conflict mark, availability, Needs attention and the SKILL.md body.
• Checks: server, web, contracts, shared and client-runtime typecheck; targeted lint; knip on the affected workspaces.
• Bundle: vp pack the server, then node dist/bin.mjs skills-cli add … installs from the bundle.
• In the real app (dev server, a throwaway git project):
  • Add skills → mattpocock/skills listed 38 skills and flagged the 4 with scripts.
  • Installing grill-me and tdd wrote .agents/skills, Claude's .claude/skills links and skills-lock.json, the same as npx skills.
  • The row showed under From mattpocock/skills.
  • Update restored a locally edited tdd. Remove deleted its folder, link and lock entry.
  • Editing the project's grill-me so it differed from the global copy showed Conflict. Its skill page switched between the project copy and the global one.
  • Installing diagnosing-bugs showed it as loaded by both Claude and Codex straight away, with Includes scripts and its .sh file labeled script.
  • At 390 px the list has no horizontal overflow.
• Real agent: a Claude Sonnet 5.5 turn in the project loaded the installed grill-me (session init lists it) and called t3_tools_read through the t3-code MCP server.

Not checked: Windows (the CLI uses junctions there), a desktop build, and a remote environment. They use the same RPCs and the same bundled CLI.

Before	After

Skill page	Dark	Phone

Add skills	Agent calling t3_tools_read

_{Implemented by Claude Opus 5.5 in T3 Code (Claude Code harness).}

🤖 Generated with Claude Code

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This is a large production feature that installs and removes executable skill content, adds agent-facing settings mutation, starts configured MCP servers with stored environment variables, and changes the built-in tool and authorization surface. An unresolved High-severity finding also affects skill export with directory symlinks, so the change requires human review.

Not approved because:

• 1 blocking correctness issue found at or above your repo's Minimum Blocking Severity

^{Adjust the Minimum Blocking Severity for this repo — including turning it Off — in Settings. You can add or adjust custom eligibility rules. Learn more.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

ℹ️ No successful main baseline artifact is available yet. This run establishes the initial measurement.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	—	5.0 KiB	—	6.8 KiB	✅
Codex	Thread snapshot wire	—	3.8 KiB	—	4.9 KiB	✅
Codex	Live turn WebSocket wire	—	1.2 KiB	—	2.0 KiB	✅
Codex	Live turn WebSocket decoded	—	20.9 KiB	—	29.3 KiB	✅
Codex	Live turn messages	—	2	—	8	✅
Claude	Total thread wire	—	5.0 KiB	—	6.8 KiB	✅
Claude	Thread snapshot wire	—	3.8 KiB	—	4.9 KiB	✅
Claude	Live turn WebSocket wire	—	1.2 KiB	—	2.0 KiB	✅
Claude	Live turn WebSocket decoded	—	21.2 KiB	—	29.3 KiB	✅
Claude	Live turn messages	—	1	—	8	✅

Baseline: unavailable · PR result: 88a827b · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

🟠 High skills/SkillLibrary.ts:723

Exporting a skill with a directory symlink fails with a filesystem error instead of producing a bundle: listFiles includes links, and this loop passes each path to readFile, which fails when the path is a directory link. Filter symlink entries before reading them, or preserve links explicitly in the bundle.

-      const bundled = yield* Effect.forEach(files, (file) =>
+      const regularFiles = yield* Effect.filter(files, (file) =>
+        fileSystem.readLink(path.join(folder, file.path)).pipe(
+          Effect.as(false),
+          Effect.orElseSucceed(() => true),
+        ),
+      );
+      const bundled = yield* Effect.forEach(regularFiles, (file) =>

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @apps/server/src/skills/SkillLibrary.ts around line 723:

Exporting a skill with a directory symlink fails with a filesystem error instead of producing a bundle: `listFiles` includes links, and this loop passes each path to `readFile`, which fails when the path is a directory link. Filter symlink entries before reading them, or preserve links explicitly in the bundle.