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
feat: a repo's skill goes up with its whole folder
Shrish Dwivedi0fc3ba3f727a
diff --git a/src/cloud/workspace-sync.ts b/src/cloud/workspace-sync.tsindex 36d26d57..d0f9bd1d 100644--- a/src/cloud/workspace-sync.ts+++ b/src/cloud/workspace-sync.ts@@ -25,6 +25,7 @@ import { createHash } from "node:crypto";import { execFileSync, spawn } from "node:child_process";import { existsSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync } from "node:fs";import { basename, join, relative, sep } from "node:path";+import { isUtf8 } from "node:buffer";import { graftCliPath } from "../claude/paths.js";import { readBranchCache, refreshBranches } from "../notes/branches.js";import { knownRepos, repoName, repoPlace, trailHome } from "../notes/home.js";@@ -37,7 +38,7 @@ import { matter } from "../util/front-matter.js";import { appendPrivateFile, ensurePrivateDir, PRIVATE_FILE_MODE, writePrivateFile } from "../util/private-file.js";import { cacheDir, readJson, writeJsonAtomic } from "../util/state.js";import { headLearnings } from "./head-learnings.js";-import { isError, postActivity, readCloud, uploadLearnings, type ActivityEvent, type ApiError, type Cloud, type UploadedLearning } from "./workspace.js";+import { isError, postActivity, readCloud, uploadLearnings, type ActivityEvent, type ApiError, type Cloud, type SkillFileUpload, type UploadedLearning } from "./workspace.js";/** A failed sync is retried after this long, not on every command. */const RETRY_MS = 5 * 60 * 1000;@@ -68,6 +69,57 @@ function inside(root: string, p: string): boolean {/** A SKILL.md bigger than this is not a skill, and is never sent. */const SKILL_MAX_BYTES = 256 * 1024;+/** What Trail keeps of a skill's folder besides SKILL.md (the server's limits too). */+const SKILL_FILES_MAX = 100;+const SKILL_FILE_MAX_BYTES = 1024 * 1024;+const SKILL_FOLDER_MAX_BYTES = 4 * 1024 * 1024;+/** Never part of a skill, though a folder may hold them. */+const NOT_SKILL_FILE = /(^|\/)(node_modules|__pycache__|\.git|\.venv)(\/|$)|(^|\/)\.DS_Store$|\.(map|pyc)$/;++/**+ * The files git tracks in a skill's folder besides SKILL.md, as they go up:+ * text as is, anything else as base64, the executable bit kept. A file that+ * resolves outside the checkout, or is too big, stays behind; so do the+ * ones past the folder's limits, smallest paths first.+ */+function skillFolderFiles(root: string, folder: string): SkillFileUpload[] {+ let rel: string;+ try {+ rel = relative(root, realpathSync(folder)).split(sep).join("/");+ } catch {+ return [];+ }+ const out: SkillFileUpload[] = [];+ let total = 0;+ for (const path of [...trackedAmong(root, [rel + "/"])].sort()) {+ const inner = path.slice(rel.length + 1);+ if (!inner || inner === "SKILL.md" || NOT_SKILL_FILE.test(inner) || out.length === SKILL_FILES_MAX) continue;+ try {+ const file = join(root, ...path.split("/"));+ const st = statSync(file);+ if (!st.isFile() || st.size > SKILL_FILE_MAX_BYTES || total + st.size > SKILL_FOLDER_MAX_BYTES) continue;+ if (!inside(root, realpathSync(file))) continue;+ const bytes = readFileSync(file);+ const text = !bytes.includes(0) && isUtf8(bytes);+ total += bytes.length;+ out.push({+ path: inner,+ content: text ? bytes.toString("utf8") : bytes.toString("base64"),+ ...(text ? {} : { encoding: "base64" as const }),+ ...(st.mode & 0o111 ? { executable: true } : {}),+ });+ } catch {+ /* gone, or can't be read */+ }+ }+ return out;+}++/** `cut-a-release` → `Cut a release`: a skill's folder name as a title. */+function skillTitle(name: string): string {+ const words = name.replace(/[-_]+/g, " ").trim();+ return words ? words[0]!.toUpperCase() + words.slice(1) : name;+}/*** Which of `paths` (relative to `root`) git tracks, by what `git ls-files` says,@@ -134,17 +186,21 @@ function skillItems(checkout: string): UploadedLearning[] {const text = readFileSync(file, "utf8");const parsed = matter(text);const d = parsed.data as Record<string, unknown>;- const description = typeof d.description === "string" ? (d.description.trim().split("\n")[0] ?? "").trim() : "";+ const description = typeof d.description === "string" ? d.description.trim().replace(/\s+/g, " ") : "";+ const files = skillFolderFiles(root, join(dir, name));out.push({path: `.claude/skills/${name}/SKILL.md`,kind: "skill",ref: "",- title: description || name,+ title: skillTitle(typeof d.name === "string" && d.name.trim() ? d.name.trim() : name),+ why: description,author: typeof d.author === "string" ? d.author.trim() : "",date: "",touches: [],body: parsed.content.trim(),- hash: sha256(text),+ // The whole folder: any file changing sends the skill again.+ hash: sha256(JSON.stringify(["folder", text, files.map((f) => [f.path, sha256(f.content), !!f.executable])])),+ files,});} catch {/* a SKILL.md that can't be read or parsed */@@ -211,7 +267,8 @@ export function workspaceLearnings(checkout: string, opts: { tree?: boolean } =}));// A skill whose text holds a secret stays behind too, named like a learning is.for (const skill of skillItems(checkout)) {- const why = secretReason(`${skill.title}\n${skill.body}`);+ const texts = (skill.files ?? []).filter((f) => !f.encoding).map((f) => f.content);+ const why = secretReason([skill.title, skill.why ?? "", skill.body, ...texts].join("\n"));if (why) leftOut.push({ name: skill.path, ref: "", why });else learnings.push(skill);}diff --git a/src/cloud/workspace.ts b/src/cloud/workspace.tsindex 2cc6ff9b..4db717c9 100644--- a/src/cloud/workspace.ts+++ b/src/cloud/workspace.ts@@ -295,14 +295,48 @@ export interface UploadedLearning {touches: string[];body: string;hash: string;+ /** A skill's description: what it does and when to use it. */+ why?: string;+ /** A skill's other files: everything git tracks in its folder besides SKILL.md. */+ files?: SkillFileUpload[];}-export function uploadLearnings(+export interface SkillFileUpload {+ /** Relative to the skill's folder: `references/forms.md`, `scripts/fill.py`. */+ path: string;+ /** The file as text, or base64 when `encoding` says so. */+ content: string;+ encoding?: "base64";+ executable?: boolean;+}++/** Most of one upload request: skills bring their folders, so a big set goes up in parts. */+export const UPLOAD_PART_BYTES = 12 * 1024 * 1024;++export async function uploadLearnings(c: Cloud,req: { repo: { key: string; name: string }; learnings: UploadedLearning[] },fetchImpl?: Fetch,): Promise<{ repo: string; learnings: number; added: number } | ApiError> {- return authed(c, "PUT", "/api/cli/learnings", req, { timeoutMs: 60_000, fetchImpl });+ const parts: UploadedLearning[][] = [[]];+ let bytes = 0;+ for (const l of req.learnings) {+ const size = JSON.stringify(l).length;+ if (bytes + size > UPLOAD_PART_BYTES && parts.at(-1)!.length) {+ parts.push([]);+ bytes = 0;+ }+ parts.at(-1)!.push(l);+ bytes += size;+ }+ let added = 0;+ let last: { repo: string; learnings: number; added: number } | ApiError | null = null;+ for (const learnings of parts) {+ last = await authed<{ repo: string; learnings: number; added: number }>(c, "PUT", "/api/cli/learnings", { ...req, learnings }, { timeoutMs: 60_000, fetchImpl });+ if (isError(last)) return last;+ added += last.added;+ }+ return { ...last!, added };}/**diff --git a/test/trail-upload-parts.test.ts b/test/trail-upload-parts.test.tsnew file mode 100644index 00000000..ef90b8c8--- /dev/null+++ b/test/trail-upload-parts.test.ts@@ -0,0 +1,32 @@+/** A big set of learnings (skills bring their folders) goes up in parts, each under the request limit. */+import { test } from "node:test";+import assert from "node:assert/strict";+import { BRAND_ENV } from "../src/brand.js";+import { uploadLearnings, UPLOAD_PART_BYTES, type Cloud, type UploadedLearning } from "../src/cloud/workspace.js";++process.env.DO_NOT_TRACK = "1";+process.env[BRAND_ENV] = "trail";++const cloud = { url: "http://trail.test", token: "t", repos: [] } as unknown as Cloud;+const item = (n: number, size: number): UploadedLearning => ({ path: `.claude/skills/s${n}/SKILL.md`, kind: "skill", ref: "", title: `S${n}`, author: "", date: "", touches: [], body: "x".repeat(size), hash: `h${n}` });++test("an upload past one part's size goes up in parts, adding up what each added", async () => {+ const sizes: number[] = [];+ const f = (async (_url: string | URL, init?: RequestInit) => {+ const body = JSON.parse(String(init!.body)) as { learnings: unknown[] };+ sizes.push(String(init!.body).length);+ return new Response(JSON.stringify({ repo: "r", learnings: 9, added: body.learnings.length }), { status: 200 });+ }) as typeof fetch;+ const big = Math.floor(UPLOAD_PART_BYTES * 0.6);+ const res = await uploadLearnings(cloud, { repo: { key: "github.com/a/b", name: "a/b" }, learnings: [item(1, big), item(2, big), item(3, 10)] }, f);+ assert.equal(sizes.length, 2);+ assert.ok(sizes.every((s) => s < UPLOAD_PART_BYTES * 1.3));+ assert.deepEqual(res, { repo: "r", learnings: 9, added: 3 });+});++test("a small upload is one request", async () => {+ let calls = 0;+ const f = (async () => (calls++, new Response(JSON.stringify({ repo: "r", learnings: 1, added: 1 }), { status: 200 }))) as typeof fetch;+ await uploadLearnings(cloud, { repo: { key: "github.com/a/b", name: "a/b" }, learnings: [item(1, 10)] }, f);+ assert.equal(calls, 1);+});diff --git a/test/workspace-sync-skills.test.ts b/test/workspace-sync-skills.test.tsindex f9c53be8..c7e00ece 100644--- a/test/workspace-sync-skills.test.ts+++ b/test/workspace-sync-skills.test.ts@@ -68,9 +68,12 @@ test("the repo's skill goes up as a skill learning, and a skill kept on this macconst s = items[0]!;assert.equal(s.path, ".claude/skills/release-hotfix/SKILL.md");assert.equal(s.kind, "skill");- assert.equal(s.title, "Cut a hotfix release from a tagged commit");+ // 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.equal(s.hash, sha(HOTFIX));+ 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, []);@@ -83,7 +86,8 @@ test("a skill without a description is titled by its folder, and plain learningswriteNote(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!.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");@@ -165,3 +169,53 @@ test("a SKILL.md over 256 KB is skipped", () => {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);+ 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);+});