Orkas is an open-source (MIT), local-first AI team for your desktop: a Commander turns your goal into to-dos and coordinates 16 built-in specialist agents plus Claude Code, Codex, OpenCode, OpenClaw and Hermes, with projects, scheduled automations and connectors. Free app for macOS & Windows; built-in models or your own keys.
JavaScript agent-collaborationagent-harnessagent-orchestrationagent-teamagent-workflowai-assistantai-automationai-employeeai-productivityai-teamai-workflowautonomous-agentsclaude-code-guiclaude-coworkdesktop-agentlocal-firstmulti-agentmulti-agent-systemself-evolving-agentstask-automation
import { describe, it, expect, beforeEach, afterEach } from "vitest";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { SkillLoader, parseFrontmatter } from "../src/skills/index.js";
let root: string;
function tmpRoot(): string {
return path.join(os.tmpdir(), `core-agent-skills-${Date.now()}-${Math.random().toString(36).slice(2)}`);
}
function writeSkill(base: string, id: string, frontmatter: Record<string, string>, body = "body text"): void {
const dir = path.join(base, id);
fs.mkdirSync(dir, { recursive: true });
const fm = Object.entries(frontmatter).map(([k, v]) => `${k}: ${v}`).join("\n");
fs.writeFileSync(path.join(dir, "SKILL.md"), `---\n${fm}\n---\n\n${body}\n`, "utf-8");
}
describe("parseFrontmatter", () => {
it("parses a standard frontmatter block", () => {
const { data, body } = parseFrontmatter(
"---\nname: foo\ndescription: a short description\n---\n\nbody here\nline 2\n",
);
expect(data.name).toBe("foo");
expect(data.description).toBe("a short description");
expect(body.trim()).toBe("body here\nline 2");
});
it("handles description with colons and commas", () => {
const { data } = parseFrontmatter("---\ndescription: foo: bar, baz\n---\n");
expect(data.description).toBe("foo: bar, baz");
});
it("strips matching surrounding quotes", () => {
const { data } = parseFrontmatter('---\nname: "quoted name"\n---\n');
expect(data.name).toBe("quoted name");
});
it("returns body unchanged when no frontmatter", () => {
const { data, body } = parseFrontmatter("# heading\nhello\n");
expect(data).toEqual({});
expect(body).toBe("# heading\nhello\n");
});
it("treats unterminated frontmatter as body", () => {
const { data, body } = parseFrontmatter("---\nname: foo\n(no closing fence)");
expect(data).toEqual({});
expect(body).toContain("(no closing fence)");
});
it("reads a literal block scalar (description: |) instead of the bare indicator", () => {
const { data } = parseFrontmatter(
"---\nname: web\ndescription: |\n Capture a website. Use when: (1) a URL is given.\n---\n",
);
expect(data.name).toBe("web");
// Regression: previously parsed as the literal "|" with the body dropped.
expect(data.description).toBe("Capture a website. Use when: (1) a URL is given.");
});
it("preserves line breaks in a multi-line literal block scalar", () => {
const { data } = parseFrontmatter(
"---\ndescription: |\n line one\n line two\n---\n",
);
expect(data.description).toBe("line one\nline two");
});
it("folds a `>` block scalar onto a single line", () => {
const { data } = parseFrontmatter(
"---\ndescription: >\n folded line one\n folded line two\n---\n",
);
expect(data.description).toBe("folded line one folded line two");
});
it("tolerates chomping indicators and ends the block at a dedented key", () => {
const { data } = parseFrontmatter(
"---\ndescription: |-\n the description\nname: after-block\n---\n",
);
expect(data.description).toBe("the description");
expect(data.name).toBe("after-block");
});
});
describe("SkillLoader", () => {
beforeEach(() => {
root = tmpRoot();
fs.mkdirSync(root, { recursive: true });
});
afterEach(() => {
try { fs.rmSync(root, { recursive: true, force: true }); } catch { /* ignore */ }
});
it("returns empty list when no dirs exist", () => {
const loader = new SkillLoader({ dirs: [path.join(root, "does-not-exist")] });
expect(loader.list()).toEqual([]);
expect(loader.renderSystemPromptBlock()).toBe("");
});
it("discovers skills with frontmatter", () => {
const base = path.join(root, "skills");
// Legacy `description` field migrates to `description_en` (no CJK chars).
writeSkill(base, "alpha", { name: "alpha", description: "first skill" });
writeSkill(base, "beta", { name: "beta", description: "second skill" });
const loader = new SkillLoader({ dirs: [base] });
const list = loader.list();
expect(list.map((s) => s.id)).toEqual(["alpha", "beta"]);
expect(list[0].name).toBe("alpha"); // invariant: name === id
expect(list[0].description_en).toBe("first skill");
expect(list[0].description_zh).toBe("");
expect(list[0].source).toBe(base);
expect(list[0].skillFile.endsWith("SKILL.md")).toBe(true);
});
it("prefers the platform bilingual frontmatter pair over duplicate legacy sidecar descriptions", () => {
const base = path.join(root, "skills");
writeSkill(base, "platform", {
name: "platform",
description_zh: "平台中文",
description_en: "Platform English",
});
fs.writeFileSync(path.join(base, "platform", "_meta.json"), JSON.stringify({
descriptions: { zh: "旧中文", en: "Legacy English" },
}));
const [spec] = new SkillLoader({ dirs: [base] }).list();
expect(spec.description_zh).toBe("平台中文");
expect(spec.description_en).toBe("Platform English");
});
it("keeps sidecar localization as a compatibility fallback for a portable custom Skill", () => {
const base = path.join(root, "skills");
writeSkill(base, "custom", { name: "custom", description: "Portable English" });
fs.writeFileSync(path.join(base, "custom", "_meta.json"), JSON.stringify({
descriptions: { zh: "自定义中文", en: "Localized English" },
}));
const [spec] = new SkillLoader({ dirs: [base] }).list();
expect(spec.description_zh).toBe("自定义中文");
expect(spec.description_en).toBe("Localized English");
});
it("parses the `ownerAgent` tag; absent/blank → undefined (agent-private gating)", () => {
const base = path.join(root, "skills");
writeSkill(base, "owned", { name: "owned", description: "private", ownerAgent: "video-studio" });
writeSkill(base, "shared", { name: "shared", description: "public" });
writeSkill(base, "blank", { name: "blank", description: "public", ownerAgent: " " });
const byId = new Map(new SkillLoader({ dirs: [base] }).list().map((s) => [s.id, s]));
expect(byId.get("owned")!.ownerAgent).toBe("video-studio");
// Absent and whitespace-only both normalize to undefined → treated as a
// normal shared skill by the prompt/UI owner filters.
expect(byId.get("shared")!.ownerAgent).toBeUndefined();
expect(byId.get("blank")!.ownerAgent).toBeUndefined();
});
it("falls back to directory name when frontmatter is missing", () => {
const base = path.join(root, "skills");
const d = path.join(base, "no-fm");
fs.mkdirSync(d, { recursive: true });
fs.writeFileSync(path.join(d, "SKILL.md"), "# Just a heading, no frontmatter\n");
const loader = new SkillLoader({ dirs: [base] });
const list = loader.list();
expect(list).toHaveLength(1);
expect(list[0].id).toBe("no-fm");
expect(list[0].name).toBe("no-fm");
expect(list[0].description_zh).toBe("");
expect(list[0].description_en).toBe("");
});
it("follows symlinked skill dirs (e.g. ~/.claude/skills entries)", () => {
// Real skill bodies live in a shared store; the scanned root holds
// symlinks into it — the common `~/.claude/skills` layout.
const store = path.join(root, "store");
writeSkill(store, "linked", { name: "linked", description: "via symlink" });
const base = path.join(root, "skills");
fs.mkdirSync(base, { recursive: true });
fs.symlinkSync(path.join(store, "linked"), path.join(base, "linked"), "dir");
const loader = new SkillLoader({ dirs: [base] });
const list = loader.list();
expect(list.map((s) => s.id)).toEqual(["linked"]);
expect(list[0].description_en).toBe("via symlink");
});
it("ignores symlinks that don't resolve to a directory", () => {
const base = path.join(root, "skills");
writeSkill(base, "real", { name: "real" });
// A dangling symlink and a symlink to a plain file must not be listed.
fs.symlinkSync(path.join(root, "nowhere"), path.join(base, "dangling"), "dir");
fs.writeFileSync(path.join(root, "afile"), "x");
fs.symlinkSync(path.join(root, "afile"), path.join(base, "tofile"));
const loader = new SkillLoader({ dirs: [base] });
expect(loader.list().map((s) => s.id)).toEqual(["real"]);
});
it("skips dirs without SKILL.md", () => {
const base = path.join(root, "skills");
writeSkill(base, "real", { name: "real" });
fs.mkdirSync(path.join(base, "empty"), { recursive: true });
const loader = new SkillLoader({ dirs: [base] });
expect(loader.list().map((s) => s.id)).toEqual(["real"]);
});
it("first dir wins on id collision", () => {
const customDir = path.join(root, "custom");
const builtinDir = path.join(root, "builtin");
// Descriptions carry the custom-vs-builtin marker since name==id now.
writeSkill(customDir, "shared", { name: "shared", description: "custom-wins" });
writeSkill(builtinDir, "shared", { name: "shared", description: "builtin-loses" });
writeSkill(builtinDir, "only-in-builtin", { name: "only-in-builtin", description: "extra" });
const loader = new SkillLoader({ dirs: [customDir, builtinDir] });
const list = loader.list();
const shared = list.find((s) => s.id === "shared")!;
// Legacy `description` migrates to `description_en` (English content).
expect(shared.description_en).toBe("custom-wins");
expect(shared.source).toBe(customDir);
expect(list.find((s) => s.id === "only-in-builtin")).toBeDefined();
});
it("caches an unchanged inventory and invalidate() forces re-scan", () => {
const base = path.join(root, "skills");
writeSkill(base, "one", { name: "One" });
const loader = new SkillLoader({ dirs: [base] });
const first = loader.list();
expect(first).toHaveLength(1);
// Second call returns the same array reference (cache hit).
const second = loader.list();
expect(second).toBe(first);
// Add another skill without touching mtime — cache still wins (expected).
writeSkill(base, "two", { name: "Two" });
// Depending on filesystem, mtime may not have changed; force invalidate.
loader.invalidate();
const third = loader.list();
expect(third.map((s) => s.id).sort()).toEqual(["one", "two"]);
});
it("refreshes an in-place SKILL.md edit even when the root mtime is unchanged", () => {
const base = path.join(root, "skills");
writeSkill(base, "one", { name: "One", description: "old route" });
const loader = new SkillLoader({ dirs: [base] });
const first = loader.list();
expect(first[0]?.description_en).toBe("old route");
const rootTimes = fs.statSync(base);
const skillFile = path.join(base, "one", "SKILL.md");
const skillTimes = fs.statSync(skillFile);
// Same-length rewrite plus restored mtime defeats a mtime+size cache. The
// loader's ctime/inode fingerprint must still observe the external edit.
writeSkill(base, "one", { name: "One", description: "new route" });
fs.utimesSync(skillFile, skillTimes.atime, skillTimes.mtime);
// Recreate the old failure condition explicitly: the root timestamp does
// not reveal an in-place child-file rewrite.
fs.utimesSync(base, rootTimes.atime, rootTimes.mtime);
const second = loader.list();
expect(second).not.toBe(first);
expect(second[0]?.description_en).toBe("new route");
});
it("refreshes an in-place description sidecar edit", () => {
const base = path.join(root, "skills");
writeSkill(base, "one", { name: "One" });
const sidecar = path.join(base, "one", "_meta.json");
fs.writeFileSync(sidecar, JSON.stringify({ descriptions: { en: "sidecar one" } }));
const loader = new SkillLoader({ dirs: [base] });
expect(loader.list()[0]?.description_en).toBe("sidecar one");
fs.writeFileSync(sidecar, JSON.stringify({ descriptions: { en: "sidecar two, externally updated" } }));
expect(loader.list()[0]?.description_en).toBe("sidecar two, externally updated");
});
it("renderSystemPromptBlock lists all skills with source marker", () => {
const customDir = path.join(root, "custom");
const builtinDir = path.join(root, "builtin");
writeSkill(customDir, "alpha", { name: "alpha", description: "alpha desc" });
writeSkill(builtinDir, "beta", { name: "beta", description: "beta desc" });
const loader = new SkillLoader({ dirs: [customDir, builtinDir] });
const block = loader.renderSystemPromptBlock();
expect(block).toContain("## Available skills");
// Each entry carries a `Source` tag (dir basename) so the LLM can pick
// the right path prefix without probing both roots. (Note: Orkas's
// production renderer in skill-registry.ts uses richer formatting with
// inline ROOT path headers; this default helper stays minimal and is
// only consumed by other hosts / by these tests.)
expect(block).toContain("**alpha** (Source: custom) — alpha desc");
expect(block).toContain("**beta** (Source: builtin) — beta desc");
// id must never be shown twice — the name==id invariant holds.
expect(block).not.toMatch(/\(`/);
});
it("parseSpec keeps frontmatter name distinct from dir id (id≠name invariant)", () => {
// The loader decouples id (= dir basename, used as `read_file` path
// component) from name (= frontmatter name, the LLM-facing display
// label). Marketplace installs deliberately let these diverge (dir is
// the 12-hex server_id, name is the authored human label).
const customDir = path.join(root, "custom");
writeSkill(customDir, "web-summary", { name: "WebSummaryLegacy", description: "x" });
const loader = new SkillLoader({ dirs: [customDir] });
const [spec] = loader.list();
expect(spec.id).toBe("web-summary");
expect(spec.name).toBe("WebSummaryLegacy"); // frontmatter is preserved verbatim
});
});