Skip to content

Commit f3dd65d

Browse files
committed
feat: add deterministic skill discovery paths and fallback
1 parent 6d31c3b commit f3dd65d

2 files changed

Lines changed: 384 additions & 0 deletions

File tree

‎src/skills/discovery.ts‎

Lines changed: 280 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,280 @@
1+
import fs from "node:fs";
2+
import os from "node:os";
3+
import path from "node:path";
4+
import { parseSkillMarkdown, SkillParseError } from "./skill";
5+
6+
export type DiscoveryWarning = {
7+
path: string;
8+
message: string;
9+
field?: string;
10+
};
11+
12+
export type DiscoveredSkill = {
13+
name: string;
14+
description: string;
15+
path: string;
16+
source: "standard" | "agent" | "fallback";
17+
};
18+
19+
export type DiscoverSkillsOptions = {
20+
cwd?: string;
21+
homeDir?: string;
22+
verbose?: boolean;
23+
};
24+
25+
export type DiscoverSkillsResult = {
26+
skills: DiscoveredSkill[];
27+
warnings: DiscoveryWarning[];
28+
usedFallback: boolean;
29+
};
30+
31+
const STANDARD_SKILL_DIRS = [
32+
".",
33+
"skills",
34+
"skills/.curated",
35+
"skills/.experimental",
36+
"skills/.system",
37+
] as const;
38+
39+
const KNOWN_AGENT_SKILL_DIRS = [
40+
".claude/skills",
41+
".codex/skills",
42+
".opencode/skills",
43+
".cursor/skills",
44+
".windsurf/skills",
45+
] as const;
46+
47+
const FALLBACK_IGNORED_DIRS = new Set([
48+
".git",
49+
"node_modules",
50+
"dist",
51+
".worktrees",
52+
"worktrees",
53+
]);
54+
55+
export function discoverSkills(options: DiscoverSkillsOptions = {}): DiscoverSkillsResult {
56+
const cwd = path.resolve(options.cwd ?? process.cwd());
57+
const homeDir = path.resolve(options.homeDir ?? os.homedir());
58+
const warnings: DiscoveryWarning[] = [];
59+
const skills: DiscoveredSkill[] = [];
60+
const seenCanonicalPaths = new Set<string>();
61+
const seenNames = new Set<string>();
62+
63+
const standardRoots = STANDARD_SKILL_DIRS
64+
.map((relativePath) => path.resolve(cwd, relativePath))
65+
.filter(isDirectory)
66+
.sort((a, b) => a.localeCompare(b));
67+
68+
let standardSkillCount = 0;
69+
let standardCandidateCount = 0;
70+
for (const root of standardRoots) {
71+
const result = collectFromRoot({
72+
root,
73+
source: "standard",
74+
verbose: options.verbose === true,
75+
skills,
76+
warnings,
77+
seenCanonicalPaths,
78+
seenNames,
79+
});
80+
standardSkillCount += result.discoveredCount;
81+
standardCandidateCount += result.candidateCount;
82+
}
83+
84+
const agentRoots = collectAgentRoots(cwd, homeDir);
85+
let agentCandidateCount = 0;
86+
for (const root of agentRoots) {
87+
const result = collectFromRoot({
88+
root,
89+
source: "agent",
90+
verbose: options.verbose === true,
91+
skills,
92+
warnings,
93+
seenCanonicalPaths,
94+
seenNames,
95+
});
96+
agentCandidateCount += result.candidateCount;
97+
}
98+
99+
let usedFallback = false;
100+
if (standardCandidateCount === 0 && standardSkillCount === 0 && agentCandidateCount === 0) {
101+
usedFallback = true;
102+
103+
// Fallback is intentionally broad and only runs when standard locations are empty.
104+
for (const skillFile of findSkillFilesRecursively(cwd)) {
105+
const skillDir = path.dirname(skillFile);
106+
collectFromSkillDir({
107+
skillDir,
108+
source: "fallback",
109+
verbose: options.verbose === true,
110+
skills,
111+
warnings,
112+
seenCanonicalPaths,
113+
seenNames,
114+
});
115+
}
116+
}
117+
118+
skills.sort((left, right) => {
119+
const nameCompare = left.name.localeCompare(right.name);
120+
if (nameCompare !== 0) {
121+
return nameCompare;
122+
}
123+
124+
return left.path.localeCompare(right.path);
125+
});
126+
127+
return {
128+
skills,
129+
warnings,
130+
usedFallback,
131+
};
132+
}
133+
134+
type CollectContext = {
135+
source: DiscoveredSkill["source"];
136+
verbose: boolean;
137+
skills: DiscoveredSkill[];
138+
warnings: DiscoveryWarning[];
139+
seenCanonicalPaths: Set<string>;
140+
seenNames: Set<string>;
141+
};
142+
143+
function collectFromRoot(
144+
context: CollectContext & { root: string }
145+
): { discoveredCount: number; candidateCount: number } {
146+
const discoveredBefore = context.skills.length;
147+
let candidateCount = 0;
148+
const candidateDirs = new Set<string>([context.root, ...listChildDirectories(context.root)]);
149+
150+
for (const skillDir of [...candidateDirs].sort((a, b) => a.localeCompare(b))) {
151+
const hasSkillFile = collectFromSkillDir({
152+
...context,
153+
skillDir,
154+
});
155+
if (hasSkillFile) {
156+
candidateCount += 1;
157+
}
158+
}
159+
160+
return {
161+
discoveredCount: context.skills.length - discoveredBefore,
162+
candidateCount,
163+
};
164+
}
165+
166+
function collectFromSkillDir(context: CollectContext & { skillDir: string }): boolean {
167+
const skillFile = path.join(context.skillDir, "SKILL.md");
168+
if (!isFile(skillFile)) {
169+
return false;
170+
}
171+
172+
let parsed;
173+
try {
174+
parsed = parseSkillMarkdown(fs.readFileSync(skillFile, "utf8"), { path: skillFile });
175+
} catch (error) {
176+
if (context.verbose && error instanceof SkillParseError) {
177+
context.warnings.push({
178+
path: skillFile,
179+
message: error.message,
180+
field: error.field,
181+
});
182+
}
183+
184+
return true;
185+
}
186+
187+
const canonicalPath = toCanonicalPath(context.skillDir);
188+
if (context.seenCanonicalPaths.has(canonicalPath) || context.seenNames.has(parsed.frontmatter.name)) {
189+
return true;
190+
}
191+
192+
context.seenCanonicalPaths.add(canonicalPath);
193+
context.seenNames.add(parsed.frontmatter.name);
194+
context.skills.push({
195+
name: parsed.frontmatter.name,
196+
description: parsed.frontmatter.description,
197+
path: context.skillDir,
198+
source: context.source,
199+
});
200+
201+
return true;
202+
}
203+
204+
function collectAgentRoots(cwd: string, homeDir: string): string[] {
205+
const roots = new Set<string>();
206+
207+
for (const relativePath of KNOWN_AGENT_SKILL_DIRS) {
208+
roots.add(path.resolve(cwd, relativePath));
209+
roots.add(path.resolve(homeDir, relativePath));
210+
}
211+
212+
return [...roots].filter(isDirectory).sort((a, b) => a.localeCompare(b));
213+
}
214+
215+
function listChildDirectories(root: string): string[] {
216+
const directories: string[] = [];
217+
218+
for (const dirent of fs.readdirSync(root, { withFileTypes: true })) {
219+
const candidate = path.join(root, dirent.name);
220+
if (dirent.isDirectory() || (dirent.isSymbolicLink() && isDirectory(candidate))) {
221+
directories.push(candidate);
222+
}
223+
}
224+
225+
return directories;
226+
}
227+
228+
function findSkillFilesRecursively(root: string): string[] {
229+
const files: string[] = [];
230+
const stack = [root];
231+
232+
while (stack.length > 0) {
233+
const current = stack.pop();
234+
if (!current) {
235+
continue;
236+
}
237+
238+
for (const dirent of fs.readdirSync(current, { withFileTypes: true })) {
239+
const candidate = path.join(current, dirent.name);
240+
241+
if (dirent.isDirectory()) {
242+
if (FALLBACK_IGNORED_DIRS.has(dirent.name)) {
243+
continue;
244+
}
245+
stack.push(candidate);
246+
continue;
247+
}
248+
249+
if (dirent.name === "SKILL.md" && isFile(candidate)) {
250+
files.push(candidate);
251+
}
252+
}
253+
}
254+
255+
return files.sort((a, b) => a.localeCompare(b));
256+
}
257+
258+
function toCanonicalPath(directoryPath: string): string {
259+
try {
260+
return fs.realpathSync(directoryPath);
261+
} catch {
262+
return path.resolve(directoryPath);
263+
}
264+
}
265+
266+
function isDirectory(candidatePath: string): boolean {
267+
try {
268+
return fs.statSync(candidatePath).isDirectory();
269+
} catch {
270+
return false;
271+
}
272+
}
273+
274+
function isFile(candidatePath: string): boolean {
275+
try {
276+
return fs.statSync(candidatePath).isFile();
277+
} catch {
278+
return false;
279+
}
280+
}

