Skip to content

Commit f8b8f5c

Browse files
committed
fix(claude): discover enabled installed plugin skills
1 parent 4ee6bfd commit f8b8f5c

2 files changed

Lines changed: 289 additions & 17 deletions

File tree

‎apps/server/src/provider/Drivers/ClaudeSkills.test.ts‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,172 @@ const writeSkill = Effect.fn(function* (
2020
});
2121

2222
it.layer(NodeServices.layer)("discoverClaudeSkills", (it) => {
23+
it.effect(
24+
"discovers only enabled installed plugin skills with their namespace and metadata",
25+
() =>
26+
Effect.gen(function* () {
27+
const fs = yield* FileSystem.FileSystem;
28+
const path = yield* Path.Path;
29+
const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-claude-skills-" });
30+
const configDir = path.join(tempDir, "claude-home");
31+
const plugin = path.join(configDir, "plugins", "cache", "shop", "plugin", "1.0.0");
32+
yield* writeSkill(path.join(plugin, "skills"), "plain", "# Plain");
33+
yield* writeSkill(
34+
path.join(plugin, "skills", "engineering"),
35+
"review",
36+
"---\nname: ignored-alias\ndescription: Review changes.\ndisable-model-invocation: yes\nuser-invocable: no\n---\n",
37+
);
38+
yield* writeSkill(path.join(plugin, "extra"), "deploy", "# Deploy");
39+
yield* fs.makeDirectory(path.join(plugin, ".claude-plugin"), { recursive: true });
40+
yield* fs.writeFileString(
41+
path.join(plugin, ".claude-plugin", "plugin.json"),
42+
'{"skills":["./skills/engineering/review","./extra","./skills/plain"]}',
43+
);
44+
yield* fs.writeFileString(
45+
path.join(configDir, "plugins", "installed_plugins.json"),
46+
`{"version":2,"plugins":{
47+
"plugin@shop":[null,{"scope":"user","installPath":"${plugin.replaceAll("\\", "/")}"}],
48+
"disabled@shop":[{"scope":"user","installPath":"${plugin.replaceAll("\\", "/")}"}],
49+
"unmentioned@shop":[{"scope":"user","installPath":"${plugin.replaceAll("\\", "/")}"}]
50+
}}`,
51+
);
52+
yield* fs.writeFileString(
53+
path.join(configDir, "settings.json"),
54+
'{ "enabledPlugins": { "plugin@shop": true, "disabled@shop": false, "uninstalled@shop": true }, "skillOverrides": { "plugin:review": "off" } }',
55+
);
56+
57+
const skills = yield* discoverClaudeSkills({ homePath: configDir });
58+
assert.deepEqual(skills, [
59+
{
60+
name: "plugin:deploy",
61+
path: path.join(plugin, "extra", "deploy", "SKILL.md"),
62+
enabled: true,
63+
scope: "user",
64+
},
65+
{
66+
name: "plugin:plain",
67+
path: path.join(plugin, "skills", "plain", "SKILL.md"),
68+
enabled: true,
69+
scope: "user",
70+
},
71+
{
72+
name: "plugin:review",
73+
path: path.join(plugin, "skills", "engineering", "review", "SKILL.md"),
74+
enabled: false,
75+
scope: "user",
76+
description: "Review changes.",
77+
userInvocationOnly: true,
78+
userInvocable: false,
79+
},
80+
]);
81+
}),
82+
);
83+
84+
it.effect(
85+
"keeps plugin installs in their workspace and prefers local then project over user",
86+
() =>
87+
Effect.gen(function* () {
88+
const fs = yield* FileSystem.FileSystem;
89+
const path = yield* Path.Path;
90+
const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-claude-skills-" });
91+
const configDir = path.join(tempDir, "claude-home");
92+
const workspace = path.join(tempDir, "workspace");
93+
const other = path.join(tempDir, "other");
94+
const installs = ["user", "project", "local", "foreign"].map((scope) =>
95+
path.join(configDir, "plugins", scope),
96+
);
97+
for (const install of installs)
98+
yield* writeSkill(path.join(install, "skills"), "review", "# Review");
99+
yield* fs.writeFileString(
100+
path.join(configDir, "plugins", "installed_plugins.json"),
101+
`{"version":2,"plugins":{
102+
"plugin@shop":[
103+
{"scope":"user","installPath":"${installs[0]!.replaceAll("\\", "/")}"},
104+
{"scope":"project","projectPath":"${workspace.replaceAll("\\", "/")}","installPath":"${installs[1]!.replaceAll("\\", "/")}"},
105+
{"scope":"local","projectPath":"${workspace.replaceAll("\\", "/")}","installPath":"${installs[2]!.replaceAll("\\", "/")}"},
106+
{"scope":"local","projectPath":"${other.replaceAll("\\", "/")}","installPath":"${installs[3]!.replaceAll("\\", "/")}"}
107+
],
108+
"foreign@shop":[{"scope":"project","projectPath":"${other.replaceAll("\\", "/")}","installPath":"${installs[3]!.replaceAll("\\", "/")}"}],
109+
"ownerless@shop":[{"scope":"project","installPath":"${installs[3]!.replaceAll("\\", "/")}"}]
110+
}}`,
111+
);
112+
yield* fs.writeFileString(
113+
path.join(configDir, "settings.json"),
114+
'{"enabledPlugins":{"plugin@shop":true,"foreign@shop":true,"ownerless@shop":true}}',
115+
);
116+
117+
const local = yield* discoverClaudeSkills({ homePath: configDir }, workspace);
118+
assert.deepEqual(
119+
local.map((skill) => [skill.name, skill.scope, skill.path]),
120+
[["plugin:review", "project", path.join(installs[2]!, "skills", "review", "SKILL.md")]],
121+
);
122+
const user = yield* discoverClaudeSkills({ homePath: configDir });
123+
assert.deepEqual(
124+
user.map((skill) => [skill.name, skill.scope, skill.path]),
125+
[["plugin:review", "user", path.join(installs[0]!, "skills", "review", "SKILL.md")]],
126+
);
127+
128+
// Windows does not allow colon-bearing filesystem skill directories.
129+
if (path.sep !== "\\") {
130+
yield* writeSkill(
131+
path.join(workspace, ".claude", "skills"),
132+
"plugin:review",
133+
"# Project review",
134+
);
135+
yield* writeSkill(path.join(configDir, "skills"), "plugin:review", "# User review");
136+
const collision = yield* discoverClaudeSkills({ homePath: configDir }, workspace);
137+
assert.equal(collision.length, 1);
138+
assert.equal(
139+
collision[0]?.path,
140+
path.join(configDir, "skills", "plugin:review", "SKILL.md"),
141+
);
142+
}
143+
}),
144+
);
145+
146+
it.effect(
147+
"merges plugin enablement separately from overrides and honors explicit local disables",
148+
() =>
149+
Effect.gen(function* () {
150+
const fs = yield* FileSystem.FileSystem;
151+
const path = yield* Path.Path;
152+
const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-claude-skills-" });
153+
const configDir = path.join(tempDir, "claude-home");
154+
const workspace = path.join(tempDir, "workspace");
155+
const plugin = path.join(configDir, "plugins", "cached");
156+
yield* writeSkill(path.join(plugin, "skills"), "review", "# Review");
157+
yield* fs.writeFileString(
158+
path.join(configDir, "plugins", "installed_plugins.json"),
159+
`{"version":2,"plugins":{"plugin@shop":[{"scope":"user","installPath":"${plugin.replaceAll("\\", "/")}"}]}}`,
160+
);
161+
yield* fs.writeFileString(
162+
path.join(configDir, "settings.json"),
163+
'{"enabledPlugins":{"plugin@shop":false}}',
164+
);
165+
yield* fs.makeDirectory(path.join(workspace, ".claude"), { recursive: true });
166+
yield* fs.writeFileString(
167+
path.join(workspace, ".claude", "settings.json"),
168+
'// project enablement\n{"enabledPlugins":{"plugin@shop":true,},"skillOverrides":{"plugin:review":"invalid"}}',
169+
);
170+
assert.equal((yield* discoverClaudeSkills({ homePath: configDir }, workspace)).length, 1);
171+
yield* fs.writeFileString(
172+
path.join(workspace, ".claude", "settings.local.json"),
173+
'{"enabledPlugins":{"plugin@shop":false}}',
174+
);
175+
assert.deepEqual(yield* discoverClaudeSkills({ homePath: configDir }, workspace), []);
176+
yield* fs.writeFileString(
177+
path.join(workspace, ".claude", "settings.local.json"),
178+
'{"enabledPlugins":{"plugin@shop":true}}',
179+
);
180+
assert.equal((yield* discoverClaudeSkills({ homePath: configDir }, workspace)).length, 1);
181+
yield* fs.writeFileString(
182+
path.join(configDir, "plugins", "installed_plugins.json"),
183+
"not json",
184+
);
185+
assert.deepEqual(yield* discoverClaudeSkills({ homePath: configDir }, workspace), []);
186+
}),
187+
);
188+
23189
it.effect("discovers user and project skills with frontmatter metadata", () =>
24190
Effect.gen(function* () {
25191
const fs = yield* FileSystem.FileSystem;

‎apps/server/src/provider/Drivers/ClaudeSkills.ts‎

Lines changed: 123 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
* matching the CLI. `.agents/skills` is a Codex location: verified against the
88
* CLI, a skill that lives only there is answered with `Unknown command`, so it
99
* is not scanned here.
10+
* Enabled installed plugins contribute namespaced skills from their cache
11+
* and manifest-declared directories, with installation ownership preserved.
1012
* The Agent SDK init handshake surfaces skills only as slash commands without
1113
* their filesystem paths, so the provider snapshot scans the same locations
1214
* directly, mirroring how the Codex app-server reports its skills.
@@ -19,6 +21,7 @@ import type { ClaudeSettings, ServerProviderSkill } from "@t3tools/contracts";
1921
import * as Effect from "effect/Effect";
2022
import * as FileSystem from "effect/FileSystem";
2123
import * as Path from "effect/Path";
24+
import * as Option from "effect/Option";
2225
import * as Schema from "effect/Schema";
2326
import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
2427
import { fromLenientJson } from "@t3tools/shared/schemaJson";
@@ -28,6 +31,13 @@ import { expandHomePath } from "../../pathExpansion.ts";
2831

2932
type ClaudeSkillScope = "user" | "project";
3033

34+
type ClaudeSkillRoot = {
35+
readonly directory: string;
36+
readonly scope: ClaudeSkillScope;
37+
readonly prefix?: string;
38+
readonly singleSkill?: boolean;
39+
};
40+
3141
const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
3242

3343
type SkillFrontmatter =
@@ -213,6 +223,13 @@ const SkillOverrideSettings = fromLenientJson(
213223
}),
214224
);
215225
const decodeSkillOverrideSettings = Schema.decodeUnknownEffect(SkillOverrideSettings);
226+
const decodeEnabledPluginSettings = Schema.decodeUnknownEffect(
227+
fromLenientJson(
228+
Schema.Struct({
229+
enabledPlugins: Schema.optional(Schema.Record(Schema.String, Schema.Boolean)),
230+
}),
231+
),
232+
);
216233

217234
/**
218235
* What a `skillOverrides` entry says about one skill. `"user-invocable-only"`
@@ -236,15 +253,16 @@ function parseSkillOverride(value: typeof SkillOverrideValue.Type): SkillOverrid
236253
}
237254
}
238255

239-
const readSkillOverrides = Effect.fn("readSkillOverrides")(function* (
256+
const readSkillSettings = Effect.fn("readSkillSettings")(function* (
240257
configDirPath: string,
241258
cwd: string | undefined,
242259
environment: NodeJS.ProcessEnv,
243-
): Effect.fn.Return<ReadonlyMap<string, SkillOverride>, never, FileSystem.FileSystem | Path.Path> {
260+
) {
244261
const fileSystem = yield* FileSystem.FileSystem;
245262
const path = yield* Path.Path;
246263
const platform = yield* HostProcessPlatform;
247264
const overridesByName = new Map<string, SkillOverride>();
265+
const enabledPlugins = new Map<string, boolean>();
248266
const repositoryRoot = cwd === undefined ? undefined : yield* findRepositoryRoot(cwd);
249267

250268
for (const settingsPath of skillOverrideSettingsPaths(
@@ -271,17 +289,95 @@ const readSkillOverrides = Effect.fn("readSkillOverrides")(function* (
271289
),
272290
Effect.orElseSucceed(() => undefined),
273291
);
274-
const overrides = parsed?.skillOverrides;
275-
if (!overrides) {
276-
continue;
277-
}
278-
279-
for (const [name, value] of Object.entries(overrides)) {
292+
for (const [name, value] of Object.entries(parsed?.skillOverrides ?? {})) {
280293
overridesByName.set(name, parseSkillOverride(value));
281294
}
295+
// Decode independently: an invalid skillOverrides map must not discard
296+
// the plugin enablement in the same settings file.
297+
const pluginSettings = yield* decodeEnabledPluginSettings(contents).pipe(
298+
Effect.orElseSucceed(() => undefined),
299+
);
300+
for (const [key, enabled] of Object.entries(pluginSettings?.enabledPlugins ?? {})) {
301+
enabledPlugins.set(key, enabled);
302+
}
282303
}
283304

284-
return overridesByName;
305+
return { skillOverrides: overridesByName, enabledPlugins };
306+
});
307+
308+
const InstalledPlugins = Schema.fromJsonString(
309+
Schema.Struct({ plugins: Schema.Record(Schema.String, Schema.Array(Schema.Unknown)) }),
310+
);
311+
const decodeInstalledPlugin = Schema.decodeUnknownOption(
312+
Schema.Struct({
313+
scope: Schema.Literals(["user", "project", "local"]),
314+
installPath: Schema.NonEmptyString,
315+
projectPath: Schema.optional(Schema.NonEmptyString),
316+
}),
317+
);
318+
const PluginManifest = Schema.fromJsonString(
319+
Schema.Struct({
320+
skills: Schema.optional(Schema.Union([Schema.String, Schema.Array(Schema.String)])),
321+
}),
322+
);
323+
324+
/** Installed plugin records are authoritative; marketplace catalogs include uninstalled plugins. */
325+
const discoverPluginSkillRoots = Effect.fn("discoverPluginSkillRoots")(function* (
326+
configDirPath: string,
327+
cwd: string | undefined,
328+
enabledPlugins: ReadonlyMap<string, boolean>,
329+
): Effect.fn.Return<ReadonlyArray<ClaudeSkillRoot>, never, FileSystem.FileSystem | Path.Path> {
330+
const fileSystem = yield* FileSystem.FileSystem;
331+
const path = yield* Path.Path;
332+
const installed = yield* fileSystem
333+
.readFileString(path.join(configDirPath, "plugins", "installed_plugins.json"))
334+
.pipe(
335+
Effect.flatMap(Schema.decodeUnknownEffect(InstalledPlugins)),
336+
Effect.orElseSucceed(() => undefined),
337+
);
338+
const roots: Array<ClaudeSkillRoot> = [];
339+
const workspace = cwd === undefined ? undefined : path.resolve(cwd);
340+
const scopePriority = { user: 0, project: 1, local: 2 };
341+
342+
for (const [key, entries] of Object.entries(installed?.plugins ?? {}).sort()) {
343+
if (enabledPlugins.get(key) !== true) continue;
344+
const prefix = key.split("@")[0];
345+
if (!prefix) continue;
346+
const install = entries
347+
.flatMap((entry) => {
348+
const record = Option.getOrUndefined(decodeInstalledPlugin(entry));
349+
if (!record) return [];
350+
if (
351+
record.scope !== "user" &&
352+
(record.projectPath === undefined || path.resolve(record.projectPath) !== workspace)
353+
) {
354+
return [];
355+
}
356+
return [record];
357+
})
358+
.sort((left, right) => scopePriority[right.scope] - scopePriority[left.scope])[0];
359+
if (!install) continue;
360+
const scope = install.scope === "user" ? "user" : "project";
361+
roots.push({ directory: path.join(install.installPath, "skills"), scope, prefix });
362+
363+
// Plugins such as mattpocock-skills declare individual nested folders;
364+
// a declared path can also be a directory containing several skills.
365+
const manifest = yield* fileSystem
366+
.readFileString(path.join(install.installPath, ".claude-plugin", "plugin.json"))
367+
.pipe(
368+
Effect.flatMap(Schema.decodeUnknownEffect(PluginManifest)),
369+
Effect.orElseSucceed(() => undefined),
370+
);
371+
const declared = manifest?.skills;
372+
for (const relative of typeof declared === "string" ? [declared] : (declared ?? [])) {
373+
const directory = path.resolve(install.installPath, relative);
374+
const singleSkill = yield* fileSystem
375+
.exists(path.join(directory, "SKILL.md"))
376+
.pipe(Effect.orElseSucceed(() => false));
377+
roots.push({ directory, scope, prefix, singleSkill });
378+
}
379+
}
380+
return roots;
285381
});
286382

287383
/**
@@ -330,21 +426,30 @@ export const discoverClaudeSkills = Effect.fn("discoverClaudeSkills")(function*
330426
const fileSystem = yield* FileSystem.FileSystem;
331427
const path = yield* Path.Path;
332428
const configDirPath = yield* resolveClaudeConfigDirPath(config, environment ?? process.env, cwd);
333-
const skillOverrides = yield* readSkillOverrides(configDirPath, cwd, environment ?? process.env);
429+
const { skillOverrides, enabledPlugins } = yield* readSkillSettings(
430+
configDirPath,
431+
cwd,
432+
environment ?? process.env,
433+
);
334434

335-
const roots: ReadonlyArray<{ directory: string; scope: ClaudeSkillScope }> = [
435+
const roots: ReadonlyArray<ClaudeSkillRoot> = [
336436
{ directory: path.join(configDirPath, "skills"), scope: "user" },
337437
...(cwd ? [{ directory: path.join(cwd, ".claude", "skills"), scope: "project" as const }] : []),
438+
...(yield* discoverPluginSkillRoots(configDirPath, cwd, enabledPlugins)),
338439
];
339440

340441
const skillsByName = new Map<string, ServerProviderSkill>();
341442
for (const root of roots) {
342-
const entries = yield* fileSystem
343-
.readDirectory(root.directory)
344-
.pipe(Effect.orElseSucceed((): ReadonlyArray<string> => []));
443+
const entries = root.singleSkill
444+
? [path.basename(root.directory)]
445+
: yield* fileSystem
446+
.readDirectory(root.directory)
447+
.pipe(Effect.orElseSucceed((): ReadonlyArray<string> => []));
345448

346449
for (const entry of [...entries].sort()) {
347-
const skillPath = path.join(root.directory, entry, "SKILL.md");
450+
const skillPath = root.singleSkill
451+
? path.join(root.directory, "SKILL.md")
452+
: path.join(root.directory, entry, "SKILL.md");
348453
const contents = yield* fileSystem
349454
.readFileString(skillPath)
350455
.pipe(Effect.orElseSucceed(() => undefined));
@@ -366,10 +471,11 @@ export const discoverClaudeSkills = Effect.fn("discoverClaudeSkills")(function*
366471
// `probe-alias`, and only `skillOverrides["probe-alias"]` switches it
367472
// off. Keying off the frontmatter name would report a command that does
368473
// not exist and miss the override that disables it.
369-
const name = entry.trim();
370-
if (!name) {
474+
const directoryName = entry.trim();
475+
if (!directoryName) {
371476
continue;
372477
}
478+
const name = root.prefix ? `${root.prefix}:${directoryName}` : directoryName;
373479

374480
// First root wins, so a later root never displaces a higher-precedence
375481
// skill of the same name.

0 commit comments

Comments
 (0)