Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
/**
* The repo's committed skills go up to the workspace with its learnings, so
* the team page can show them. Only the working tree's `.claude/skills/`:
* never a skill kept on this machine, never one that points outside the repo,
* and only one git tracks: not an untracked or gitignored one.
*/
import { test } from "node:test";
import assert from "node:assert/strict";
import { createHash } from "node:crypto";
import { execFileSync } from "node:child_process";
import { mkdirSync, mkdtempSync, realpathSync, symlinkSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { BRAND_ENV } from "../src/brand.js";
import { learningsPayload } from "../src/cloud/workspace-sync.js";
import { writeNote } from "../src/notes/notes.js";
import { skillDirs } from "../src/skills/skills.js";
process.env.DO_NOT_TRACK = "1";
process.env[BRAND_ENV] = "trail";
process.env.TRAIL_HOME = mkdtempSync(join(tmpdir(), "skills-sync-home-"));
const sha = (t: string) => createHash("sha256").update(t).digest("hex");
const HOTFIX = `---
name: release-hotfix
description: Cut a hotfix release from a tagged commit
author: Anirudh
---
# Release a hotfix
1. Branch from the tag.
2. Cherry-pick the fix.
`;
const git = (dir: string, ...args: string[]) => execFileSync("git", args, { cwd: dir, stdio: "ignore" });
/** A git checkout with a commit, so HEAD reads. Skills go up only once git tracks them: call `track` after writing the ones expected to. */
function checkout(): string {
const dir = realpathSync(mkdtempSync(join(tmpdir(), "skills-sync-repo-")));
git(dir, "init", "-q", "-b", "main");
git(dir, "-c", "user.name=t", "-c", "[email protected]", "commit", "-q", "--allow-empty", "-m", "start");
return dir;
}
function track(dir: string): void {
git(dir, "add", "-A", "-f");
git(dir, "-c", "user.name=t", "-c", "[email protected]", "commit", "-q", "--allow-empty", "-m", "track");
}
function writeSkill(root: string, name: string, text: string): void {
mkdirSync(join(root, name), { recursive: true });
writeFileSync(join(root, name, "SKILL.md"), text);
}
const skillItems = (dir: string) => (learningsPayload(dir) ?? []).filter((l) => l.kind === "skill");
test("the repo's skill goes up as a skill learning, and a skill kept on this machine does not", () => {
const dir = checkout();
const dirs = skillDirs(dir);
writeSkill(dirs.repo, "release-hotfix", HOTFIX);
writeSkill(dirs.home, "my-private-habit", "---\ndescription: Only mine\n---\n\nSecret steps.\n");
track(dir);
const items = skillItems(dir);
assert.equal(items.length, 1);
const s = items[0]!;
assert.equal(s.path, ".claude/skills/release-hotfix/SKILL.md");
assert.equal(s.kind, "skill");
// SKILL.md's name titles it; its description is what it does and when.
assert.equal(s.title, "Release hotfix");
assert.equal(s.why, "Cut a hotfix release from a tagged commit");
assert.equal(s.body, "# Release a hotfix\n\n1. Branch from the tag.\n2. Cherry-pick the fix.");
assert.deepEqual(s.files, []);
assert.equal(s.hash, sha(JSON.stringify(["folder", HOTFIX, []])));
assert.equal(s.author, "Anirudh");
assert.equal(s.ref, "");
assert.deepEqual(s.touches, []);
assert.ok(!(learningsPayload(dir) ?? []).some((l) => l.path.includes("my-private-habit")));
});
test("a skill without a description is titled by its folder, and plain learnings carry no kind", () => {
const dir = checkout();
writeSkill(skillDirs(dir).repo, "pdf-coords", "---\nname: pdf-coords\n---\n\nUse points, not pixels.\n");
writeNote(dir, { title: "Keep payment retries at 4", body: "## Decided\nFour retries.", author: "Sam", date: "2026-10-07", touches: [] });
track(dir);
const [s] = skillItems(dir);
assert.equal(s!.title, "Pdf coords");
assert.equal(s!.why, "");
assert.equal(s!.author, "");
const learning = (learningsPayload(dir) ?? []).filter((l) => l.path.startsWith(".trail/learnings/"));
assert.equal(learning.length, 1, "the fixture's learning is in the payload");
assert.equal(learning[0]!.kind, undefined);
});
test("editing a skill changes its hash in the payload", () => {
const dir = checkout();
const repo = skillDirs(dir).repo;
writeSkill(repo, "release-hotfix", HOTFIX);
track(dir);
const before = skillItems(dir)[0]!;
writeSkill(repo, "release-hotfix", HOTFIX + "3. Tag the release.\n");
const after = skillItems(dir)[0]!;
assert.notEqual(before.hash, after.hash);
assert.match(after.body, /Tag the release/);
});
test("a SKILL.md that can't be parsed is skipped, and the others still go up", () => {
const dir = checkout();
const repo = skillDirs(dir).repo;
writeSkill(repo, "broken", "---\ndescription: [unclosed\n - : :\n---\n\nbody\n");
writeSkill(repo, "release-hotfix", HOTFIX);
track(dir);
const items = skillItems(dir);
assert.deepEqual(items.map((i) => i.path), [".claude/skills/release-hotfix/SKILL.md"]);
});
test("a skill folder that points outside the repo is skipped, one that points inside is kept", () => {
const dir = checkout();
const outside = mkdtempSync(join(tmpdir(), "skills-sync-outside-"));
writeSkill(outside, "stolen", "---\ndescription: Not in this repo\n---\n\nOutside text.\n");
const repo = skillDirs(dir).repo;
mkdirSync(repo, { recursive: true });
symlinkSync(join(outside, "stolen"), join(repo, "stolen"), "dir");
mkdirSync(join(repo, "viafile"), { recursive: true });
symlinkSync(join(outside, "stolen", "SKILL.md"), join(repo, "viafile", "SKILL.md"));
writeSkill(join(dir, ".agents", "skills"), "shared", "---\ndescription: Shared across agents\n---\n\nSteps.\n");
symlinkSync(join(dir, ".agents", "skills", "shared"), join(repo, "shared"), "dir");
track(dir);
assert.deepEqual(skillItems(dir).map((i) => i.path), [".claude/skills/shared/SKILL.md"]);
});
test("an untracked skill is not uploaded, and a tracked one is", () => {
const dir = checkout();
const repo = skillDirs(dir).repo;
writeSkill(repo, "release-hotfix", HOTFIX);
track(dir);
writeSkill(repo, "scratch-idea", "---\ndescription: Not committed\n---\n\nHalf-baked.\n");
assert.deepEqual(skillItems(dir).map((i) => i.path), [".claude/skills/release-hotfix/SKILL.md"]);
track(dir);
assert.deepEqual(skillItems(dir).map((i) => i.path), [".claude/skills/release-hotfix/SKILL.md", ".claude/skills/scratch-idea/SKILL.md"]);
});
test("a gitignored skill is not uploaded, unless it was force-added", () => {
const dir = checkout();
const repo = skillDirs(dir).repo;
writeFileSync(join(dir, ".gitignore"), ".claude/skills/ignored/\n.claude/skills/forced/\n");
writeSkill(repo, "release-hotfix", HOTFIX);
writeSkill(repo, "ignored", "---\ndescription: Ignored\n---\n\nKept out of git.\n");
writeSkill(repo, "forced", "---\ndescription: Forced in\n---\n\nTracked anyway.\n");
git(dir, "add", ".gitignore", ".claude/skills/release-hotfix");
git(dir, "add", "-f", ".claude/skills/forced");
assert.deepEqual(skillItems(dir).map((i) => i.path), [".claude/skills/forced/SKILL.md", ".claude/skills/release-hotfix/SKILL.md"]);
});
test("a checkout that isn't a git repo uploads no skills, and doesn't throw", () => {
const dir = mkdtempSync(join(tmpdir(), "skills-sync-nogit-"));
writeSkill(skillDirs(dir).repo, "release-hotfix", HOTFIX);
assert.deepEqual(skillItems(dir), []);
});
test("a SKILL.md over 256 KB is skipped", () => {
const dir = checkout();
const repo = skillDirs(dir).repo;
writeSkill(repo, "release-hotfix", HOTFIX);
writeSkill(repo, "huge", `---\ndescription: Too big\n---\n\n${"x".repeat(256 * 1024 + 1)}\n`);
track(dir);
assert.deepEqual(skillItems(dir).map((i) => i.path), [".claude/skills/release-hotfix/SKILL.md"]);
});
test("a skill goes up with its folder: what git tracks, text as text, the rest as base64", () => {
const dir = checkout();
const root = join(skillDirs(dir).repo, "fill-forms");
writeSkill(skillDirs(dir).repo, "fill-forms", "---\nname: fill-forms\ndescription: Fill PDF forms\n---\n\n1. Read references/forms.md\n2. Run scripts/fill.py\n");
mkdirSync(join(root, "references"), { recursive: true });
mkdirSync(join(root, "scripts"));
mkdirSync(join(root, "assets"));
mkdirSync(join(root, "node_modules", "x"), { recursive: true });
writeFileSync(join(root, "references", "forms.md"), "# Forms\nUse field names.\n");
writeFileSync(join(root, "scripts", "fill.py"), "print('ok')\n", { mode: 0o755 });
writeFileSync(join(root, "assets", "logo.png"), Buffer.from([0x89, 0x50, 0x4e, 0x47, 0, 1, 2]));
writeFileSync(join(root, "node_modules", "x", "index.js"), "junk");
track(dir);
// Written after the commit: untracked, so it stays here.
writeFileSync(join(root, "references", "draft.md"), "not yet");
// A link out of the repo is never followed.
const outside = realpathSync(mkdtempSync(join(tmpdir(), "skills-outside-")));
writeFileSync(join(outside, "secret.md"), "elsewhere");
symlinkSync(join(outside, "secret.md"), join(root, "references", "linked.md"));
git(dir, "add", "-f", ".");
git(dir, "-c", "user.name=t", "-c", "[email protected]", "commit", "-q", "-m", "link");
writeFileSync(join(root, "references", "draft.md"), "not yet");
git(dir, "rm", "-q", "--cached", ".claude/skills/fill-forms/references/draft.md");
const s = skillItems(dir)[0]!;
const files = Object.fromEntries((s.files ?? []).map((f) => [f.path, f]));
assert.deepEqual(Object.keys(files).sort(), ["assets/logo.png", "references/forms.md", "scripts/fill.py"]);
assert.equal(files["references/forms.md"]!.content, "# Forms\nUse field names.\n");
assert.equal(files["references/forms.md"]!.encoding, undefined);
// Windows has no executable bit to keep.
if (process.platform !== "win32") assert.equal(files["scripts/fill.py"]!.executable, true);
assert.equal(files["assets/logo.png"]!.encoding, "base64");
assert.deepEqual([...Buffer.from(files["assets/logo.png"]!.content, "base64")], [0x89, 0x50, 0x4e, 0x47, 0, 1, 2]);
// Any file changing sends the skill again.
const before = s.hash;
writeFileSync(join(root, "references", "forms.md"), "# Forms\nUse field ids.\n");
assert.notEqual(skillItems(dir)[0]!.hash, before);
});
test("a secret in one of a skill's files keeps the whole skill on this machine", () => {
const dir = checkout();
const root = join(skillDirs(dir).repo, "deploy");
writeSkill(skillDirs(dir).repo, "deploy", "---\nname: deploy\ndescription: Deploy\n---\n\n1. Run scripts/go.sh\n");
mkdirSync(join(root, "scripts"));
// Built in pieces so the test file itself holds no token.
writeFileSync(join(root, "scripts", "go.sh"), 'TOKEN="' + "EA" + "Ab1C2d3E4f5G6h7I8j9K0l1M2n3O4p5Q6rS7t8U9v0" + '"\n');
track(dir);
assert.equal(skillItems(dir).length, 0);
});