Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 mac
const 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 learnings
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!.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);
+});