Skip to content

Commit 8f27b8e

Browse files
t3dotggclaude
andcommitted
fix(claude): validate skillOverrides and skill roots the way Claude Code does
Two discovery details did not match the CLI. Claude Code validates the whole skillOverrides map, so one unknown or boolean value makes it drop every override in that file; discovery applied the valid siblings. And Claude Code never loads `.agents/skills`, so a skill living only there was offered and dispatched to an `Unknown command` reply. Both verified against the CLI and matched. Co-Authored-By: Claude Fable 5.1 <[email protected]>
1 parent 082db59 commit 8f27b8e

3 files changed

Lines changed: 57 additions & 84 deletions

File tree

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

Lines changed: 22 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -66,14 +66,16 @@ it.layer(NodeServices.layer)("discoverClaudeSkills", (it) => {
6666
}),
6767
);
6868

69-
it.effect("discovers project skills from the workspace .agents directory", () =>
69+
it.effect("ignores .agents/skills, which Claude Code does not load", () =>
7070
Effect.gen(function* () {
7171
const fs = yield* FileSystem.FileSystem;
7272
const path = yield* Path.Path;
7373
const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-claude-skills-" });
7474
const configDir = path.join(tempDir, "claude-home");
7575
const workspace = path.join(tempDir, "workspace");
7676

77+
// Verified against the CLI: `/review` here is answered with
78+
// `Unknown command`, so offering it would dispatch a dead command.
7779
yield* writeSkill(
7880
path.join(workspace, ".agents", "skills"),
7981
"review",
@@ -82,19 +84,11 @@ it.layer(NodeServices.layer)("discoverClaudeSkills", (it) => {
8284

8385
const skills = yield* discoverClaudeSkills({ homePath: configDir }, workspace);
8486

85-
assert.deepEqual(skills, [
86-
{
87-
name: "review",
88-
path: path.join(workspace, ".agents", "skills", "review", "SKILL.md"),
89-
enabled: true,
90-
scope: "project",
91-
description: "Review the changes.",
92-
},
93-
]);
87+
assert.deepEqual(skills, []);
9488
}),
9589
);
9690

97-
it.effect("prefers user skills on three-way name collisions", () =>
91+
it.effect("prefers user skills on name collisions even with a stray .agents copy", () =>
9892
Effect.gen(function* () {
9993
const fs = yield* FileSystem.FileSystem;
10094
const path = yield* Path.Path;
@@ -132,39 +126,6 @@ it.layer(NodeServices.layer)("discoverClaudeSkills", (it) => {
132126
}),
133127
);
134128

135-
it.effect("prefers user skills over workspace .agents skills on name collisions", () =>
136-
Effect.gen(function* () {
137-
const fs = yield* FileSystem.FileSystem;
138-
const path = yield* Path.Path;
139-
const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-claude-skills-" });
140-
const configDir = path.join(tempDir, "claude-home");
141-
const workspace = path.join(tempDir, "workspace");
142-
143-
yield* writeSkill(
144-
path.join(configDir, "skills"),
145-
"deploy",
146-
["---", "name: deploy", "description: User deploy.", "---"].join("\n"),
147-
);
148-
yield* writeSkill(
149-
path.join(workspace, ".agents", "skills"),
150-
"deploy",
151-
["---", "name: deploy", "description: Agents deploy.", "---"].join("\n"),
152-
);
153-
154-
const skills = yield* discoverClaudeSkills({ homePath: configDir }, workspace);
155-
156-
assert.deepEqual(skills, [
157-
{
158-
name: "deploy",
159-
path: path.join(configDir, "skills", "deploy", "SKILL.md"),
160-
enabled: true,
161-
scope: "user",
162-
description: "User deploy.",
163-
},
164-
]);
165-
}),
166-
);
167-
168129
it.effect("prefers user skills over project skills on name collisions", () =>
169130
Effect.gen(function* () {
170131
const fs = yield* FileSystem.FileSystem;
@@ -418,28 +379,36 @@ it.layer(NodeServices.layer)("discoverClaudeSkills", (it) => {
418379
}),
419380
);
420381

421-
it.effect("keeps an unmodelled override value visible", () =>
382+
it.effect("drops every override in a file when one value is invalid, as Claude Code does", () =>
422383
Effect.gen(function* () {
423384
const fs = yield* FileSystem.FileSystem;
424385
const path = yield* Path.Path;
425386
const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-claude-skills-" });
426387
const configDir = path.join(tempDir, "claude-home");
427388

428-
yield* writeSkill(
429-
path.join(configDir, "skills"),
430-
"ask-matt",
431-
["---", "name: ask-matt", "---", "", "# Body"].join("\n"),
432-
);
389+
for (const name of ["unknown-mode", "boolean-false", "sibling-off"]) {
390+
yield* writeSkill(
391+
path.join(configDir, "skills"),
392+
name,
393+
["---", `name: ${name}`, "---", "", "# Body"].join("\n"),
394+
);
395+
}
396+
// Verified against the CLI: with an unknown string or a boolean in the
397+
// map, the valid "off" sibling is ignored too and every skill runs.
433398
yield* fs.writeFileString(
434399
path.join(configDir, "settings.json"),
435-
'{ "skillOverrides": { "ask-matt": "some-future-mode" } }',
400+
'{ "skillOverrides": { "unknown-mode": "some-future-mode", "boolean-false": false, "sibling-off": "off" } }',
436401
);
437402

438403
const skills = yield* discoverClaudeSkills({ homePath: configDir });
439404

440405
assert.deepEqual(
441-
skills.map((skill) => [skill.name, skill.enabled, skill.userInvocationOnly === true]),
442-
[["ask-matt", true, false]],
406+
skills.map((skill) => [skill.name, skill.enabled]),
407+
[
408+
["boolean-false", true],
409+
["sibling-off", true],
410+
["unknown-mode", true],
411+
],
443412
);
444413
}),
445414
);

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

Lines changed: 33 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
/**
22
* ClaudeSkills — filesystem discovery of Claude Code skills for the `$` picker.
33
*
4-
* Claude Code loads skills from `<config dir>/skills` (user scope), then
5-
* `<cwd>/.claude/skills` and `<cwd>/.agents/skills` (project scope), one
6-
* directory per skill with a `SKILL.md` carrying YAML frontmatter. The first
7-
* root wins on name collisions, so precedence is user, `.claude`, then
8-
* `.agents`, matching the CLI.
4+
* Claude Code loads skills from `<config dir>/skills` (user scope) and
5+
* `<cwd>/.claude/skills` (project scope), one directory per skill with a
6+
* `SKILL.md` carrying YAML frontmatter. The user root wins on name collisions,
7+
* matching the CLI. `.agents/skills` is a Codex location: verified against the
8+
* CLI, a skill that lives only there is answered with `Unknown command`, so it
9+
* is not scanned here.
910
* The Agent SDK init handshake surfaces skills only as slash commands without
1011
* their filesystem paths, so the provider snapshot scans the same locations
1112
* directly, mirroring how the Codex app-server reports its skills.
@@ -179,11 +180,19 @@ const findRepositoryRoot = Effect.fn("findRepositoryRoot")(function* (
179180
}
180181
});
181182

183+
/**
184+
* The four states Claude Code accepts. The CLI validates the whole map, not
185+
* each entry: verified against it, one entry with an unknown value (or a
186+
* boolean) makes it drop every override in that file, so this schema does the
187+
* same rather than applying the valid siblings the CLI ignores.
188+
*/
189+
const SkillOverrideValue = Schema.Literals(["on", "name-only", "user-invocable-only", "off"]);
190+
182191
// Lenient because these settings files are hand-edited and Claude Code itself
183192
// tolerates comments and trailing commas in them.
184193
const SkillOverrideSettings = fromLenientJson(
185194
Schema.Struct({
186-
skillOverrides: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
195+
skillOverrides: Schema.optional(Schema.Record(Schema.String, SkillOverrideValue)),
187196
}),
188197
);
189198
const decodeSkillOverrideSettings = Schema.decodeUnknownEffect(SkillOverrideSettings);
@@ -198,16 +207,16 @@ type SkillOverride = {
198207
readonly userInvocationOnly: boolean;
199208
};
200209

201-
function parseSkillOverride(value: unknown): SkillOverride {
202-
if (value === "off" || value === false) {
203-
return { enabled: false, userInvocationOnly: false };
204-
}
205-
if (value === "user-invocable-only") {
206-
return { enabled: true, userInvocationOnly: true };
210+
function parseSkillOverride(value: typeof SkillOverrideValue.Type): SkillOverride {
211+
switch (value) {
212+
case "off":
213+
return { enabled: false, userInvocationOnly: false };
214+
case "user-invocable-only":
215+
return { enabled: true, userInvocationOnly: true };
216+
case "on":
217+
case "name-only":
218+
return { enabled: true, userInvocationOnly: false };
207219
}
208-
// An unknown value means a newer Claude Code grew a mode we do not model
209-
// yet — leave the skill visible rather than guessing at it.
210-
return { enabled: true, userInvocationOnly: false };
211220
}
212221

213222
const readSkillOverrides = Effect.fn("readSkillOverrides")(function* (
@@ -287,14 +296,14 @@ const resolveClaudeConfigDirPath = Effect.fn("resolveClaudeConfigDirPath")(funct
287296
});
288297

289298
/**
290-
* Enumerate Claude Code skills from the user config dir, workspace
291-
* `.claude/skills`, and workspace `.agents/skills`. Discovery is best-effort:
292-
* unreadable roots and malformed skill entries are skipped so a broken skill
293-
* never degrades the provider snapshot. Roots are listed highest precedence
294-
* first and the first hit for a name wins, matching Claude Code: verified
295-
* against the CLI with the same skill name in both scopes, the user copy is
296-
* the one that runs. Reporting the project copy instead would attach its
297-
* invocation metadata to a command Claude Code resolves elsewhere.
299+
* Enumerate Claude Code skills from the user config dir and the workspace
300+
* `.claude/skills`. Discovery is best-effort: unreadable roots and malformed
301+
* skill entries are skipped so a broken skill never degrades the provider
302+
* snapshot. Roots are listed highest precedence first and the first hit for a
303+
* name wins, matching Claude Code: verified against the CLI with the same
304+
* skill name in both scopes, the user copy is the one that runs. Reporting the
305+
* project copy instead would attach its invocation metadata to a command
306+
* Claude Code resolves elsewhere.
298307
*/
299308
export const discoverClaudeSkills = Effect.fn("discoverClaudeSkills")(function* (
300309
config: Pick<ClaudeSettings, "homePath">,
@@ -308,12 +317,7 @@ export const discoverClaudeSkills = Effect.fn("discoverClaudeSkills")(function*
308317

309318
const roots: ReadonlyArray<{ directory: string; scope: ClaudeSkillScope }> = [
310319
{ directory: path.join(configDirPath, "skills"), scope: "user" },
311-
...(cwd
312-
? [
313-
{ directory: path.join(cwd, ".claude", "skills"), scope: "project" as const },
314-
{ directory: path.join(cwd, ".agents", "skills"), scope: "project" as const },
315-
]
316-
: []),
320+
...(cwd ? [{ directory: path.join(cwd, ".claude", "skills"), scope: "project" as const }] : []),
317321
];
318322

319323
const skillsByName = new Map<string, ServerProviderSkill>();

‎docs/user/providers-claude.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,8 +48,8 @@ Claude can show its own resume prompt when you continue an old session.
4848

4949
## Where Claude Skills Are Loaded
5050

51-
T3 Code looks for Claude skills in the Claude config directory's `skills` folder,
52-
`<workspace>/.claude/skills`, and `<workspace>/.agents/skills`.
51+
T3 Code looks for Claude skills in the Claude config directory's `skills` folder and
52+
`<workspace>/.claude/skills`, the two places Claude Code loads them from.
5353

5454
If the same skill name exists in more than one folder, the one in the Claude config directory
5555
wins, the same way Claude Code resolves it.

0 commit comments

Comments
 (0)