The best way to control Claude Code, Codex and more from any computer or phone
fix(claude): discover enabled installed plugin skills (#15662)
Co-authored-by: Julius Marminge <julius0216@outlook.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
maria committed
Oct 20, 2026 at 05:39 UTC
c2b127f8f11080dbdcfdb9cd0f8078fb10e7727b
3 files changed
+498
-30
apps/server/src/provider/Drivers/ClaudeSkills.test.ts
+270
@@ -21,6 +21,276 @@ const writeSkill = Effect.fn(function* (
21
});
22
23
it.layer(NodeServices.layer)("discoverClaudeSkills", (it) => {
24
+ it.effect("discovers enabled plugin skills with manifest names and ignores skill overrides", () =>
25
+ Effect.gen(function* () {
26
+ const fs = yield* FileSystem.FileSystem;
27
+ const path = yield* Path.Path;
28
+ const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-claude-skills-" });
29
+ const configDir = path.join(tempDir, "claude-home");
30
+ const plugin = path.join(configDir, "plugins", "cache", "shop", "plugin", "1.0.0");
31
+ const disabled = path.join(configDir, "plugins", "disabled");
32
+ yield* writeSkill(path.join(disabled, "skills"), "hidden", "# Hidden");
33
+ yield* writeSkill(path.join(plugin, "skills"), "plain", "# Plain");
34
+ yield* writeSkill(
35
+ path.join(plugin, "engineering"),
36
+ "review",
37
+ "---\nname: review-alias\ndescription: Review changes.\ndisable-model-invocation: true\nuser-invocable: false\n---\n",
38
+ );
39
+ yield* fs.makeDirectory(path.join(plugin, ".claude-plugin"), { recursive: true });
40
+ yield* fs.writeFileString(
41
+ path.join(plugin, ".claude-plugin", "plugin.json"),
42
+ '{"name":"manifest-plugin","skills":["./engineering/review"]}',
43
+ );
44
+ yield* fs.writeFileString(
45
+ path.join(configDir, "plugins", "installed_plugins.json"),
46
+ JSON.stringify({
47
+ plugins: {
48
+ "plugin@shop": [{ scope: "user", installPath: plugin }],
49
+ "disabled@shop": [{ scope: "user", installPath: disabled }],
50
+ "unconfigured@shop": [{ scope: "user", installPath: disabled }],
51
+ },
52
+ }),
53
+ );
54
+ yield* fs.writeFileString(
55
+ path.join(configDir, "settings.json"),
56
+ '{"enabledPlugins":{"plugin@shop":true,"disabled@shop":false,"uninstalled@shop":true,"other@shop":["^1.0.0"]},"skillOverrides":{"manifest-plugin:plain":"off"}}',
57
+ );
58
+
59
+ const skills = yield* discoverClaudeSkills({ homePath: configDir });
60
+ assert.deepEqual(skills, [
61
+ {
62
+ name: "manifest-plugin:plain",
63
+ path: path.join(plugin, "skills", "plain", "SKILL.md"),
64
+ enabled: true,
65
+ scope: "user",
66
+ },
67
+ {
68
+ name: "manifest-plugin:review-alias",
69
+ path: path.join(plugin, "engineering", "review", "SKILL.md"),
70
+ enabled: true,
71
+ scope: "user",
72
+ description: "Review changes.",
73
+ userInvocationOnly: true,
74
+ userInvocable: false,
75
+ },
76
+ ]);
77
+ }),
78
+ );
79
+
80
+ it.effect("merges plugin enablement and selects installs in native registry order", () =>
81
+ Effect.gen(function* () {
82
+ const fs = yield* FileSystem.FileSystem;
83
+ const path = yield* Path.Path;
84
+ const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-claude-skills-" });
85
+ const configDir = path.join(tempDir, "claude-home");
86
+ const workspace = path.join(tempDir, "workspace");
87
+ const nestedWorkspace = path.join(workspace, "packages", "app");
88
+ const aliasedWorkspace = path.join(tempDir, "aliased-workspace");
89
+ const userInstall = path.join(configDir, "plugins", "user");
90
+ const projectInstall = path.join(configDir, "plugins", "project");
91
+ const localInstall = path.join(configDir, "plugins", "local");
92
+ const managedInstall = path.join(configDir, "plugins", "managed");
93
+ yield* fs.makeDirectory(path.join(workspace, ".git"), { recursive: true });
94
+ yield* fs.makeDirectory(nestedWorkspace, { recursive: true });
95
+ yield* fs.symlink(workspace, aliasedWorkspace);
96
+ for (const install of [userInstall, projectInstall, localInstall, managedInstall]) {
97
+ yield* writeSkill(path.join(install, "skills"), "review", "# Review");
98
+ }
99
+ yield* fs.writeFileString(
100
+ path.join(configDir, "plugins", "installed_plugins.json"),
101
+ JSON.stringify({
102
+ plugins: {
103
+ "plugin@shop": [
104
+ { scope: "project", projectPath: aliasedWorkspace, installPath: localInstall },
105
+ { scope: "project", projectPath: workspace, installPath: projectInstall },
106
+ { scope: "user", installPath: userInstall },
107
+ { scope: "managed", installPath: managedInstall },
108
+ ],
109
+ "local@shop": [
110
+ { scope: "local", projectPath: workspace, installPath: localInstall },
111
+ { scope: "project", projectPath: workspace, installPath: projectInstall },
112
+ { scope: "managed", installPath: path.join(configDir, "plugins", "missing") },
113
+ { scope: "managed", installPath: managedInstall },
114
+ { scope: "user", installPath: userInstall },
115
+ ],
116
+ },
117
+ }),
118
+ );
119
+ yield* fs.writeFileString(
120
+ path.join(configDir, "settings.json"),
121
+ '{"enabledPlugins":{"plugin@shop":true,"local@shop":false}}',
122
+ );
123
+ yield* fs.makeDirectory(path.join(workspace, ".claude"), { recursive: true });
124
+ yield* fs.writeFileString(
125
+ path.join(workspace, ".claude", "settings.json"),
126
+ '{"enabledPlugins":{"plugin@shop":false,"local@shop":true,"other@shop":["^1.0.0"]}}',
127
+ );
128
+ const projectSettings = yield* discoverClaudeSkills({ homePath: configDir }, workspace);
129
+ assert.deepEqual(
130
+ projectSettings.map((skill) => [skill.name, skill.scope, skill.path]),
131
+ [["local:review", "project", path.join(localInstall, "skills", "review", "SKILL.md")]],
132
+ );
133
+ assert.deepEqual(
134
+ (yield* discoverClaudeSkills({ homePath: configDir }, nestedWorkspace)).map((skill) => [
135
+ skill.name,
136
+ skill.scope,
137
+ skill.path,
138
+ ]),
139
+ [["plugin:review", "project", path.join(projectInstall, "skills", "review", "SKILL.md")]],
140
+ );
141
+ yield* fs.writeFileString(
142
+ path.join(workspace, ".claude", "settings.local.json"),
143
+ '{"enabledPlugins":{"plugin@shop":true,"local@shop":false},"skillOverrides":{"invalid":"bogus"}}',
144
+ );
145
+ assert.deepEqual(
146
+ yield* discoverClaudeSkills({ homePath: configDir }, workspace),
147
+ projectSettings,
148
+ );
149
+ yield* fs.writeFileString(
150
+ path.join(workspace, ".claude", "settings.local.json"),
151
+ '{"enabledPlugins":{"plugin@shop":true,"local@shop":true}}',
152
+ );
153
+ const localSettings = yield* discoverClaudeSkills({ homePath: configDir }, workspace);
154
+ assert.deepEqual(
155
+ localSettings.map((skill) => [skill.name, skill.scope, skill.path]),
156
+ [
157
+ ["local:review", "project", path.join(localInstall, "skills", "review", "SKILL.md")],
158
+ ["plugin:review", "project", path.join(projectInstall, "skills", "review", "SKILL.md")],
159
+ ],
160
+ );
161
+ assert.deepEqual(
162
+ yield* discoverClaudeSkills({ homePath: configDir }, nestedWorkspace),
163
+ localSettings,
164
+ );
165
+ assert.deepEqual(
166
+ yield* discoverClaudeSkills({ homePath: configDir }, aliasedWorkspace),
167
+ localSettings,
168
+ );
169
+ yield* fs.writeFileString(
170
+ path.join(workspace, ".claude", "settings.local.json"),
171
+ '{"enabledPlugins":{"local@shop":["^1.0.0"]}}',
172
+ );
173
+ assert.deepEqual(yield* discoverClaudeSkills({ homePath: configDir }, workspace), []);
174
+ yield* fs.writeFileString(
175
+ path.join(configDir, "settings.json"),
176
+ '{"enabledPlugins":{"plugin@shop":true,"local@shop":true}}',
177
+ );
178
+ const separateRepository = path.join(workspace, "separate");
179
+ yield* fs.makeDirectory(path.join(separateRepository, ".git"), { recursive: true });
180
+ for (const cwd of [undefined, path.join(tempDir, "elsewhere"), separateRepository]) {
181
+ const elsewhere = yield* discoverClaudeSkills({ homePath: configDir }, cwd);
182
+ assert.deepEqual(
183
+ elsewhere.map((skill) => [skill.name, skill.scope, skill.path]),
184
+ [
185
+ ["local:review", "user", path.join(managedInstall, "skills", "review", "SKILL.md")],
186
+ ["plugin:review", "user", path.join(userInstall, "skills", "review", "SKILL.md")],
187
+ ],
188
+ );
189
+ }
190
+ const worktree = path.join(tempDir, "worktree");
191
+ const worktreeGitDirectory = path.join(workspace, ".git", "worktrees", "fixture");
192
+ yield* fs.makeDirectory(worktree);
193
+ yield* fs.makeDirectory(worktreeGitDirectory, { recursive: true });
194
+ yield* fs.writeFileString(path.join(worktree, ".git"), `gitdir: ${worktreeGitDirectory}\n`);
195
+ yield* fs.writeFileString(path.join(worktreeGitDirectory, "commondir"), "../..\n");
196
+ yield* fs.writeFileString(
197
+ path.join(worktreeGitDirectory, "gitdir"),
198
+ path.join(worktree, ".git"),
199
+ );
200
+ assert.deepEqual(
201
+ yield* discoverClaudeSkills({ homePath: configDir }, worktree),
202
+ localSettings,
203
+ );
204
+ const linkedWorktree = path.join(tempDir, "linked-worktree");
205
+ yield* fs.symlink(worktree, linkedWorktree);
206
+ assert.deepEqual(
207
+ yield* discoverClaudeSkills({ homePath: configDir }, linkedWorktree),
208
+ localSettings,
209
+ );
210
+ }),
211
+ );
212
+
213
+ it.effect("publishes and dispatches canonical plugin folder names regardless of aliases", () =>
214
+ Effect.gen(function* () {
215
+ const fs = yield* FileSystem.FileSystem;
216
+ const path = yield* Path.Path;
217
+ const configDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-claude-skills-" });
218
+ const plugin = path.join(configDir, "plugins", "installed");
219
+ yield* writeSkill(path.join(plugin, "skills"), "review", "---\nname: review-alias\n---\n");
220
+ yield* writeSkill(path.join(plugin, "skills"), "alias", "---\nname: dot.alias\n---\n");
221
+ yield* fs.writeFileString(
222
+ path.join(configDir, "plugins", "installed_plugins.json"),
223
+ JSON.stringify({ plugins: { "plugin@shop": [{ scope: "user", installPath: plugin }] } }),
224
+ );
225
+ yield* fs.writeFileString(
226
+ path.join(configDir, "settings.json"),
227
+ '{"enabledPlugins":{"plugin@shop":true}}',
228
+ );
229
+
230
+ const skills = yield* discoverClaudeSkills({ homePath: configDir });
231
+ assert.deepEqual(
232
+ planClaudeSkillDispatch(
233
+ "$plugin:alias focus on auth",
234
+ new Map(skills.map((skill) => [skill.name, skill])),
235
+ ),
236
+ {
237
+ leadingText: undefined,
238
+ commandText: "/plugin:alias focus on auth",
239
+ skillName: "plugin:alias",
240
+ },
241
+ );
242
+ assert.deepEqual(
243
+ skills.map((skill) => skill.name),
244
+ ["plugin:alias", "plugin:review"],
245
+ );
246
+ }),
247
+ );
248
+
249
+ it.effect("uses the native cache root, root-skill fallback and manifest path boundaries", () =>
250
+ Effect.gen(function* () {
251
+ const fs = yield* FileSystem.FileSystem;
252
+ const path = yield* Path.Path;
253
+ const workspace = yield* fs.makeTempDirectoryScoped({ prefix: "t3-claude-skills-" });
254
+ const configDir = path.join(workspace, "config");
255
+ const pluginsDir = path.join(workspace, "plugin-cache");
256
+ const plugin = path.join(pluginsDir, "installed");
257
+ const outside = path.join(workspace, "outside");
258
+ yield* writeSkill(pluginsDir, "installed", "---\nname: plugin:root.alias\n---\n");
259
+ yield* fs.makeDirectory(configDir);
260
+ yield* fs.writeFileString(
261
+ path.join(configDir, "settings.json"),
262
+ '{"enabledPlugins":{"plugin@shop":true}}',
263
+ );
264
+ yield* fs.writeFileString(
265
+ path.join(pluginsDir, "installed_plugins.json"),
266
+ JSON.stringify({ plugins: { "plugin@shop": [{ scope: "user", installPath: plugin }] } }),
267
+ );
268
+ const environment = { CLAUDE_CODE_PLUGIN_CACHE_DIR: "plugin-cache" };
269
+ assert.deepEqual(
270
+ (yield* discoverClaudeSkills({ homePath: configDir }, workspace, environment)).map(
271
+ (skill) => skill.name,
272
+ ),
273
+ ["plugin:root-alias"],
274
+ );
275
+
276
+ yield* writeSkill(path.join(plugin, "skills"), "plain", "# Plain");
277
+ yield* writeSkill(plugin, "custom", "---\nname: custom.review\n---\n");
278
+ yield* writeSkill(outside, "escaped", "# Outside");
279
+ yield* fs.symlink(outside, path.join(plugin, "escape"));
280
+ yield* fs.makeDirectory(path.join(plugin, ".claude-plugin"));
281
+ yield* fs.writeFileString(
282
+ path.join(plugin, ".claude-plugin", "plugin.json"),
283
+ '{"skills":["./custom","./escape","../../outside"]}',
284
+ );
285
+ assert.deepEqual(
286
+ (yield* discoverClaudeSkills({ homePath: configDir }, workspace, environment)).map(
287
+ (skill) => skill.name,
288
+ ),
289
+ ["plugin:custom-review", "plugin:plain"],
290
+ );
291
+ }),
292
+ );
293
+
294
it.effect("discovers user and project skills with frontmatter metadata", () =>
295
Effect.gen(function* () {
296
const fs = yield* FileSystem.FileSystem;
apps/server/src/provider/Drivers/ClaudeSkills.ts
+226
-29
@@ -2,16 +2,24 @@ import type { ClaudeSettings, ServerProviderSkill } from "@t3tools/contracts";
2
import * as Effect from "effect/Effect";
3
import * as FileSystem from "effect/FileSystem";
4
import * as Path from "effect/Path";
5
+import * as Option from "effect/Option";
6
import * as Schema from "effect/Schema";
7
import * as HostProcess from "@t3tools/shared/HostProcess";
8
import { parseCliArgs } from "@t3tools/shared/cliArgs";
9
import { fromLenientJson } from "@t3tools/shared/schemaJson";
10
+import { SKILL_MENTION_PATTERN } from "@t3tools/shared/composerInlineTokens";
11
import { parse as parseYamlDocument } from "yaml";
12
13
import { expandHomePath } from "@t3tools/provider-core/server/pathExpansion";
14
15
type ClaudeSkillScope = "user" | "project";
16
17
+type ClaudeSkillRoot = {
18
+ readonly directory: string;
19
+ readonly scope: ClaudeSkillScope;
20
+ readonly prefix?: string;
21
+};
22
+
23
const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
24
25
type SkillFrontmatter =
@@ -19,6 +27,7 @@ type SkillFrontmatter =
27
| { readonly kind: "malformed" }
28
| {
29
readonly kind: "parsed";
30
+ readonly name?: string;
31
readonly description?: string;
32
readonly userInvocationOnly?: boolean;
33
readonly userInvocable?: boolean;
@@ -85,9 +94,11 @@ function parseSkillFrontmatter(contents: string): SkillFrontmatter {
94
}
95
96
const record = parsed as Record<string, unknown>;
97
+ const name = typeof record.name === "string" ? record.name.trim() : "";
98
const description = typeof record.description === "string" ? record.description.trim() : "";
99
return {
100
kind: "parsed",
101
+ ...(name ? { name } : {}),
102
...(description ? { description } : {}),
103
...(parseFrontmatterBoolean(record["disable-model-invocation"]) === true
104
? { userInvocationOnly: true }
@@ -157,6 +168,43 @@ const findRepositoryRoot = Effect.fn("findRepositoryRoot")(function* (
168
}
169
});
170
171
+const findPluginRepositoryRoot = Effect.fn("findPluginRepositoryRoot")(function* (cwd: string) {
172
+ const fileSystem = yield* FileSystem.FileSystem;
173
+ const path = yield* Path.Path;
174
+ const root = yield* findRepositoryRoot(cwd);
175
+ if (root === undefined) return undefined;
176
+ const gitFile = yield* fileSystem
177
+ .readFileString(path.join(root, ".git"))
178
+ .pipe(Effect.orElseSucceed(() => ""));
179
+ if (!gitFile.trim().startsWith("gitdir:")) return root;
180
+ const gitDirectory = path.resolve(root, gitFile.trim().slice(7).trim());
181
+ const commonFile = yield* fileSystem
182
+ .readFileString(path.join(gitDirectory, "commondir"))
183
+ .pipe(Effect.orElseSucceed(() => ""));
184
+ const worktreeFile = yield* fileSystem
185
+ .readFileString(path.join(gitDirectory, "gitdir"))
186
+ .pipe(Effect.orElseSucceed(() => ""));
187
+ if (!commonFile.trim() || !worktreeFile.trim()) return root;
188
+ const commonDirectory = path.resolve(gitDirectory, commonFile.trim());
189
+ const backlinkPath = yield* fileSystem
190
+ .realPath(path.resolve(gitDirectory, worktreeFile.trim()))
191
+ .pipe(Effect.orElseSucceed(() => undefined));
192
+ const worktreeGitPath = yield* fileSystem
193
+ .realPath(path.join(root, ".git"))
194
+ .pipe(Effect.orElseSucceed(() => undefined));
195
+ if (
196
+ path.dirname(gitDirectory) !== path.join(commonDirectory, "worktrees") ||
197
+ backlinkPath === undefined ||
198
+ backlinkPath !== worktreeGitPath
199
+ ) {
200
+ return root;
201
+ }
202
+ // Claude shares plugin install records across linked worktrees, using their common repository.
203
+ return path.basename(commonDirectory) === ".git"
204
+ ? path.dirname(commonDirectory)
205
+ : commonDirectory;
206
+});
207
+
208
/**
209
* The CLI validates the whole map, not each entry: verified against it, one
210
* entry with an unknown value (or a boolean) makes it drop every override in
@@ -167,12 +215,13 @@ const SkillOverrideValue = Schema.Literals(["on", "name-only", "user-invocable-o
215
216
// Lenient because these settings files are hand-edited and Claude Code itself
217
// tolerates comments and trailing commas in them.
170
-const SkillOverrideSettings = fromLenientJson(
218
+const SkillSettings = fromLenientJson(
219
Schema.Struct({
220
skillOverrides: Schema.optional(Schema.Record(Schema.String, SkillOverrideValue)),
221
+ enabledPlugins: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
222
}),
223
);
175
-const decodeSkillOverrideSettings = Schema.decodeUnknownEffect(SkillOverrideSettings);
224
+const decodeSkillSettings = Schema.decodeUnknownEffect(SkillSettings);
225
226
type SkillOverride = {
227
readonly enabled: boolean;
@@ -191,15 +240,16 @@ function parseSkillOverride(value: typeof SkillOverrideValue.Type): SkillOverrid
240
}
241
}
242
194
-const readSkillOverrides = Effect.fn("readSkillOverrides")(function* (
243
+const readSkillSettings = Effect.fn("readSkillSettings")(function* (
244
configDirPath: string,
245
cwd: string | undefined,
246
environment: NodeJS.ProcessEnv,
198
-): Effect.fn.Return<ReadonlyMap<string, SkillOverride>, never, FileSystem.FileSystem | Path.Path> {
247
+) {
248
const fileSystem = yield* FileSystem.FileSystem;
249
const path = yield* Path.Path;
250
const platform = yield* HostProcess.Platform;
251
const overridesByName = new Map<string, SkillOverride>();
252
+ const enabledPlugins = new Map<string, boolean>();
253
const repositoryRoot = cwd === undefined ? undefined : yield* findRepositoryRoot(cwd);
254
255
for (const settingsPath of skillOverrideSettingsPaths(
@@ -217,26 +267,150 @@ const readSkillOverrides = Effect.fn("readSkillOverrides")(function* (
267
continue;
268
}
269
220
- const parsed = yield* decodeSkillOverrideSettings(contents).pipe(
270
+ const parsed = yield* decodeSkillSettings(contents).pipe(
271
Effect.tapError((cause) =>
222
- Effect.logDebug("claude settings file is unreadable; ignoring skillOverrides", {
272
+ Effect.logDebug("claude settings file is unreadable; ignoring skill settings", {
273
path: settingsPath,
274
cause,
275
}),
276
),
277
Effect.orElseSucceed(() => undefined),
278
);
229
- const overrides = parsed?.skillOverrides;
230
- if (!overrides) {
231
- continue;
232
- }
233
-
234
- for (const [name, value] of Object.entries(overrides)) {
279
+ for (const [name, value] of Object.entries(parsed?.skillOverrides ?? {})) {
280
overridesByName.set(name, parseSkillOverride(value));
281
}
282
+ for (const [key, enabled] of Object.entries(parsed?.enabledPlugins ?? {})) {
283
+ if (typeof enabled === "boolean") {
284
+ enabledPlugins.set(key, enabled);
285
+ } else {
286
+ // Extended formats replace lower-precedence values without enabling the plugin here.
287
+ enabledPlugins.delete(key);
288
+ }
289
+ }
290
}
291
239
- return overridesByName;
292
+ return { skillOverrides: overridesByName, enabledPlugins };
293
+});
294
+
295
+const InstalledPlugins = Schema.fromJsonString(
296
+ Schema.Struct({ plugins: Schema.Record(Schema.String, Schema.Array(Schema.Unknown)) }),
297
+);
298
+const decodeInstalledPlugin = Schema.decodeUnknownOption(
299
+ Schema.Struct({
300
+ scope: Schema.Literals(["user", "project", "local", "managed"]),
301
+ installPath: Schema.NonEmptyString,
302
+ projectPath: Schema.optional(Schema.NonEmptyString),
303
+ }),
304
+);
305
+const PluginManifest = Schema.fromJsonString(
306
+ Schema.Struct({
307
+ name: Schema.optional(Schema.NonEmptyString),
308
+ skills: Schema.optional(Schema.Union([Schema.String, Schema.Array(Schema.String)])),
309
+ }),
310
+);
311
+
312
+function isInsideDirectory(path: Path.Path, directory: string, candidate: string): boolean {
313
+ const relative = path.relative(directory, candidate);
314
+ return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
315
+}
316
+
317
+const discoverPluginSkillRoots = Effect.fn("discoverPluginSkillRoots")(function* (
318
+ configDirPath: string,
319
+ cwd: string | undefined,
320
+ enabledPlugins: ReadonlyMap<string, boolean>,
321
+ environment: NodeJS.ProcessEnv,
322
+) {
323
+ const fileSystem = yield* FileSystem.FileSystem;
324
+ const path = yield* Path.Path;
325
+ const home = yield* HostProcess.HomeDirectory;
326
+ const pluginDirectory = environment.CLAUDE_CODE_PLUGIN_CACHE_DIR;
327
+ const pluginsPath = pluginDirectory
328
+ ? path.resolve(cwd ?? ".", expandHomePath(pluginDirectory, home))
329
+ : path.join(configDirPath, "plugins");
330
+ const installed = yield* fileSystem
331
+ .readFileString(path.join(pluginsPath, "installed_plugins.json"))
332
+ .pipe(
333
+ Effect.flatMap(Schema.decodeUnknownEffect(InstalledPlugins)),
334
+ Effect.orElseSucceed(() => undefined),
335
+ );
336
+ if (installed === undefined) return [];
337
+ const roots: Array<ClaudeSkillRoot> = [];
338
+ // The CLI's process.cwd() resolves symlinks; registry projectPath values remain lexical.
339
+ const workspace =
340
+ cwd === undefined
341
+ ? undefined
342
+ : yield* fileSystem.realPath(cwd).pipe(Effect.orElseSucceed(() => path.resolve(cwd)));
343
+ const repositoryRoot =
344
+ workspace === undefined ? undefined : yield* findPluginRepositoryRoot(workspace);
345
+
346
+ for (const [key, entries] of Object.entries(installed.plugins).sort()) {
347
+ if (enabledPlugins.get(key) !== true) continue;
348
+ const applicable = yield* Effect.filter(
349
+ entries.flatMap((entry) => Option.toArray(decodeInstalledPlugin(entry))),
350
+ (record) =>
351
+ Effect.gen(function* () {
352
+ if (record.scope === "user" || record.scope === "managed") return true;
353
+ if (record.projectPath === undefined || workspace === undefined) return false;
354
+ if (path.resolve(record.projectPath) === workspace) return true;
355
+ return (
356
+ repositoryRoot !== undefined &&
357
+ (yield* findPluginRepositoryRoot(record.projectPath)) === repositoryRoot
358
+ );
359
+ }),
360
+ );
361
+ // The native loader keeps registry order, preferring the first install that exists.
362
+ const existing = yield* Effect.findFirst(applicable, (record) =>
363
+ fileSystem
364
+ .exists(path.resolve(cwd ?? ".", record.installPath))
365
+ .pipe(Effect.orElseSucceed(() => false)),
366
+ );
367
+ const install = Option.getOrElse(existing, () => applicable[0]);
368
+ if (!install) continue;
369
+ const scope = install.scope === "user" || install.scope === "managed" ? "user" : "project";
370
+ const installPath = path.resolve(cwd ?? ".", install.installPath);
371
+ const manifest = yield* fileSystem
372
+ .readFileString(path.join(installPath, ".claude-plugin", "plugin.json"))
373
+ .pipe(
374
+ Effect.flatMap(Schema.decodeUnknownEffect(PluginManifest)),
375
+ Effect.orElseSucceed(() => undefined),
376
+ );
377
+ const prefix = manifest?.name ?? key.split("@")[0];
378
+ if (!prefix) continue;
379
+
380
+ const defaultDirectory = path.join(installPath, "skills");
381
+ const hasDefaultDirectory = yield* fileSystem
382
+ .exists(defaultDirectory)
383
+ .pipe(Effect.orElseSucceed(() => false));
384
+ if (hasDefaultDirectory) roots.push({ directory: defaultDirectory, scope, prefix });
385
+ const declared = manifest?.skills;
386
+ if (declared === undefined && !hasDefaultDirectory) {
387
+ const hasRootSkill = yield* fileSystem
388
+ .exists(path.join(installPath, "SKILL.md"))
389
+ .pipe(Effect.orElseSucceed(() => false));
390
+ if (hasRootSkill) roots.push({ directory: installPath, scope, prefix });
391
+ }
392
+
393
+ const canonicalInstallPath = yield* fileSystem
394
+ .realPath(installPath)
395
+ .pipe(Effect.orElseSucceed(() => undefined));
396
+ for (const relative of typeof declared === "string" ? [declared] : (declared ?? [])) {
397
+ const directory = path.resolve(installPath, relative);
398
+ if (!isInsideDirectory(path, installPath, directory) || canonicalInstallPath === undefined) {
399
+ continue;
400
+ }
401
+ const canonicalDirectory = yield* fileSystem
402
+ .realPath(directory)
403
+ .pipe(Effect.orElseSucceed(() => undefined));
404
+ // The native loader rejects manifest roots that escape through a symlink, too.
405
+ if (
406
+ canonicalDirectory !== undefined &&
407
+ isInsideDirectory(path, canonicalInstallPath, canonicalDirectory)
408
+ ) {
409
+ roots.push({ directory, scope, prefix });
410
+ }
411
+ }
412
+ }
413
+ return roots;
414
});
415
416
const resolveClaudeConfigDirPath = Effect.fn("resolveClaudeConfigDirPath")(function* (
@@ -275,11 +449,15 @@ export const discoverClaudeSkills = Effect.fn("discoverClaudeSkills")(function*
449
const fileSystem = yield* FileSystem.FileSystem;
450
const path = yield* Path.Path;
451
const configDirPath = yield* resolveClaudeConfigDirPath(config, environment ?? process.env, cwd);
278
- const skillOverrides = yield* readSkillOverrides(configDirPath, cwd, environment ?? process.env);
452
+ const { skillOverrides, enabledPlugins } = yield* readSkillSettings(
453
+ configDirPath,
454
+ cwd,
455
+ environment ?? process.env,
456
+ );
457
458
// Use the session's argument parser so discovery sees the same --add-dir value.
459
const additionalDirectory = parseCliArgs(config.launchArgs ?? "").flags["add-dir"];
282
- const roots: ReadonlyArray<{ directory: string; scope: ClaudeSkillScope }> = [
460
+ const roots: ReadonlyArray<ClaudeSkillRoot> = [
461
{ directory: path.join(configDirPath, "skills"), scope: "user" },
462
...(cwd ? [{ directory: path.join(cwd, ".claude", "skills"), scope: "project" as const }] : []),
463
...(additionalDirectory && (cwd || path.isAbsolute(additionalDirectory))
@@ -294,16 +472,31 @@ export const discoverClaudeSkills = Effect.fn("discoverClaudeSkills")(function*
472
},
473
]
474
: []),
475
+ ...(yield* discoverPluginSkillRoots(
476
+ configDirPath,
477
+ cwd,
478
+ enabledPlugins,
479
+ environment ?? process.env,
480
+ )),
481
];
482
483
const skillsByName = new Map<string, ServerProviderSkill>();
484
for (const root of roots) {
301
- const entries = yield* fileSystem
302
- .readDirectory(root.directory)
303
- .pipe(Effect.orElseSucceed((): ReadonlyArray<string> => []));
485
+ const singleSkill =
486
+ root.prefix !== undefined &&
487
+ (yield* fileSystem
488
+ .exists(path.join(root.directory, "SKILL.md"))
489
+ .pipe(Effect.orElseSucceed(() => false)));
490
+ const entries = singleSkill
491
+ ? [path.basename(root.directory)]
492
+ : yield* fileSystem
493
+ .readDirectory(root.directory)
494
+ .pipe(Effect.orElseSucceed((): ReadonlyArray<string> => []));
495
496
for (const entry of [...entries].sort()) {
306
- const skillPath = path.join(root.directory, entry, "SKILL.md");
497
+ const skillPath = singleSkill
498
+ ? path.join(root.directory, "SKILL.md")
499
+ : path.join(root.directory, entry, "SKILL.md");
500
const contents = yield* fileSystem
501
.readFileString(skillPath)
502
.pipe(Effect.orElseSucceed(() => undefined));
@@ -316,22 +509,26 @@ export const discoverClaudeSkills = Effect.fn("discoverClaudeSkills")(function*
509
continue;
510
}
511
319
- // Claude Code identifies a skill by its directory, not by the
320
- // frontmatter `name`: verified against the CLI, a skill in `probe-alias/`
321
- // declaring `name: probe-alias-frontmatter` is published as
322
- // `probe-alias`, and only `skillOverrides["probe-alias"]` switches it
323
- // off. Keying off the frontmatter name would report a command that does
324
- // not exist and miss the override that disables it.
325
- const name = entry.trim();
326
- if (!name) {
327
- continue;
512
+ const directoryName = entry.trim();
513
+ if (!directoryName) continue;
514
+ let name = directoryName;
515
+ if (root.prefix) {
516
+ // Native folder skills use their folder; only a single SKILL.md uses its name field.
517
+ const declaredName = singleSkill && frontmatter.kind === "parsed" ? frontmatter.name : "";
518
+ const unprefixedName = declaredName?.startsWith(`${root.prefix}:`)
519
+ ? declaredName.slice(root.prefix.length + 1)
520
+ : declaredName;
521
+ name = `${root.prefix}:${(unprefixedName || entry).replace(/[^a-zA-Z0-9_-]/g, "-")}`;
522
+ // Advertise only exact native names the shared composer grammar can invoke.
523
+ const [mention] = `$${name}`.matchAll(SKILL_MENTION_PATTERN);
524
+ if (mention?.[2] !== name) continue;
525
}
526
527
if (skillsByName.has(name)) {
528
continue;
529
}
530
334
- const override = skillOverrides.get(name);
531
+ const override = root.prefix ? undefined : skillOverrides.get(name);
532
const userInvocationOnly =
533
(frontmatter.kind === "parsed" && frontmatter.userInvocationOnly === true) ||
534
override?.userInvocationOnly === true;
docs/user/providers-claude.md
+2
-1
@@ -71,7 +71,8 @@ Claude skills come from the config directory's `skills` folder and the project's
71
`.claude/skills` folder. If both define the same name, the config-directory copy
72
wins. Skills disabled in Claude's settings do not appear in the composer.
73
74
-Use `$` in the composer to select a skill. Skills marked `disable-model-invocation`
74
+Use `$` in the composer to select a skill. Enabled installed Claude plugins also
75
+contribute skills under names such as `plugin:review`. Skills marked `disable-model-invocation`
76
can still be started by you. Invoke those one per message: Claude directly runs
77
only the last named skill and may try to start earlier ones through its Skill
78
tool, which refuses skills reserved for manual invocation.