Skip to content

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

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.ts
index 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.cjs
index 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');