@@ -2,83 +2,200 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
22 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
33 import { tmpdir } from "node:os";
44 import { join } from "node:path";
5-import { loadSkills } from "./skills.ts";
5+import { loadSkillContent, loadSkills, loadSkillsIndex } from "./skills.ts";
6+import { terminal } from "./terminal-io.ts";
67
7-describe("loadSkills", () => {
8+const originalStdoutWrite = terminal.stdoutWrite.bind(terminal);
9+
10+describe("skills loader", () => {
811 let dir: string;
12+ let fakeHome: string;
13+ let stdout = "";
914
1015 beforeEach(() => {
1116 dir = mkdtempSync(join(tmpdir(), "mc-skills-test-"));
17+ fakeHome = mkdtempSync(join(tmpdir(), "mc-skills-home-test-"));
18+ stdout = "";
19+ terminal.stdoutWrite = (chunk: string) => {
20+ stdout += chunk;
21+ };
1222 });
1323
1424 afterEach(() => {
25+ terminal.stdoutWrite = originalStdoutWrite;
1526 rmSync(dir, { recursive: true, force: true });
27+ rmSync(fakeHome, { recursive: true, force: true });
1628 });
1729
18- function writeSkill(root: string, folderName: string, content: string): void {
19- const skillDir = join(root, ".agents", "skills", folderName);
30+ function writeSkill(
31+ root: string,
32+ conventionDir: ".agents" | ".claude",
33+ folderName: string,
34+ content: string,
35+ ): void {
36+ const skillDir = join(root, conventionDir, "skills", folderName);
2037 mkdirSync(skillDir, { recursive: true });
2138 writeFileSync(join(skillDir, "SKILL.md"), content);
2239 }
2340
24- test("returns empty map when no .agents/skills dir exists", () => {
25- expect(loadSkills(dir).size).toBe(0);
41+ test("returns empty map when no skills directories exist", () => {
42+ expect(loadSkillsIndex(dir, fakeHome).size).toBe(0);
2643 });
2744
28- test("loads a skill with name and description from frontmatter", () => {
45+ test("loads metadata from index and reads full content on demand", () => {
46+ const raw =
47+ "---\nname: test-skill\ndescription: Test description\n---\n\nDo the thing.";
48+ writeSkill(dir, ".agents", "test-skill", raw);
49+
50+ const index = loadSkillsIndex(dir, fakeHome);
51+ expect(index.get("test-skill")?.description).toBe("Test description");
52+ expect(index.get("test-skill")?.source).toBe("local");
53+ expect(loadSkillContent("test-skill", dir, fakeHome)?.content).toBe(raw);
54+ });
55+
56+ test("discovers skills from parent directories when cwd is nested", () => {
2957 writeSkill(
3058 dir,
31- "git-release",
32- "---\nname: git-release\ndescription: Create consistent releases\n---\n\n# Instructions\nUse conventional commits.",
59+ ".agents",
60+ "root-skill",
61+ "---\nname: root-skill\ndescription: Found via walk-up\n---\nBody",
3362 );
34- const skills = loadSkills(dir);
35- const skill = skills.get("git-release");
36- expect(skill?.name).toBe("git-release");
37- expect(skill?.description).toBe("Create consistent releases");
38- expect(skill?.content).toContain("Use conventional commits.");
39- expect(skill?.source).toBe("local");
40- });
63+ const nested = join(dir, "packages", "service", "src");
64+ mkdirSync(join(dir, ".git"), { recursive: true });
65+ mkdirSync(nested, { recursive: true });
4166
42- test("falls back to folder name when frontmatter has no name", () => {
43- writeSkill(dir, "my-skill", "---\ndescription: A skill\n---\nContent.");
44- const skills = loadSkills(dir);
45- // key is name from frontmatter or folder name
46- expect(skills.get("my-skill")?.name).toBe("my-skill");
67+ const index = loadSkillsIndex(nested, fakeHome);
68+ expect(index.get("root-skill")?.description).toBe("Found via walk-up");
4769 });
4870
49- test("falls back to name as description when frontmatter has none", () => {
50- writeSkill(dir, "no-desc", "---\nname: no-desc\n---\nContent.");
51- expect(loadSkills(dir).get("no-desc")?.description).toBe("no-desc");
71+ test("does not traverse past cwd when outside a git repository", () => {
72+ const nested = join(dir, "pkg", "src");
73+ mkdirSync(nested, { recursive: true });
74+ writeSkill(
75+ dir,
76+ ".agents",
77+ "parent-skill",
78+ "---\nname: parent-skill\ndescription: should not be discovered\n---\nBody",
79+ );
80+
81+ const index = loadSkillsIndex(nested, fakeHome);
82+ expect(index.has("parent-skill")).toBe(false);
5283 });
5384
54- test("skill content includes the raw SKILL.md text", () => {
55- const raw =
56- "---\nname: test-skill\ndescription: Test\n---\n\nDo the thing.";
57- writeSkill(dir, "test-skill", raw);
58- expect(loadSkills(dir).get("test-skill")?.content).toBe(raw);
85+ test("applies precedence: nearest local > ancestor local > global and .agents > .claude", () => {
86+ const nestedRoot = join(dir, "apps", "api");
87+ const cwd = join(nestedRoot, "src");
88+ mkdirSync(cwd, { recursive: true });
89+ mkdirSync(join(dir, ".git"), { recursive: true });
90+
91+ writeSkill(
92+ fakeHome,
93+ ".claude",
94+ "deploy",
95+ "---\nname: deploy\ndescription: global claude\n---\ncontent",
96+ );
97+ writeSkill(
98+ fakeHome,
99+ ".agents",
100+ "deploy",
101+ "---\nname: deploy\ndescription: global agents\n---\ncontent",
102+ );
103+ writeSkill(
104+ dir,
105+ ".claude",
106+ "deploy",
107+ "---\nname: deploy\ndescription: ancestor claude\n---\ncontent",
108+ );
109+ writeSkill(
110+ dir,
111+ ".agents",
112+ "deploy",
113+ "---\nname: deploy\ndescription: ancestor agents\n---\ncontent",
114+ );
115+ writeSkill(
116+ nestedRoot,
117+ ".claude",
118+ "deploy",
119+ "---\nname: deploy\ndescription: nearest claude\n---\ncontent",
120+ );
121+ writeSkill(
122+ nestedRoot,
123+ ".agents",
124+ "deploy",
125+ "---\nname: deploy\ndescription: nearest agents\n---\ncontent",
126+ );
127+
128+ const index = loadSkillsIndex(cwd, fakeHome);
129+ const deploy = index.get("deploy");
130+ expect(deploy?.description).toBe("nearest agents");
131+ expect(deploy?.source).toBe("local");
132+ expect(deploy?.rootPath).toBe(nestedRoot);
59133 });
60134
61- test("ignores entries without a SKILL.md", () => {
62- const skillDir = join(dir, ".agents", "skills", "empty-folder");
63- mkdirSync(skillDir, { recursive: true });
64- expect(loadSkills(dir).size).toBe(0);
135+ test("conflict warnings use frontmatter skill names, not folder names", () => {
136+ writeSkill(
137+ dir,
138+ ".claude",
139+ "claude-folder",
140+ "---\nname: same-skill\ndescription: from claude\n---\ncontent",
141+ );
142+ writeSkill(
143+ dir,
144+ ".agents",
145+ "agents-folder",
146+ "---\nname: same-skill\ndescription: from agents\n---\ncontent",
147+ );
148+
149+ loadSkillsIndex(dir, fakeHome);
150+ expect(stdout).toContain("conflicting skills in local .agents and .claude");
151+ expect(stdout).toContain("same-skill");
152+ expect(stdout).not.toContain("agents-folder");
153+ expect(stdout).not.toContain("claude-folder");
65154 });
66155
67- test("ignores non-directory entries in skills dir", () => {
68- const skillsDir = join(dir, ".agents", "skills");
69- mkdirSync(skillsDir, { recursive: true });
70- writeFileSync(join(skillsDir, "not-a-dir.md"), "stuff");
71- expect(loadSkills(dir).size).toBe(0);
156+ test("skips invalid skills but tolerates unknown frontmatter fields", () => {
157+ writeSkill(
158+ dir,
159+ ".agents",
160+ "missing-name",
161+ "---\ndescription: Missing name\n---\ncontent",
162+ );
163+ writeSkill(
164+ dir,
165+ ".agents",
166+ "missing-description",
167+ "---\nname: missing-description\n---\ncontent",
168+ );
169+ writeSkill(
170+ dir,
171+ ".agents",
172+ "bad-format",
173+ "---\nname: Bad_Name\ndescription: bad\n---\ncontent",
174+ );
175+ writeSkill(
176+ dir,
177+ ".agents",
178+ "valid-skill",
179+ "---\nname: valid-skill\ndescription: valid\nowner: team\n---\ncontent",
180+ );
181+
182+ const index = loadSkillsIndex(dir, fakeHome);
183+ expect(index.has("missing-name")).toBe(false);
184+ expect(index.has("missing-description")).toBe(false);
185+ expect(index.has("Bad_Name")).toBe(false);
186+ expect(index.get("valid-skill")?.description).toBe("valid");
72187 });
73188
74- test("local skill overrides global with same name", () => {
189+ test("compatibility loadSkills still returns full records", () => {
75190 writeSkill(
76191 dir,
77- "git-release",
78- "---\nname: git-release\ndescription: local version\n---\nLocal content.",
192+ ".agents",
193+ "compat-skill",
194+ "---\nname: compat-skill\ndescription: compat\n---\ncompat body",
79195 );
80- const skills = loadSkills(dir);
81- expect(skills.get("git-release")?.description).toBe("local version");
82- expect(skills.get("git-release")?.source).toBe("local");
196+
197+ const skills = loadSkills(dir, fakeHome);
198+ expect(skills.get("compat-skill")?.description).toBe("compat");
199+ expect(skills.get("compat-skill")?.content).toContain("compat body");
83200 });
84201 });