‎tests/skills/discovery.test.ts‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
import fs from "node:fs";
2+
import os from "node:os";
3+
import path from "node:path";
4+
import { afterEach, describe, expect, test } from "vitest";
5+
import { discoverSkills } from "../../src/skills/discovery";
6+
7+
const tempDirs: string[] = [];
8+
9+
function makeTempDir(prefix: string): string {
10+
const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
11+
tempDirs.push(dir);
12+
return dir;
13+
}
14+
15+
function createSkill(skillDir: string, name = path.basename(skillDir), description?: string): void {
16+
fs.mkdirSync(skillDir, { recursive: true });
17+
fs.writeFileSync(
18+
path.join(skillDir, "SKILL.md"),
19+
`---\nname: ${name}\ndescription: ${description ?? `${name} description`}\n---\n\n# ${name}\n\nBody\n`
20+
);
21+
}
22+
23+
afterEach(() => {
24+
for (const dir of tempDirs.splice(0)) {
25+
fs.rmSync(dir, { recursive: true, force: true });
26+
}
27+
});
28+
29+
describe("discoverSkills", () => {
30+
test("discovers skills from standard project locations deterministically", () => {
31+
const cwd = makeTempDir("skillet-discovery-");
32+
const homeDir = path.join(cwd, "home");
33+
34+
createSkill(path.join(cwd, "skills", "zeta"));
35+
createSkill(path.join(cwd, "skills", ".curated", "alpha"));
36+
37+
const result = discoverSkills({ cwd, homeDir });
38+
39+
expect(result.skills.map((skill) => skill.name)).toEqual(["alpha", "zeta"]);
40+
expect(result.usedFallback).toBe(false);
41+
});
42+
43+
test("discovers skills in known agent directories", () => {
44+
const cwd = makeTempDir("skillet-discovery-");
45+
const homeDir = path.join(cwd, "home");
46+
47+
createSkill(path.join(homeDir, ".codex", "skills", "agent-skill"));
48+
49+
const result = discoverSkills({ cwd, homeDir });
50+
51+
expect(result.skills.map((skill) => skill.name)).toContain("agent-skill");
52+
expect(result.usedFallback).toBe(false);
53+
});
54+
55+
test("dedupes duplicate discoveries by canonical path and name", () => {
56+
const cwd = makeTempDir("skillet-discovery-");
57+
const homeDir = path.join(cwd, "home");
58+
const canonicalSkillPath = path.join(cwd, "skills", "dupe");
59+
createSkill(canonicalSkillPath);
60+
61+
const agentSkillsDir = path.join(cwd, ".codex", "skills");
62+
fs.mkdirSync(agentSkillsDir, { recursive: true });
63+
fs.symlinkSync(canonicalSkillPath, path.join(agentSkillsDir, "dupe-link"), "dir");
64+
65+
const result = discoverSkills({ cwd, homeDir });
66+
67+
expect(result.skills.filter((skill) => skill.name === "dupe")).toHaveLength(1);
68+
});
69+
70+
test("skips invalid SKILL.md and reports warning only in verbose mode", () => {
71+
const cwd = makeTempDir("skillet-discovery-");
72+
const homeDir = path.join(cwd, "home");
73+
const invalidDir = path.join(cwd, "skills", "broken");
74+
75+
fs.mkdirSync(invalidDir, { recursive: true });
76+
fs.writeFileSync(path.join(invalidDir, "SKILL.md"), "# broken");
77+
78+
const quietResult = discoverSkills({ cwd, homeDir, verbose: false });
79+
const verboseResult = discoverSkills({ cwd, homeDir, verbose: true });
80+
81+
expect(quietResult.skills).toHaveLength(0);
82+
expect(quietResult.warnings).toHaveLength(0);
83+
expect(verboseResult.warnings).toHaveLength(1);
84+
expect(verboseResult.warnings[0]?.path).toContain(path.join("skills", "broken", "SKILL.md"));
85+
});
86+
87+
test("uses recursive fallback only when standard locations are empty", () => {
88+
const cwd = makeTempDir("skillet-discovery-");
89+
const homeDir = path.join(cwd, "home");
90+
91+
createSkill(path.join(cwd, "custom", "nested", "fallback-skill"));
92+
93+
const fallbackResult = discoverSkills({ cwd, homeDir });
94+
expect(fallbackResult.skills.map((skill) => skill.name)).toContain("fallback-skill");
95+
expect(fallbackResult.usedFallback).toBe(true);
96+
97+
createSkill(path.join(cwd, "skills", "primary-skill"));
98+
99+
const noFallbackResult = discoverSkills({ cwd, homeDir });
100+
expect(noFallbackResult.skills.map((skill) => skill.name)).toContain("primary-skill");
101+
expect(noFallbackResult.skills.map((skill) => skill.name)).not.toContain("fallback-skill");
102+
expect(noFallbackResult.usedFallback).toBe(false);
103+
});
104+
});

0 commit comments

Comments
 (0)