Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

fix(claude): discover repo-local .agents/skills in skill discovery (#5488)

Roshan Mhatread47d2347c69
diff --git a/apps/server/src/provider/Drivers/ClaudeSkills.test.ts b/apps/server/src/provider/Drivers/ClaudeSkills.test.ts
index 1ad843d75..60db1d0c5 100644
--- a/apps/server/src/provider/Drivers/ClaudeSkills.test.ts
+++ b/apps/server/src/provider/Drivers/ClaudeSkills.test.ts
@@ -66,6 +66,105 @@ it.layer(NodeServices.layer)("discoverClaudeSkills", (it) => {
}),
);
+ it.effect("discovers project skills from the workspace .agents directory", () =>
+ Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-claude-skills-" });
+ const configDir = path.join(tempDir, "claude-home");
+ const workspace = path.join(tempDir, "workspace");
+
+ yield* writeSkill(
+ path.join(workspace, ".agents", "skills"),
+ "review",
+ ["---", "name: review", "description: Review the changes.", "---"].join("\n"),
+ );
+
+ const skills = yield* discoverClaudeSkills({ homePath: configDir }, workspace);
+
+ assert.deepEqual(skills, [
+ {
+ name: "review",
+ path: path.join(workspace, ".agents", "skills", "review", "SKILL.md"),
+ enabled: true,
+ scope: "project",
+ description: "Review the changes.",
+ },
+ ]);
+ }),
+ );
+
+ it.effect("prefers workspace .claude skills on three-way name collisions", () =>
+ Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-claude-skills-" });
+ const configDir = path.join(tempDir, "claude-home");
+ const workspace = path.join(tempDir, "workspace");
+
+ yield* writeSkill(
+ path.join(configDir, "skills"),
+ "deploy",
+ ["---", "name: deploy", "description: User deploy.", "---"].join("\n"),
+ );
+ yield* writeSkill(
+ path.join(workspace, ".agents", "skills"),
+ "deploy",
+ ["---", "name: deploy", "description: Agents deploy.", "---"].join("\n"),
+ );
+ yield* writeSkill(
+ path.join(workspace, ".claude", "skills"),
+ "deploy",
+ ["---", "name: deploy", "description: Claude deploy.", "---"].join("\n"),
+ );
+
+ const skills = yield* discoverClaudeSkills({ homePath: configDir }, workspace);
+
+ assert.deepEqual(skills, [
+ {
+ name: "deploy",
+ path: path.join(workspace, ".claude", "skills", "deploy", "SKILL.md"),
+ enabled: true,
+ scope: "project",
+ description: "Claude deploy.",
+ },
+ ]);
+ }),
+ );
+
+ it.effect("prefers workspace .agents skills over user skills on name collisions", () =>
+ Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-claude-skills-" });
+ const configDir = path.join(tempDir, "claude-home");
+ const workspace = path.join(tempDir, "workspace");
+
+ yield* writeSkill(
+ path.join(configDir, "skills"),
+ "deploy",
+ ["---", "name: deploy", "description: User deploy.", "---"].join("\n"),
+ );
+ yield* writeSkill(
+ path.join(workspace, ".agents", "skills"),
+ "deploy",
+ ["---", "name: deploy", "description: Agents deploy.", "---"].join("\n"),
+ );
+
+ const skills = yield* discoverClaudeSkills({ homePath: configDir }, workspace);
+
+ assert.deepEqual(skills, [
+ {
+ name: "deploy",
+ path: path.join(workspace, ".agents", "skills", "deploy", "SKILL.md"),
+ enabled: true,
+ scope: "project",
+ description: "Agents deploy.",
+ },
+ ]);
+ }),
+ );
+
it.effect("prefers project skills over user skills on name collisions", () =>
Effect.gen(function* () {
const fs = yield* FileSystem.FileSystem;
diff --git a/apps/server/src/provider/Drivers/ClaudeSkills.ts b/apps/server/src/provider/Drivers/ClaudeSkills.ts
index 335c3d468..5c33fba0b 100644
--- a/apps/server/src/provider/Drivers/ClaudeSkills.ts
+++ b/apps/server/src/provider/Drivers/ClaudeSkills.ts
@@ -1,12 +1,13 @@
/**
* ClaudeSkills — filesystem discovery of Claude Code skills for the `$` picker.
*
- * Claude Code loads skills from `<config dir>/skills` (user scope) and
- * `<cwd>/.claude/skills` (project scope), one directory per skill with a
- * `SKILL.md` carrying YAML frontmatter. The Agent SDK init handshake surfaces
- * skills only as slash commands without their filesystem paths, so the
- * provider snapshot scans the same locations directly, mirroring how the
- * Codex app-server reports its skills.
+ * Claude Code loads skills from `<config dir>/skills` (user scope), then
+ * `<cwd>/.agents/skills` and `<cwd>/.claude/skills` (project scope), one
+ * directory per skill with a `SKILL.md` carrying YAML frontmatter. Later roots
+ * win on name collisions, so precedence is user, `.agents`, then `.claude`.
+ * The Agent SDK init handshake surfaces skills only as slash commands without
+ * their filesystem paths, so the provider snapshot scans the same locations
+ * directly, mirroring how the Codex app-server reports its skills.
*
* @module provider/Drivers/ClaudeSkills
*/
@@ -84,11 +85,12 @@ const resolveClaudeConfigDirPath = Effect.fn("resolveClaudeConfigDirPath")(funct
});
/**
- * Enumerate Claude Code skills from the user config dir and the workspace.
- * Discovery is best-effort: unreadable roots and malformed skill entries are
- * skipped so a broken skill never degrades the provider snapshot. On name
- * collisions the project-scoped skill wins, matching Claude Code's
- * most-specific-wins resolution.
+ * Enumerate Claude Code skills from the user config dir, workspace
+ * `.agents/skills`, and workspace `.claude/skills`, in that order. Discovery
+ * is best-effort: unreadable roots and malformed skill entries are skipped so
+ * a broken skill never degrades the provider snapshot. On name collisions,
+ * later roots win: `.agents` beats user and `.claude` beats `.agents`, matching
+ * Claude Code's resolution.
*/
export const discoverClaudeSkills = Effect.fn("discoverClaudeSkills")(function* (
config: Pick<ClaudeSettings, "homePath">,
@@ -101,7 +103,12 @@ export const discoverClaudeSkills = Effect.fn("discoverClaudeSkills")(function*
const roots: ReadonlyArray<{ directory: string; scope: ClaudeSkillScope }> = [
{ directory: path.join(configDirPath, "skills"), scope: "user" },
- ...(cwd ? [{ directory: path.join(cwd, ".claude", "skills"), scope: "project" as const }] : []),
+ ...(cwd
+ ? [
+ { directory: path.join(cwd, ".agents", "skills"), scope: "project" as const },
+ { directory: path.join(cwd, ".claude", "skills"), scope: "project" as const },
+ ]
+ : []),
];
const skillsByName = new Map<string, ServerProviderSkill>();
diff --git a/docs/user/providers-claude.md b/docs/user/providers-claude.md
index 79f1211cf..f9699388b 100644
--- a/docs/user/providers-claude.md
+++ b/docs/user/providers-claude.md
@@ -34,6 +34,13 @@ When you set this field, T3 Code points Claude Code at that directory with the
`CLAUDE_CONFIG_DIR` environment variable. It does not change `HOME`, so your system keychain and
the rest of your environment stay as they are.
+## Where Claude Skills Are Loaded
+
+T3 Code looks for Claude skills in the Claude config directory's `skills` folder, then
+`<workspace>/.agents/skills`, then `<workspace>/.claude/skills`.
+
+If the same skill name exists in more than one folder, the later folder wins.
+
## I Want Work And Personal Claude Accounts
Use a different Claude config directory for each account.