skills 1.5.6 → 1.5.7

package/dist/cli.mjs

@@ -17,7 +17,9 @@ import * as readline from "readline";
 import { Writable } from "stream";
 import { access, cp, lstat, mkdir, mkdtemp, readFile, readdir, readlink, realpath, rm, stat, symlink, writeFile } from "fs/promises";
 import { parse } from "yaml";
-import { createHash } from "crypto";
+import { createHash } from "node:crypto";
+import { gunzipSync, inflateRawSync } from "node:zlib";
+import { createHash as createHash$1 } from "crypto";
 var import_picocolors = /* @__PURE__ */ __toESM(require_picocolors(), 1);
 function getOwnerRepo(parsed) {
 	if (parsed.type === "local") return null;
@@ -1475,7 +1477,7 @@ async function installWellKnownSkillForAgent(skill, agentType, options = {}) {
 			if (!isPathSafe(targetDir, fullPath)) continue;
 			const parentDir = dirname(fullPath);
 			if (parentDir !== targetDir) await mkdir(parentDir, { recursive: true });
-			await writeFile(fullPath, content, "utf-8");
+			await writeFile(fullPath, content);
 		}
 	}
 	try {
@@ -1829,6 +1831,9 @@ var ProviderRegistryImpl = class {
 	}
 };
 new ProviderRegistryImpl();
+const DISCOVERY_SCHEMA_V2 = "https://schemas.agentskills.io/discovery/0.2.0/schema.json";
+const MAX_ARCHIVE_UNPACKED_BYTES = 50 * 1024 * 1024;
+const MAX_ARCHIVE_FILES = 1e3;
 var WellKnownProvider = class {
 	id = "well-known";
 	displayName = "Well-Known Skills";
@@ -1852,6 +1857,9 @@ var WellKnownProvider = class {
 		}
 	}
 	async fetchIndex(baseUrl) {
+		return (await this.fetchIndexCandidates(baseUrl))[0] ?? null;
+	}
+	async fetchIndexCandidates(baseUrl) {
 		try {
 			const parsed = new URL(baseUrl);
 			const basePath = parsed.pathname.replace(/\/$/, "");
@@ -1868,113 +1876,383 @@ var WellKnownProvider = class {
 					wellKnownPath
 				});
 			}
+			const candidates = [];
 			for (const { indexUrl, baseUrl: resolvedBase, wellKnownPath } of urlsToTry) try {
 				const response = await fetch(indexUrl);
 				if (!response.ok) continue;
-				const index = await response.json();
-				if (!index.skills || !Array.isArray(index.skills)) continue;
-				let allValid = true;
-				for (const entry of index.skills) if (!this.isValidSkillEntry(entry)) {
-					allValid = false;
-					break;
-				}
-				if (allValid) return {
-					index,
+				const rawIndex = await response.json();
+				const normalized = this.normalizeIndex(rawIndex, indexUrl, wellKnownPath);
+				if (!normalized) continue;
+				candidates.push({
+					index: normalized.index,
+					entries: normalized.entries,
 					resolvedBaseUrl: resolvedBase,
-					resolvedWellKnownPath: wellKnownPath
-				};
+					resolvedWellKnownPath: wellKnownPath,
+					indexUrl
+				});
 			} catch {
 				continue;
 			}
-			return null;
+			return candidates;
 		} catch {
-			return null;
+			return [];
+		}
+	}
+	normalizeIndex(rawIndex, indexUrl, resolvedWellKnownPath) {
+		if (!rawIndex || typeof rawIndex !== "object") return null;
+		const record = rawIndex;
+		if (!Array.isArray(record.skills)) return null;
+		const schema = record.$schema;
+		if (schema === DISCOVERY_SCHEMA_V2) {
+			const entries = [];
+			const v2Entries = [];
+			for (const entry of record.skills) {
+				if (!this.isValidSkillEntryV2(entry)) continue;
+				const artifactUrl = new URL(entry.url, indexUrl).toString();
+				entries.push({
+					version: "0.2.0",
+					name: entry.name,
+					description: entry.description,
+					type: entry.type,
+					artifactUrl,
+					digest: entry.digest,
+					indexEntry: entry
+				});
+				v2Entries.push(entry);
+			}
+			if (entries.length === 0) return null;
+			return {
+				index: {
+					$schema: DISCOVERY_SCHEMA_V2,
+					skills: v2Entries
+				},
+				entries
+			};
+		}
+		if (schema !== void 0) return null;
+		const v1Entries = [];
+		const entries = [];
+		for (const entry of record.skills) {
+			if (!this.isValidSkillEntryV1(entry)) return null;
+			v1Entries.push(entry);
+			entries.push({
+				version: "0.1.0",
+				name: entry.name,
+				description: entry.description,
+				files: entry.files,
+				baseUrl: this.getLegacySkillBaseUrl(indexUrl, resolvedWellKnownPath),
+				wellKnownPath: resolvedWellKnownPath,
+				indexEntry: entry
+			});
 		}
+		return {
+			index: { skills: v1Entries },
+			entries
+		};
 	}
