Skip to content

Commit 180e8aa

Browse files
committed
fix(claude): resolve skill name collisions the way Claude Code does
Discovery listed the user config dir first and let later roots overwrite it, so a project skill of the same name replaced the user one. Claude Code resolves the opposite way, which meant the snapshot could attach a project skill's invocation metadata to a command that runs the user skill. Measured against Claude Code 2.1.250 with the same skill name in both scopes and different bodies: the user copy is the one that runs. Roots are now listed highest precedence first and the first hit for a name wins. Model: Claude Opus 5 via Claude Code.
1 parent c3962ef commit 180e8aa

3 files changed

Lines changed: 29 additions & 20 deletions

File tree

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

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ it.layer(NodeServices.layer)("discoverClaudeSkills", (it) => {
9494
}),
9595
);
9696

97-
it.effect("prefers workspace .claude skills on three-way name collisions", () =>
97+
it.effect("prefers user skills on three-way name collisions", () =>
9898
Effect.gen(function* () {
9999
const fs = yield* FileSystem.FileSystem;
100100
const path = yield* Path.Path;
@@ -123,16 +123,16 @@ it.layer(NodeServices.layer)("discoverClaudeSkills", (it) => {
123123
assert.deepEqual(skills, [
124124
{
125125
name: "deploy",
126-
path: path.join(workspace, ".claude", "skills", "deploy", "SKILL.md"),
126+
path: path.join(configDir, "skills", "deploy", "SKILL.md"),
127127
enabled: true,
128-
scope: "project",
129-
description: "Claude deploy.",
128+
scope: "user",
129+
description: "User deploy.",
130130
},
131131
]);
132132
}),
133133
);
134134

135-
it.effect("prefers workspace .agents skills over user skills on name collisions", () =>
135+
it.effect("prefers user skills over workspace .agents skills on name collisions", () =>
136136
Effect.gen(function* () {
137137
const fs = yield* FileSystem.FileSystem;
138138
const path = yield* Path.Path;
@@ -156,16 +156,16 @@ it.layer(NodeServices.layer)("discoverClaudeSkills", (it) => {
156156
assert.deepEqual(skills, [
157157
{
158158
name: "deploy",
159-
path: path.join(workspace, ".agents", "skills", "deploy", "SKILL.md"),
159+
path: path.join(configDir, "skills", "deploy", "SKILL.md"),
160160
enabled: true,
161-
scope: "project",
162-
description: "Agents deploy.",
161+
scope: "user",
162+
description: "User deploy.",
163163
},
164164
]);
165165
}),
166166
);
167167

168-
it.effect("prefers project skills over user skills on name collisions", () =>
168+
it.effect("prefers user skills over project skills on name collisions", () =>
169169
Effect.gen(function* () {
170170
const fs = yield* FileSystem.FileSystem;
171171
const path = yield* Path.Path;
@@ -187,8 +187,8 @@ it.layer(NodeServices.layer)("discoverClaudeSkills", (it) => {
187187
const skills = yield* discoverClaudeSkills({ homePath: configDir }, workspace);
188188

189189
assert.equal(skills.length, 1);
190-
assert.equal(skills[0]?.scope, "project");
191-
assert.equal(skills[0]?.description, "Project deploy.");
190+
assert.equal(skills[0]?.scope, "user");
191+
assert.equal(skills[0]?.description, "User deploy.");
192192
}),
193193
);
194194

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

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -251,11 +251,13 @@ const resolveClaudeConfigDirPath = Effect.fn("resolveClaudeConfigDirPath")(funct
251251

252252
/**
253253
* Enumerate Claude Code skills from the user config dir, workspace
254-
* `.agents/skills`, and workspace `.claude/skills`, in that order. Discovery
255-
* is best-effort: unreadable roots and malformed skill entries are skipped so
256-
* a broken skill never degrades the provider snapshot. On name collisions,
257-
* later roots win: `.agents` beats user and `.claude` beats `.agents`, matching
258-
* Claude Code's resolution.
254+
* `.claude/skills`, and workspace `.agents/skills`. Discovery is best-effort:
255+
* unreadable roots and malformed skill entries are skipped so a broken skill
256+
* never degrades the provider snapshot. Roots are listed highest precedence
257+
* first and the first hit for a name wins, matching Claude Code: verified
258+
* against the CLI with the same skill name in both scopes, the user copy is
259+
* the one that runs. Reporting the project copy instead would attach its
260+
* invocation metadata to a command Claude Code resolves elsewhere.
259261
*/
260262
export const discoverClaudeSkills = Effect.fn("discoverClaudeSkills")(function* (
261263
config: Pick<ClaudeSettings, "homePath">,
@@ -271,8 +273,8 @@ export const discoverClaudeSkills = Effect.fn("discoverClaudeSkills")(function*
271273
{ directory: path.join(configDirPath, "skills"), scope: "user" },
272274
...(cwd
273275
? [
274-
{ directory: path.join(cwd, ".agents", "skills"), scope: "project" as const },
275276
{ directory: path.join(cwd, ".claude", "skills"), scope: "project" as const },
277+
{ directory: path.join(cwd, ".agents", "skills"), scope: "project" as const },
276278
]
277279
: []),
278280
];
@@ -311,6 +313,12 @@ export const discoverClaudeSkills = Effect.fn("discoverClaudeSkills")(function*
311313
continue;
312314
}
313315

316+
// First root wins, so a later root never displaces a higher-precedence
317+
// skill of the same name.
318+
if (skillsByName.has(name)) {
319+
continue;
320+
}
321+
314322
const override = skillOverrides.get(name);
315323
const userInvocationOnly =
316324
(frontmatter.kind === "parsed" && frontmatter.userInvocationOnly === true) ||

‎docs/user/providers-claude.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,10 +48,11 @@ 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, then
52-
`<workspace>/.agents/skills`, then `<workspace>/.claude/skills`.
51+
T3 Code looks for Claude skills in the Claude config directory's `skills` folder,
52+
`<workspace>/.claude/skills`, and `<workspace>/.agents/skills`.
5353

54-
If the same skill name exists in more than one folder, the later folder wins.
54+
If the same skill name exists in more than one folder, the one in the Claude config directory
55+
wins, the same way Claude Code resolves it.
5556

5657
A skill you have switched off in Claude Code is left out of both menus.
5758

0 commit comments

Comments
 (0)