an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions
HTML agent-harnessagent-orchestrationagentsai-agentsautonomous-agentsclaude-codecodexcoding-agentsdesktop-appdeveloper-toolselectrongemini-cliharnessharness-engineeringlocal-firstmemorymulti-agentopencodeorchestrationtypescript
fix(skills): resolve the SKILL.md directory before installing a repo-root source
vspapg28769533ffd5
diff --git a/src/main/skills.ts b/src/main/skills.tsindex 98a9488c..1e2121d2 100644--- a/src/main/skills.ts+++ b/src/main/skills.ts@@ -320,6 +320,62 @@ function getJson<T>(url: string): Promise<T> {return getText(url).then((t) => JSON.parse(t) as T);}+/**+ * For a repo-ROOT source, find the directory that actually holds the skill+ * BEFORE anything is walked or downloaded (issue #385).+ *+ * A root URL used to mean "the repo root IS the skill" unconditionally, so the+ * installer walked the entire repository — and MAX_FILES / MAX_TOTAL_BYTES,+ * meant to bound one skill folder, were applied to the whole repo. Any normal+ * repo that keeps its skill under `skills/<name>` failed with "larger than this+ * installer will fetch" even when the skill itself was a few KB.+ *+ * Resolution order, each step one directory listing:+ * 1. Root contains SKILL.md → the root is the skill (the well-formed entries).+ * 2. `skills/<name>`, `.claude/skills/<name>`, `<name>` — probed only when+ * their first segment exists as a directory in the root listing, so the+ * outcome is fully determined by listings and no blind 404s are issued.+ * 3. Nothing holds a SKILL.md → a structured refusal, before any download.+ *+ * `listDir` is injected (the contents-API fetch in production) so this policy+ * is testable without the network.+ */+export async function resolveRepoRootSkillDir(+ listDir: (path: string) => Promise<GhEntry[]>,+ entryName: string+): Promise<{ path: string } | { error: string; unsupported?: boolean }> {+ let root: GhEntry[];+ try {+ root = await listDir('');+ } catch (e) {+ return { error: e instanceof Error ? e.message : String(e) };+ }+ const hasSkillMd = (listing: GhEntry[]) =>+ listing.some((it) => it.type === 'file' && it.name === 'SKILL.md');+ if (hasSkillMd(root)) return { path: '' };++ const hasDir = (name: string) => root.some((it) => it.type === 'dir' && it.name === name);+ const name = safeSkillDirName(entryName);+ const candidates = name+ ? [+ ...(hasDir('skills') ? [`skills/${name}`] : []),+ ...(hasDir('.claude') ? [`.claude/skills/${name}`] : []),+ ...(hasDir(name) ? [name] : [])+ ]+ : [];+ for (const candidate of candidates) {+ try {+ if (hasSkillMd(await listDir(candidate))) return { path: candidate };+ } catch {+ // 404 or transient failure on a guess — try the next location.+ }+ }+ return {+ unsupported: true,+ error: "couldn't find the skill's SKILL.md in that repository — open Learn more to install it by hand"+ };+}+/** officialskills.sh pages are a rendering of a GitHub folder and link back to* it. Resolving that link is one request and turns 578 otherwise un-installable* catalog rows into installable ones. */@@ -350,18 +406,32 @@ export async function installSkill(const gh = parseGitHubSourceUrl(source);if (!gh) return { ok: false, unsupported: true, error: 'Source is not a GitHub folder.' };- const dirName = safeSkillDirName(gh.path || entryName);- if (!dirName) return { ok: false, error: 'That skill has a name this app will not create a folder for.' };-- const root = join(homedir(), '.claude', 'skills');- const dest = join(root, dirName);- if (existsSync(dest)) return { ok: false, error: `Already installed at ${dest}` };-// An empty ref means "the repo's default branch" — omit the parameter entirely// rather than guessing main vs master.const api = (p: string) =>`https://api.github.com/repos/${gh.owner}/${gh.repo}/contents/${p ? encodeURI(p) : ''}`+ (gh.ref ? `?ref=${encodeURIComponent(gh.ref)}` : '');+ const listDir = async (p: string): Promise<GhEntry[]> => {+ const res = await getJson<GhEntry[] | GhEntry>(api(p));+ return Array.isArray(res) ? res : [res];+ };++ // A repo-root source names a repository, not necessarily a skill folder —+ // locate the SKILL.md directory first so the size/file caps bound the skill,+ // not the whole repo (issue #385). Tree URLs keep their explicit path.+ let skillPath = gh.path;+ if (!skillPath) {+ const resolved = await resolveRepoRootSkillDir(listDir, entryName);+ if ('error' in resolved) return { ok: false, error: resolved.error, unsupported: resolved.unsupported };+ skillPath = resolved.path;+ }++ const dirName = safeSkillDirName(skillPath || entryName);+ if (!dirName) return { ok: false, error: 'That skill has a name this app will not create a folder for.' };++ const root = join(homedir(), '.claude', 'skills');+ const dest = join(root, dirName);+ if (existsSync(dest)) return { ok: false, error: `Already installed at ${dest}` };const files: { path: string; url: string; size: number }[] = [];let total = 0;@@ -386,13 +456,13 @@ export async function installSkill(const size = it.size ?? 0;total += size;if (total > MAX_TOTAL_BYTES) return 'that skill is larger than this installer will fetch';- const rel = gh.path ? it.path.slice(gh.path.length).replace(/^\/+/, '') : it.path;+ const rel = skillPath ? it.path.slice(skillPath.length).replace(/^\/+/, '') : it.path;files.push({ path: rel, url: it.download_url, size });}return null;};- const walkErr = await walk(gh.path, 0);+ const walkErr = await walk(skillPath, 0);if (walkErr) return { ok: false, error: walkErr };if (files.length === 0) return { ok: false, error: 'No files found at that source.' };diff --git a/test/skills-install.test.cjs b/test/skills-install.test.cjsindex 6420140f..bced8f90 100644--- a/test/skills-install.test.cjs+++ b/test/skills-install.test.cjs@@ -16,7 +16,7 @@ const fs = require('node:fs');const path = require('node:path');const loadTs = require('./load-ts.cjs');-const { parseGitHubSourceUrl, safeSkillDirName, uninstallSkill } =+const { parseGitHubSourceUrl, resolveRepoRootSkillDir, safeSkillDirName, uninstallSkill } =loadTs('src/main/skills.ts');const tmpdir = (t) => {@@ -48,6 +48,84 @@ test('a skill folder name that could escape its directory is refused', () => {assert.equal(safeSkillDirName('a/../../b'), 'b');});+// ── repo-root skill resolution (issue #385) ─────────────────────────────────+// A root URL used to mean "walk the whole repository": every file counted+// against MAX_FILES / MAX_TOTAL_BYTES, so a tiny skill inside a normal-sized+// repo failed with "larger than this installer will fetch". The resolver finds+// the directory that actually holds SKILL.md before anything is fetched.++/** A fake GitHub contents API: {'': [...], 'skills/foo': [...]}. Missing key = 404. */+const lister = (dirs) => async (p) => {+ if (!(p in dirs)) throw new Error('Not Found (404)');+ return dirs[p];+};+const file = (name) => ({ name, path: name, type: 'file', size: 10, download_url: 'x' });+const dir = (name) => ({ name, path: name, type: 'dir' });++test('a repo whose root holds SKILL.md is the skill itself (the 81 well-formed entries)', async () => {+ const resolved = await resolveRepoRootSkillDir(lister({ '': [file('SKILL.md'), file('README.md')] }), 'demo');+ assert.deepEqual(resolved, { path: '' });+});++test('a repo-root entry resolves to skills/<name> instead of walking the whole repo', async () => {+ const resolved = await resolveRepoRootSkillDir(+ lister({+ '': [dir('skills'), dir('src'), file('README.md')],+ 'skills/frontend-slides': [{ name: 'SKILL.md', path: 'skills/frontend-slides/SKILL.md', type: 'file', size: 10, download_url: 'x' }]+ }),+ 'frontend-slides'+ );+ assert.deepEqual(resolved, { path: 'skills/frontend-slides' });+});++test('.claude/skills/<name> and a bare <name> directory are probed as fallbacks', async () => {+ const viaClaude = await resolveRepoRootSkillDir(+ lister({+ '': [dir('.claude'), file('README.md')],+ '.claude/skills/demo': [{ name: 'SKILL.md', path: '.claude/skills/demo/SKILL.md', type: 'file', size: 1, download_url: 'x' }]+ }),+ 'demo'+ );+ assert.deepEqual(viaClaude, { path: '.claude/skills/demo' });++ const viaBare = await resolveRepoRootSkillDir(+ lister({+ '': [dir('demo'), file('README.md')],+ demo: [{ name: 'SKILL.md', path: 'demo/SKILL.md', type: 'file', size: 1, download_url: 'x' }]+ }),+ 'demo'+ );+ assert.deepEqual(viaBare, { path: 'demo' });+});++test('a candidate that 404s or lacks SKILL.md is skipped, not fatal', async () => {+ const resolved = await resolveRepoRootSkillDir(+ lister({+ '': [dir('skills'), dir('demo')],+ // skills/demo missing entirely (404); bare demo/ has the skill.+ demo: [{ name: 'SKILL.md', path: 'demo/SKILL.md', type: 'file', size: 1, download_url: 'x' }]+ }),+ 'demo'+ );+ assert.deepEqual(resolved, { path: 'demo' });+});++test('no SKILL.md anywhere is a refusal, before a single file downloads', async () => {+ const resolved = await resolveRepoRootSkillDir(+ lister({ '': [dir('src'), dir('docs'), file('README.md')] }),+ 'demo'+ );+ assert.equal(resolved.unsupported, true);+ assert.match(resolved.error, /SKILL\.md/);+});++test('a root listing failure is reported, and an unsafe entry name cannot crash the probe', async () => {+ const failed = await resolveRepoRootSkillDir(async () => { throw new Error('API rate limit exceeded'); }, 'demo');+ assert.match(failed.error, /rate limit/);+ const unsafe = await resolveRepoRootSkillDir(lister({ '': [dir('src')] }), '../../etc');+ assert.equal(unsafe.unsupported, true);+});+test('uninstall refuses anything outside a managed skills root', (t) => {const tmp = tmpdir(t);const victim = path.join(tmp, 'important-work');