-	isValidSkillEntry(entry) {
+	getLegacySkillBaseUrl(indexUrl, wellKnownPath) {
+		const parsed = new URL(indexUrl);
+		const marker = `/${wellKnownPath}/${this.INDEX_FILE}`;
+		return `${parsed.protocol}//${parsed.host}${parsed.pathname.slice(0, -marker.length)}`;
+	}
+	isValidSkillName(name) {
+		if (typeof name !== "string") return false;
+		if (name.length < 1 || name.length > 64) return false;
+		if (!/^[a-z0-9-]+$/.test(name)) return false;
+		if (name.startsWith("-") || name.endsWith("-")) return false;
+		if (name.includes("--")) return false;
+		return true;
+	}
+	isSafeLegacyFilePath(filePath) {
+		if (typeof filePath !== "string" || filePath.length === 0) return false;
+		if (filePath.startsWith("/") || filePath.startsWith("\\") || filePath.includes("..")) return false;
+		if (filePath.includes("\0")) return false;
+		return true;
+	}
+	isValidSkillEntryV1(entry) {
 		if (!entry || typeof entry !== "object") return false;
 		const e = entry;
-		if (typeof e.name !== "string" || !e.name) return false;
+		if (!this.isValidSkillName(e.name)) return false;
 		if (typeof e.description !== "string" || !e.description) return false;
 		if (!Array.isArray(e.files) || e.files.length === 0) return false;
-		if (!/^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$/.test(e.name) && e.name.length > 1) {
-			if (e.name.length === 1 && !/^[a-z0-9]$/.test(e.name)) return false;
-		}
-		for (const file of e.files) {
-			if (typeof file !== "string") return false;
-			if (file.startsWith("/") || file.startsWith("\\") || file.includes("..")) return false;
+		for (const file of e.files) if (!this.isSafeLegacyFilePath(file)) return false;
+		return e.files.some((f) => typeof f === "string" && f.toLowerCase() === "skill.md");
+	}
+	isValidSkillEntryV2(entry) {
+		if (!entry || typeof entry !== "object") return false;
+		const e = entry;
+		if (!this.isValidSkillName(e.name)) return false;
+		if (typeof e.description !== "string" || !e.description || e.description.length > 1024) return false;
+		if (e.type !== "skill-md" && e.type !== "archive") return false;
+		if (typeof e.url !== "string" || !e.url) return false;
+		if (typeof e.digest !== "string" || !/^sha256:[a-f0-9]{64}$/.test(e.digest)) return false;
+		try {
+			new URL(e.url, "https://example.com/.well-known/agent-skills/index.json");
+		} catch {
+			return false;
 		}
-		if (!e.files.some((f) => typeof f === "string" && f.toLowerCase() === "skill.md")) return false;
 		return true;
 	}
 	async fetchSkill(url) {
 		try {
 			const parsed = new URL(url);
-			const result = await this.fetchIndex(url);
-			if (!result) return null;
-			const { index, resolvedBaseUrl, resolvedWellKnownPath } = result;
-			let skillName = null;
-			const pathMatch = parsed.pathname.match(/\/.well-known\/(?:agent-skills|skills)\/([^/]+)\/?$/);
-			if (pathMatch && pathMatch[1] && pathMatch[1] !== "index.json") skillName = pathMatch[1];
-			else if (index.skills.length === 1) skillName = index.skills[0].name;
-			if (!skillName) return null;
-			const skillEntry = index.skills.find((s) => s.name === skillName);
-			if (!skillEntry) return null;
-			return this.fetchSkillByEntry(resolvedBaseUrl, skillEntry, resolvedWellKnownPath);
+			const candidates = await this.fetchIndexCandidates(url);
+			for (const result of candidates) {
+				const { entries } = result;
+				let skillName = null;
+				const pathMatch = parsed.pathname.match(/\/.well-known\/(?:agent-skills|skills)\/([^/]+)\/?$/);
+				if (pathMatch && pathMatch[1] && pathMatch[1] !== "index.json") skillName = pathMatch[1];
+				else if (entries.length === 1) skillName = entries[0].name;
+				if (!skillName) continue;
+				const skillEntry = entries.find((s) => s.name === skillName);
+				if (!skillEntry) continue;
+				const skill = await this.fetchSkillByEntry(skillEntry);
+				if (skill) return skill;
+			}
+			return null;
 		} catch {
 			return null;
 		}
 	}
-	async fetchSkillByEntry(baseUrl, entry, wellKnownPath) {
+	async fetchSkillByEntry(baseUrlOrEntry, legacyEntry, legacyWellKnownPath) {
+		if (typeof baseUrlOrEntry === "string") {
+			if (!legacyEntry) return null;
+			return this.fetchLegacySkillByEntry({
+				version: "0.1.0",
+				name: legacyEntry.name,
+				description: legacyEntry.description,
+				files: legacyEntry.files,
+				baseUrl: baseUrlOrEntry,
+				wellKnownPath: legacyWellKnownPath ?? this.WELL_KNOWN_PATHS[0],
+				indexEntry: legacyEntry
+			});
+		}
+		if (baseUrlOrEntry.version === "0.1.0") return this.fetchLegacySkillByEntry(baseUrlOrEntry);
+		return this.fetchArtifactSkillByEntry(baseUrlOrEntry);
+	}
+	async fetchLegacySkillByEntry(entry) {
 		try {
-			const resolvedPath = wellKnownPath ?? this.WELL_KNOWN_PATHS[0];
-			const skillBaseUrl = `${baseUrl.replace(/\/$/, "")}/${resolvedPath}/${entry.name}`;
+			const skillBaseUrl = `${entry.baseUrl.replace(/\/$/, "")}/${entry.wellKnownPath}/${entry.name}`;
 			const skillMdUrl = `${skillBaseUrl}/SKILL.md`;
 			const response = await fetch(skillMdUrl);
 			if (!response.ok) return null;
 			const content = await response.text();
 			const { data } = parseFrontmatter(content);
-			if (!data.name || !data.description) return null;
+			if (typeof data.name !== "string" || typeof data.description !== "string") return null;
 			const files = /* @__PURE__ */ new Map();
 			files.set("SKILL.md", content);
 			const filePromises = entry.files.filter((f) => f.toLowerCase() !== "skill.md").map(async (filePath) => {
 				try {
 					const fileUrl = `${skillBaseUrl}/${filePath}`;
 					const fileResponse = await fetch(fileUrl);
-					if (fileResponse.ok) return {
-						path: filePath,
-						content: await fileResponse.text()
-					};
+					if (fileResponse.ok) {
+						const fileContent = await fileResponse.arrayBuffer();
+						return {
+							path: filePath,
+							content: new Uint8Array(fileContent)
+						};
+					}
 				} catch {}
 				return null;
 			});
 			const fileResults = await Promise.all(filePromises);
 			for (const result of fileResults) if (result) files.set(result.path, result.content);
-			return {
-				name: sanitizeMetadata(data.name),
-				description: sanitizeMetadata(data.description),
+			return this.createSkill({
+				name: data.name,
+				description: data.description,
 				content,
 				installName: entry.name,
 				sourceUrl: skillMdUrl,
 				metadata: data.metadata,
 				files,
-				indexEntry: entry
-			};
+				indexEntry: entry.indexEntry
+			});
+		} catch {
+			return null;
+		}
+	}
+	async fetchArtifactSkillByEntry(entry) {
+		try {
+			const response = await fetch(entry.artifactUrl);
+			if (!response.ok) return null;
+			const contentType = response.headers.get("content-type") ?? "";
+			const bytes = new Uint8Array(await response.arrayBuffer());
+			if (this.computeDigest(bytes) !== entry.digest) return null;
+			if (entry.type === "skill-md") {
+				const content = new TextDecoder().decode(bytes);
+				const { data } = parseFrontmatter(content);
+				if (typeof data.name !== "string" || typeof data.description !== "string") return null;
+				const files = /* @__PURE__ */ new Map();
+				files.set("SKILL.md", content);
+				return this.createSkill({
+					name: data.name,
+					description: data.description,
+					content,
+					installName: entry.name,
+					sourceUrl: entry.artifactUrl,
+					metadata: data.metadata,
+					files,
+					indexEntry: entry.indexEntry
+				});
+			}
+			const files = this.extractArchive(bytes, entry.artifactUrl, contentType);
+			const skillMdBytes = files.get("SKILL.md");
+			if (!skillMdBytes) return null;
+			const content = typeof skillMdBytes === "string" ? skillMdBytes : new TextDecoder().decode(skillMdBytes);
+			files.set("SKILL.md", content);
+			const { data } = parseFrontmatter(content);
+			if (typeof data.name !== "string" || typeof data.description !== "string") return null;
+			return this.createSkill({
+				name: data.name,
+				description: data.description,
+				content,
+				installName: entry.name,
+				sourceUrl: entry.artifactUrl,
+				metadata: data.metadata,
+				files,
+				indexEntry: entry.indexEntry
+			});
 		} catch {
 			return null;
 		}
 	}
+	createSkill(input) {
+		return {
+			name: sanitizeMetadata(input.name),
+			description: sanitizeMetadata(input.description),
+			content: input.content,
+			installName: input.installName,
+			sourceUrl: input.sourceUrl,
+			metadata: input.metadata && typeof input.metadata === "object" ? input.metadata : void 0,
+			files: input.files,
+			indexEntry: input.indexEntry
+		};
+	}
 	async fetchAllSkills(url) {
 		try {
-			const result = await this.fetchIndex(url);
-			if (!result) return [];
-			const { index, resolvedBaseUrl, resolvedWellKnownPath } = result;
-			const skillPromises = index.skills.map((entry) => this.fetchSkillByEntry(resolvedBaseUrl, entry, resolvedWellKnownPath));
-			return (await Promise.all(skillPromises)).filter((s) => s !== null);
+			const candidates = await this.fetchIndexCandidates(url);
+			for (const result of candidates) {
+				const skillPromises = result.entries.map((entry) => this.fetchSkillByEntry(entry));
+				const skills = (await Promise.all(skillPromises)).filter((s) => s !== null);
+				if (skills.length > 0) return skills;
+			}
+			return [];
 		} catch {
 			return [];
 		}
 	}
+	computeDigest(bytes) {
+		return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+	}
+	extractArchive(bytes, artifactUrl, contentType) {
+		if (this.isZipArchive(bytes, artifactUrl, contentType)) return this.extractZip(bytes);
+		if (this.isTarGzArchive(bytes, artifactUrl, contentType)) return this.extractTarGz(bytes);
+		throw new Error("Unsupported archive format");
+	}
+	isZipArchive(bytes, artifactUrl, contentType) {
+		return contentType.includes("application/zip") || artifactUrl.toLowerCase().endsWith(".zip") || bytes[0] === 80 && bytes[1] === 75;
+	}
+	isTarGzArchive(bytes, artifactUrl, contentType) {
+		const lower = artifactUrl.toLowerCase();
+		return contentType.includes("application/gzip") || contentType.includes("application/x-gzip") || lower.endsWith(".tar.gz") || lower.endsWith(".tgz") || bytes[0] === 31 && bytes[1] === 139;
+	}
+	normalizeArchivePath(rawPath) {
+		if (!rawPath || rawPath.includes("\0")) return null;
+		if (rawPath.startsWith("/") || rawPath.startsWith("\\")) return null;
+		if (/^[A-Za-z]:/.test(rawPath)) return null;
+		if (rawPath.includes("\\")) return null;
+		const parts = rawPath.split("/").filter(Boolean);
+		if (parts.length === 0) return null;
+		if (parts.some((part) => part === "." || part === "..")) return null;
+		return parts.join("/");
+	}
+	addArchiveFile(files, path, content, runningTotal) {
+		const normalizedPath = this.normalizeArchivePath(path);
+		if (!normalizedPath) throw new Error(`Unsafe archive path: ${path}`);
+		runningTotal.bytes += content.byteLength;
+		if (runningTotal.bytes > MAX_ARCHIVE_UNPACKED_BYTES) throw new Error("Archive exceeds maximum unpacked size");
+		if (files.size >= MAX_ARCHIVE_FILES) throw new Error("Archive contains too many files");
+		files.set(normalizedPath, content);
+	}
+	extractTarGz(bytes) {
+		const tar = gunzipSync(Buffer.from(bytes));
+		const files = /* @__PURE__ */ new Map();
+		const runningTotal = { bytes: 0 };
+		let offset = 0;
+		while (offset + 512 <= tar.length) {
+			const header = tar.subarray(offset, offset + 512);
+			if (header.every((byte) => byte === 0)) break;
+			const name = this.readTarString(header, 0, 100);
+			const sizeText = this.readTarString(header, 124, 12).trim();
+			const typeFlag = header[156];
+			const prefix = this.readTarString(header, 345, 155);
+			const path = prefix ? `${prefix}/${name}` : name;
+			const size = Number.parseInt(sizeText || "0", 8);
+			if (!Number.isFinite(size) || size < 0) throw new Error("Invalid tar entry size");
+			offset += 512;
+			if (typeFlag === 50 || typeFlag === 49) throw new Error("Archive links are not supported");
+			if (typeFlag === 0 || typeFlag === 48) {
+				const content = tar.subarray(offset, offset + size);
+				this.addArchiveFile(files, path, new Uint8Array(content), runningTotal);
+			}
+			offset += Math.ceil(size / 512) * 512;
+		}
+		if (!files.has("SKILL.md")) throw new Error("Archive missing root SKILL.md");
+		return files;
+	}
+	readTarString(buffer, offset, length) {
+		const slice = buffer.subarray(offset, offset + length);
+		const nul = slice.indexOf(0);
+		return new TextDecoder().decode(nul >= 0 ? slice.subarray(0, nul) : slice);
+	}
+	extractZip(bytes) {
+		const buffer = Buffer.from(bytes);
+		const eocdOffset = this.findZipEndOfCentralDirectory(buffer);
+		if (eocdOffset < 0) throw new Error("Invalid zip archive");
+		const totalEntries = buffer.readUInt16LE(eocdOffset + 10);
+		const centralDirectoryOffset = buffer.readUInt32LE(eocdOffset + 16);
+		const files = /* @__PURE__ */ new Map();
+		const runningTotal = { bytes: 0 };
+		let offset = centralDirectoryOffset;
+		for (let i = 0; i < totalEntries; i++) {
+			if (buffer.readUInt32LE(offset) !== 33639248) throw new Error("Invalid zip directory");
+			const flags = buffer.readUInt16LE(offset + 8);
+			const method = buffer.readUInt16LE(offset + 10);
+			const compressedSize = buffer.readUInt32LE(offset + 20);
+			const uncompressedSize = buffer.readUInt32LE(offset + 24);
+			const fileNameLength = buffer.readUInt16LE(offset + 28);
+			const extraLength = buffer.readUInt16LE(offset + 30);
+			const commentLength = buffer.readUInt16LE(offset + 32);
+			const externalAttributes = buffer.readUInt32LE(offset + 38);
+			const localHeaderOffset = buffer.readUInt32LE(offset + 42);
+			const nameStart = offset + 46;
+			const rawName = buffer.subarray(nameStart, nameStart + fileNameLength);
+			const fileName = new TextDecoder(flags & 2048 ? "utf-8" : void 0).decode(rawName);
+			offset = nameStart + fileNameLength + extraLength + commentLength;
+			if (fileName.endsWith("/")) continue;
+			if (flags & 1) throw new Error("Encrypted zip entries are not supported");
+			const fileType = externalAttributes >>> 16 & 61440;
+			if (fileType === 40960 || fileType === 4096) throw new Error("Archive links are not supported");
+			if (buffer.readUInt32LE(localHeaderOffset) !== 67324752) throw new Error("Invalid zip local header");
+			const localFileNameLength = buffer.readUInt16LE(localHeaderOffset + 26);
+			const localExtraLength = buffer.readUInt16LE(localHeaderOffset + 28);
+			const dataStart = localHeaderOffset + 30 + localFileNameLength + localExtraLength;
+			const compressed = buffer.subarray(dataStart, dataStart + compressedSize);
+			let content;
+			if (method === 0) content = compressed;
+			else if (method === 8) content = inflateRawSync(compressed);
+			else throw new Error(`Unsupported zip compression method: ${method}`);
+			if (content.byteLength !== uncompressedSize) throw new Error("Zip entry size mismatch");
+			this.addArchiveFile(files, fileName, new Uint8Array(content), runningTotal);
+		}
+		if (!files.has("SKILL.md")) throw new Error("Archive missing root SKILL.md");
+		return files;
+	}
+	findZipEndOfCentralDirectory(buffer) {
+		const minOffset = Math.max(0, buffer.length - 65535 - 22);
+		for (let offset = buffer.length - 22; offset >= minOffset; offset--) if (buffer.readUInt32LE(offset) === 101010256) return offset;
+		return -1;
+	}
 	toRawUrl(url) {
 		try {
 			const parsed = new URL(url);
@@ -2028,9 +2306,14 @@ async function writeSkillLock(lock) {
 	await mkdir(dirname(lockPath), { recursive: true });
 	await writeFile(lockPath, JSON.stringify(lock, null, 2), "utf-8");
 }
+let _ghWarningShown = false;
 function getGitHubToken() {
 	if (process.env.GITHUB_TOKEN) return process.env.GITHUB_TOKEN;
 	if (process.env.GH_TOKEN) return process.env.GH_TOKEN;
+	if (!_ghWarningShown) {
+		process.stderr.write("warn: GitHub API rate limit reached; reading a token via `gh auth token`.\n      Set GITHUB_TOKEN in your environment to skip this fallback.\n");
+		_ghWarningShown = true;
+	}
 	try {
 		const token = execSync("gh auth token", {
 			encoding: "utf-8",
@@ -2044,9 +2327,9 @@ function getGitHubToken() {
 	} catch {}
 	return null;
 }
-async function fetchSkillFolderHash(ownerRepo, skillPath, token, ref) {
+async function fetchSkillFolderHash(ownerRepo, skillPath, getToken, ref) {
 	const { fetchRepoTree, getSkillFolderHashFromTree } = await Promise.resolve().then(() => blob_exports);
-	const tree = await fetchRepoTree(ownerRepo, ref, token);
+	const tree = await fetchRepoTree(ownerRepo, ref, getToken ?? void 0);
 	if (!tree) return null;
 	return getSkillFolderHashFromTree(tree, skillPath);
 }
@@ -2129,7 +2412,7 @@ async function computeSkillFolderHash(skillDir) {
 	const files = [];
 	await collectFiles(skillDir, skillDir, files);
 	files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
-	const hash = createHash("sha256");
+	const hash = createHash$1("sha256");
 	for (const file of files) {
 		hash.update(file.relativePath);
 		hash.update(file.content);
@@ -2176,13 +2459,9 @@ const FETCH_TIMEOUT = 1e4;
 function toSkillSlug(name) {
 	return name.toLowerCase().replace(/[\s_]+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
 }
-async function fetchRepoTree(ownerRepo, ref, token) {
-	const branches = ref ? [ref] : [
-		"HEAD",
-		"main",
-		"master"
-	];
-	for (const branch of branches) try {
+let _rateLimitedThisSession = false;
+async function fetchTreeBranch(ownerRepo, branch, token) {
+	try {
 		const url = `https://api.github.com/repos/${ownerRepo}/git/trees/${encodeURIComponent(branch)}?recursive=1`;
 		const headers = {
 			Accept: "application/vnd.github.v3+json",
@@ -2193,15 +2472,59 @@ async function fetchRepoTree(ownerRepo, ref, token) {
 			headers,
 			signal: AbortSignal.timeout(FETCH_TIMEOUT)
 		});
-		if (!response.ok) continue;
-		const data = await response.json();
+		if (response.ok) {
+			const data = await response.json();
+			return {
+				tree: {
+					sha: data.sha,
+					branch,
+					tree: data.tree
+				},
+				rateLimited: false
+			};
+		}
 		return {
-			sha: data.sha,
-			branch,
-			tree: data.tree
+			tree: null,
+			rateLimited: response.status === 403 && response.headers.get("x-ratelimit-remaining") === "0"
 		};
 	} catch {
-		continue;
+		return {
+			tree: null,
+			rateLimited: false
+		};
+	}
+}
+async function fetchRepoTree(ownerRepo, ref, getToken) {
+	const branches = ref ? [ref] : [
+		"HEAD",
+		"main",
+		"master"
+	];
+	if (_rateLimitedThisSession && getToken) {
+		const token = getToken();
+		if (!token) return null;
+		for (const branch of branches) {
+			const result = await fetchTreeBranch(ownerRepo, branch, token);
+			if (result.tree) return result.tree;
+		}
+		return null;
+	}
+	let rateLimited = false;
+	for (const branch of branches) {
+		const result = await fetchTreeBranch(ownerRepo, branch, null);
+		if (result.tree) return result.tree;
+		if (result.rateLimited) {
+			rateLimited = true;
+			break;
+		}
+	}
+	if (!rateLimited || !getToken) return null;
+	_rateLimitedThisSession = true;
+	const token = getToken();
+	if (!token) return null;
+	for (const branch of branches) {
+		const result = await fetchTreeBranch(ownerRepo, branch, token);
+		if (result.tree) return result.tree;
 	}
 	return null;
 }
@@ -2298,7 +2621,7 @@ async function fetchSkillDownload(source, slug) {
 	}
 }
 async function tryBlobInstall(ownerRepo, options = {}) {
-	const tree = await fetchRepoTree(ownerRepo, options.ref, options.token);
+	const tree = await fetchRepoTree(ownerRepo, options.ref, options.getToken);
 	if (!tree) return null;
 	let skillMdPaths = findSkillMdPaths(tree, options.subpath);
 	if (skillMdPaths.length === 0) return null;
@@ -2370,7 +2693,7 @@ async function tryBlobInstall(ownerRepo, options = {}) {
 		tree
 	};
 }
-var version$1 = "1.5.6";
+var version$1 = "1.5.7";
 const isCancelled$1 = (value) => typeof value === "symbol";
 async function isSourcePrivate(source) {
 	const ownerRepo = parseOwnerRepo(source);
@@ -2912,12 +3235,11 @@ async function runAdd(args, options = {}) {
 			const owner = ownerRepo?.split("/")[0]?.toLowerCase();
 			if (ownerRepo && owner && BLOB_ALLOWED_OWNERS.includes(owner)) {
 				spinner.start("Fetching skills...");
-				const token = getGitHubToken();
 				blobResult = await tryBlobInstall(ownerRepo, {
 					subpath: parsed.subpath,
 					skillFilter: parsed.skillFilter,
 					ref: parsed.ref,
-					token,
+					getToken: getGitHubToken,
 					includeInternal
 				});
 				if (!blobResult) spinner.stop(import_picocolors.default.dim("Falling back to clone..."));
@@ -3265,10 +3587,7 @@ async function runAdd(args, options = {}) {
 		if (successful.length > 0 && installGlobally && normalizedSource) {
 			const successfulSkillNames = new Set(successful.map((r) => r.skill));
 			let cachedTree;
-			if (parsed.type === "github" && !blobResult) {
-				const token = getGitHubToken();
-				cachedTree = await fetchRepoTree(normalizedSource, parsed.ref, token);
-			}
+			if (parsed.type === "github" && !blobResult) cachedTree = await fetchRepoTree(normalizedSource, parsed.ref, getGitHubToken);
 			for (const skill of selectedSkills) {
 				const skillDisplayName = getSkillDisplayName(skill);
 				if (successfulSkillNames.has(skillDisplayName)) try {
@@ -4751,7 +5070,6 @@ async function updateGlobalSkills(skillFilter) {
 			checkedCount: 0
 		};
 	}
-	const token = getGitHubToken();
 	const updates = [];
 	const skipped = [];
 	const checkable = [];
@@ -4778,7 +5096,7 @@ async function updateGlobalSkills(skillFilter) {
 		const { name: skillName, entry } = checkable[i];
 		process.stdout.write(`\r${DIM}Checking global skill ${i + 1}/${checkable.length}: ${sanitizeMetadata(skillName)}${RESET}\x1b[K`);
 		try {
-			const latestHash = await fetchSkillFolderHash(entry.source, entry.skillPath, token, entry.ref);
+			const latestHash = await fetchSkillFolderHash(entry.source, entry.skillPath, getGitHubToken, entry.ref);
 			if (latestHash && latestHash !== entry.skillFolderHash) updates.push({
 				name: skillName,
 				source: entry.source,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills",
-  "version": "1.5.6",
+  "version": "1.5.7",
   "description": "The open agent skills ecosystem",
   "type": "module",
   "bin": {