Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(skills): list operator-pinned external skill repositories as clearly labelled, never auto-enabled community skills

nirholasdd69b9b4b1ed
diff --git a/api/_lib/community-skill-sources.js b/api/_lib/community-skill-sources.js
new file mode 100644
index 000000000..9a06d9947
--- /dev/null
+++ b/api/_lib/community-skill-sources.js
@@ -0,0 +1,298 @@
+// External community skill sources: public GitHub skill repositories an
+// operator has chosen to trust, pinned to a commit, merged into the community
+// skills API as a clearly separate "external" set.
+//
+// Trust model (the design constraint, not an afterthought):
+// - the list lives in runtime config (COMMUNITY_SKILL_SOURCES), never in code
+// - every source is pinned to a full commit sha; a branch name is rejected, so
+// the bytes behind a listing cannot change under a reader
+// - a skill is untrusted input. It is listed and previewable, never enabled
+// on an agent by this module. Importing is an explicit owner action that
+// goes through the scan and approval flow in skill-import-store.js
+// - a source that fails (404, timeout, rate limit) is logged and skipped; it
+// can never take the in-repo registry down, because the in-repo registry is
+// not read here
+//
+// COMMUNITY_SKILL_SOURCES is a JSON array:
+// [{ "repo": "owner/name", "ref": "<40-hex commit sha>", "path": "skills", "license": "<SPDX id>" }]
+
+import { createHash } from 'node:crypto';
+import { LIMITS, parseSkillMarkdown, estimateTokens } from '../../community-skills/tools/registry.mjs';
+
+export const TTL_MS = 5 * 60 * 1000;
+export const FAILURE_TTL_MS = 60 * 1000;
+export const MAX_SKILLS_PER_SOURCE = 100;
+export const FETCH_TIMEOUT_MS = 8000;
+const CONCURRENCY = 6;
+
+const REPO_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/[A-Za-z0-9._-]{1,100}$/;
+const SHA_RE = /^[0-9a-f]{40}$/;
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const TAG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const SPDX_RE = /^[A-Za-z0-9.+-]{2,40}$/;
+
+const defaultLog = (msg) => console.warn(`[community-skill-sources] ${msg}`);
+
+/**
+ * Parse and validate the env value. Returns { sources, problems }; an unset or
+ * empty value is { sources: [], problems: [] }. An invalid entry is dropped
+ * with a reason, never repaired.
+ */
+export function parseSources(raw) {
+ const text = String(raw ?? '').trim();
+ if (!text) return { sources: [], problems: [] };
+ let list;
+ try {
+ list = JSON.parse(text);
+ } catch (err) {
+ return { sources: [], problems: [`COMMUNITY_SKILL_SOURCES is not valid JSON: ${err.message}`] };
+ }
+ if (!Array.isArray(list)) return { sources: [], problems: ['COMMUNITY_SKILL_SOURCES must be a JSON array'] };
+ const sources = [];
+ const problems = [];
+ const seen = new Set();
+ list.forEach((item, i) => {
+ const at = `COMMUNITY_SKILL_SOURCES[${i}]`;
+ if (!item || typeof item !== 'object') return problems.push(`${at} must be an object`);
+ const { repo, ref, license } = item;
+ const path = item.path === undefined ? 'skills' : item.path;
+ if (typeof repo !== 'string' || !REPO_RE.test(repo)) return problems.push(`${at}.repo must be "owner/name"`);
+ if (typeof ref !== 'string' || !SHA_RE.test(ref)) return problems.push(`${at}.ref must be a full 40-character commit sha (a branch or tag is not pinned)`);
+ if (typeof license !== 'string' || !SPDX_RE.test(license)) return problems.push(`${at}.license must be an SPDX id such as "MIT"`);
+ const parts = typeof path === 'string' ? path.split('/').filter(Boolean) : null;
+ if (!parts || parts.some((p) => p === '.' || p === '..' || !/^[A-Za-z0-9._-]+$/.test(p))) {
+ return problems.push(`${at}.path must be a plain relative directory`);
+ }
+ const key = `${repo.toLowerCase()}@${ref}/${parts.join('/')}`;
+ if (seen.has(key)) return problems.push(`${at} duplicates an earlier source`);
+ seen.add(key);
+ sources.push({ repo, ref, path: parts.join('/'), license });
+ });
+ return { sources, problems };
+}
+
+function titleCase(slug) {
+ return slug
+ .split('-')
+ .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+ .join(' ');
+}
+
+function parseTags(value) {
+ if (typeof value !== 'string') return ['external'];
+ const tags = value
+ .replace(/^\[|\]$/g, '')
+ .split(',')
+ .map((t) => t.trim().replace(/^['"]|['"]$/g, '').toLowerCase())
+ .filter((t) => TAG_RE.test(t) && t.length <= LIMITS.tagMax);
+ const unique = [...new Set(tags)].slice(0, LIMITS.tagsMax);
+ return unique.length ? unique : ['external'];
+}
+
+/**
+ * Apply the registry's SKILL.md rules to one fetched file. Returns
+ * { entry } or { reason }. The metadata.json requirement is replaced by
+ * values derived from the source (author = repository owner, license = the
+ * operator-declared SPDX id); the SKILL.md rules are the same.
+ */
+export function validateExternalSkill({ slug, text, source }) {
+ if (!SLUG_RE.test(slug) || slug.length < LIMITS.slugMin || slug.length > LIMITS.slugMax) {
+ return { reason: `directory name "${slug}" is not a URL-safe slug of ${LIMITS.slugMin}-${LIMITS.slugMax} characters` };
+ }
+ const parsed = parseSkillMarkdown(text);
+ if (!parsed) return { reason: 'SKILL.md has no --- frontmatter block' };
+ const { name, description, version, tags } = parsed.data;
+ if (!name) return { reason: 'frontmatter is missing "name"' };
+ if (name !== slug) return { reason: `frontmatter name "${name}" must equal the directory name "${slug}"` };
+ if (!description) return { reason: 'frontmatter is missing "description"' };
+ if (description.length < LIMITS.descriptionMin) return { reason: 'description is too short to act as a trigger' };
+ if (description.length > LIMITS.descriptionMax) return { reason: `description is ${description.length} characters; the limit is ${LIMITS.descriptionMax}` };
+ const len = parsed.body.length;
+ if (len < LIMITS.bodyMinChars) return { reason: `body is ${len} characters; a useful skill needs at least ${LIMITS.bodyMinChars}` };
+ if (len > LIMITS.bodyMaxChars) return { reason: `body is ${len} characters; the limit is ${LIMITS.bodyMaxChars}` };
+ const [owner] = source.repo.split('/');
+ const base = `https://github.com/${source.repo}`;
+ return {
+ entry: {
+ slug,
+ name: titleCase(slug),
+ description,
+ author: owner,
+ tags: parseTags(tags),
+ version: version && SEMVER_RE.test(version) ? version : `0.0.0-${source.ref.slice(0, 7)}`,
+ license: source.license,
+ origin: 'external',
+ not_reviewed: true,
+ source: source.repo,
+ ref: source.ref,
+ path: `${source.path}/${slug}`,
+ source_url: `${base}/blob/${source.ref}/${source.path}/${slug}/SKILL.md`,
+ tree_url: `${base}/tree/${source.ref}/${source.path}/${slug}`,
+ bytes: Buffer.byteLength(text),
+ tokens: estimateTokens(parsed.body),
+ sha256: createHash('sha256').update(text).digest('hex'),
+ import: { registry: `${base}/tree/${source.ref}/${source.path}`, skill: slug },
+ },
+ content: text,
+ body: parsed.body,
+ };
+}
+
+async function getJson(fetchImpl, url, headers) {
+ const res = await fetchImpl(url, { headers, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+ if (!res.ok) throw new Error(`HTTP ${res.status} from ${new URL(url).host}`);
+ return res.json();
+}
+
+async function getText(fetchImpl, url) {
+ const res = await fetchImpl(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+ if (!res.ok) throw new Error(`HTTP ${res.status}`);
+ const text = await res.text();
+ if (Buffer.byteLength(text) > LIMITS.fileMaxBytes) throw new Error(`larger than ${LIMITS.fileMaxBytes} bytes`);
+ return text;
+}
+
+async function mapLimit(items, limit, fn) {
+ const out = new Array(items.length);
+ let next = 0;
+ await Promise.all(
+ Array.from({ length: Math.min(limit, items.length) }, async () => {
+ while (next < items.length) {
+ const i = next++;
+ out[i] = await fn(items[i]);
+ }
+ }),
+ );
+ return out;
+}
+
+/** Load one source at its pinned commit. Never throws: failure is { error }. */
+export async function loadSource(source, { fetchImpl = fetch, apiBase, rawBase, token, log = defaultLog } = {}) {
+ const result = { repo: source.repo, ref: source.ref, path: source.path, license: source.license, skills: [], dropped: [] };
+ try {
+ const headers = {
+ accept: 'application/vnd.github+json',
+ 'user-agent': 'three.ws-community-skills',
+ 'x-github-api-version': '2022-11-28',
+ ...(token ? { authorization: `Bearer ${token}` } : {}),
+ };
+ const tree = await getJson(fetchImpl, `${apiBase}/repos/${source.repo}/git/trees/${source.ref}?recursive=1`, headers);
+ if (!Array.isArray(tree.tree)) throw new Error('unexpected tree response');
+ if (tree.truncated) log(`${source.repo}@${source.ref.slice(0, 7)} tree listing was truncated; some skills may be missing`);
+ const prefix = `${source.path}/`;
+ const files = tree.tree.filter((n) => n.type === 'blob' && n.path.startsWith(prefix) && /^[^/]+\/SKILL\.md$/.test(n.path.slice(prefix.length)));
+ const picked = files.slice(0, MAX_SKILLS_PER_SOURCE);
+ if (files.length > picked.length) log(`${source.repo}: ${files.length - picked.length} skills beyond the ${MAX_SKILLS_PER_SOURCE} per-source cap were ignored`);
+ await mapLimit(picked, CONCURRENCY, async (node) => {
+ const slug = node.path.slice(prefix.length).split('/')[0];
+ try {
+ const text = await getText(fetchImpl, `${rawBase}/${source.repo}/${source.ref}/${node.path}`);
+ const verdict = validateExternalSkill({ slug, text, source });
+ if (verdict.entry) result.skills.push({ ...verdict.entry, content: verdict.content, body: verdict.body });
+ else {
+ result.dropped.push({ slug, reason: verdict.reason });
+ log(`dropped ${source.repo}/${slug}: ${verdict.reason}`);
+ }
+ } catch (err) {
+ result.dropped.push({ slug, reason: err.message });
+ log(`dropped ${source.repo}/${slug}: ${err.message}`);
+ }
+ });
+ result.skills.sort((a, b) => a.slug.localeCompare(b.slug));
+ } catch (err) {
+ result.error = err.name === 'TimeoutError' ? `timed out after ${FETCH_TIMEOUT_MS} ms` : err.message;
+ result.skills = [];
+ log(`source ${source.repo}@${source.ref.slice(0, 7)} failed to load: ${result.error}`);
+ }
+ return result;
+}
+
+const cache = { key: null, at: 0, ttl: TTL_MS, value: null };
+
+/** Test hook: forget the cached merge. */
+export function resetExternalCache() {
+ cache.key = null;
+ cache.value = null;
+}
+
+/**
+ * The merged external set. Disabled (and free) when the env var is unset.
+ * `reservedSlugs` are the in-repo slugs: an in-repo skill always wins a clash,
+ * and the first source wins a clash between two sources.
+ */
+export async function loadExternalSkills({
+ env = process.env,
+ fetchImpl = fetch,
+ now = Date.now,
+ reservedSlugs = new Set(),
+ log = defaultLog,
+} = {}) {
+ const raw = env.COMMUNITY_SKILL_SOURCES;
+ if (!raw || !String(raw).trim()) return { enabled: false, count: 0, skills: [], sources: [] };
+ const apiBase = (env.COMMUNITY_SKILL_GITHUB_API || 'https://api.github.com').replace(/\/+$/, '');
+ const rawBase = (env.COMMUNITY_SKILL_RAW_BASE || 'https://raw.githubusercontent.com').replace(/\/+$/, '');
+ const key = `${raw}|${apiBase}|${rawBase}`;
+ if (cache.key === key && cache.value && now() - cache.at < cache.ttl) return cache.value;
+
+ const { sources, problems } = parseSources(raw);
+ for (const p of problems) log(p);
+ const loaded = await Promise.all(
+ sources.map((s) => loadSource(s, { fetchImpl, apiBase, rawBase, token: env.GITHUB_TOKEN || env.GH_TOKEN, log })),
+ );
+ const taken = new Set(reservedSlugs);
+ const skills = [];
+ for (const src of loaded) {
+ for (const skill of src.skills) {
+ if (taken.has(skill.slug)) {
+ src.dropped.push({ slug: skill.slug, reason: 'slug already used by an earlier skill' });
+ log(`dropped ${src.repo}/${skill.slug}: slug already used by an earlier skill`);
+ continue;
+ }
+ taken.add(skill.slug);
+ skills.push(skill);
+ }
+ }
+ const value = {
+ enabled: true,
+ count: skills.length,
+ skills,
+ problems,
+ sources: loaded.map((s) => ({
+ repo: s.repo,
+ ref: s.ref,
+ path: s.path,
+ license: s.license,
+ url: `https://github.com/${s.repo}/tree/${s.ref}/${s.path}`,
+ loaded: !s.error,
+ ...(s.error ? { error: s.error } : {}),
+ count: s.skills.filter((k) => skills.includes(k)).length,
+ dropped: s.dropped,
+ })),
+ };
+ cache.key = key;
+ cache.at = now();
+ cache.ttl = loaded.some((s) => s.error) ? FAILURE_TTL_MS : TTL_MS;
+ cache.value = value;
+ return value;
+}
+
+/** Public shape: the entry without the file bodies. */
+export function publicExternal(skill) {
+ const { content, body, ...rest } = skill;
+ return rest;
+}
+
+/** Same filter semantics as the in-repo search: q words all match, tag and author are exact. */
+export function filterExternal(skills, { q = '', tag = '', author = '' } = {}) {
+ const needle = String(q || '').trim().toLowerCase();
+ const wantTag = String(tag || '').trim().toLowerCase();
+ const wantAuthor = String(author || '').trim().toLowerCase();
+ return skills.filter((s) => {
+ if (wantTag && !s.tags.includes(wantTag)) return false;
+ if (wantAuthor && s.author.toLowerCase() !== wantAuthor) return false;
+ if (!needle) return true;
+ const hay = `${s.slug} ${s.name} ${s.description} ${s.tags.join(' ')} ${s.author} ${s.source}`.toLowerCase();
+ return needle.split(/\s+/).every((word) => hay.includes(word));
+ });
+}
diff --git a/api/skills/community.js b/api/skills/community.js
index 66c33aad4..b424572d7 100644
--- a/api/skills/community.js
+++ b/api/skills/community.js
@@ -9,10 +9,19 @@
* validated by `npm run build:pages` and baked into the image, so a response
* only changes with a deploy and can be cached at the edge. Importing a skill
* onto an agent is POST /api/agents/:id/custom-skills { source: 'community', slug }.
+ *
+ * External sources (docs/community-skill-sources.md): when the operator sets
+ * COMMUNITY_SKILL_SOURCES, the list response gains an `external` object and the
+ * detail route also resolves external slugs. Those skills carry
+ * origin: "external", their source repository, pinned commit and license, are
+ * never merged into `skills`, and install only through the scan and approval
+ * flow (POST /api/skill-imports/scan). With the variable unset the response is
+ * byte-for-byte what it was before.
*/
import { cors, json, text, method, wrap, error } from '../_lib/http.js';
-import { searchCommunitySkills, getCommunitySkill } from '../_lib/community-skills.js';
+import { searchCommunitySkills, getCommunitySkill, loadRegistry } from '../_lib/community-skills.js';
+import { loadExternalSkills, filterExternal, publicExternal } from '../_lib/community-skill-sources.js';
const CACHE = { 'cache-control': 'public, max-age=300, stale-while-revalidate=3600' };
@@ -32,10 +41,21 @@ export default wrap(async (req, res) => {
author: url.searchParams.get('author') || '',
limit: Number.isFinite(limit) ? limit : 100,
});
- return json(res, 200, result, CACHE);
+ const external = await loadExternalSkills({ reservedSlugs: new Set(loadRegistry().skills.map((s) => s.slug)) });
+ if (!external.enabled) return json(res, 200, result, CACHE);
+ const matched = filterExternal(external.skills, {
+ q: url.searchParams.get('q') || '',
+ tag: url.searchParams.get('tag') || '',
+ author: url.searchParams.get('author') || '',
+ });
+ return json(res, 200, { ...result, external: { count: matched.length, total: external.count, sources: external.sources, skills: matched.map(publicExternal) } }, CACHE);
}
- const skill = getCommunitySkill(slug);
+ let skill = getCommunitySkill(slug);
+ if (!skill) {
+ const external = await loadExternalSkills({ reservedSlugs: new Set(loadRegistry().skills.map((s) => s.slug)) });
+ skill = external.skills.find((s) => s.slug === slug) || null;
+ }
if (!skill) return error(res, 404, 'not_found', `no community skill "${slug}"`);
if (url.searchParams.get('format') === 'md') {
return text(res, 200, skill.content, { ...CACHE, 'content-type': 'text/markdown; charset=utf-8' });
diff --git a/community-skills/README.md b/community-skills/README.md
index fdd015ae0..59b11286a 100644
--- a/community-skills/README.md
+++ b/community-skills/README.md
@@ -72,6 +72,38 @@ curl -s -X POST https://three.ws/api/agents/<agent-id>/custom-skills \
Enabled skills are added to the agent's system prompt in the order they were installed, inside a budget of 6,000 tokens per agent. A skill that would overflow the budget is skipped whole, never cut off mid-instruction, and the agent's skills page shows which ones are active. That is why a single community skill is capped at 12,000 characters (about 3,000 tokens): at least two always fit side by side.
+## External sources (operator-configured)
+
+The registry in this directory is reviewed: every skill is committed here and passes `tools/validate.mjs`. An operator can additionally list skills from public third-party GitHub repositories. These are **external** skills and are kept apart from the reviewed registry everywhere they appear.
+
+Trust model:
+
+- A skill is a set of instructions an agent follows, so an external skill is untrusted input.
+- Every source is **pinned to a full commit sha**. A branch or tag name is rejected, so the bytes behind a listing cannot change under a reader.
+- External skills carry `origin: "external"`, `not_reviewed: true`, their source repository, the pinned commit, their license and a link to that exact commit. `/skills/community` shows them in their own section with a "not reviewed by three.ws" notice.
+- Nothing enables an external skill on an agent automatically. Installing is an explicit owner action that goes through the scanner and an approval step (`POST /api/skill-imports/scan`, then approve), the same flow as `/skills/import`. A skill that asks to spend, sign or send messages also needs the owner to acknowledge the spend gate.
+- `three-ws skills import <slug> --agent <id>` prints the source and commit for an external skill and asks for confirmation. With no terminal it refuses unless you pass `--yes`; a gated skill also needs `--acknowledge-gated`.
+- A source that fails to load (404, rate limit, timeout) is logged and skipped. The reviewed registry never depends on it.
+
+Each external `SKILL.md` must pass the same frontmatter rules as ours (`name` equal to its directory, a `description` of 20 to 400 characters, a body of 200 to 12,000 characters, a URL-safe slug). A file that does not is dropped with a logged reason, and the rules are never loosened to admit it. Author comes from the repository owner and license from the operator's declaration; `tags` and `version` are read from the frontmatter when present. A slug that clashes with a reviewed skill, or with an earlier source, is dropped.
+
+Operator setup: set one environment variable on the API service, a JSON array.
+
+```bash
+COMMUNITY_SKILL_SOURCES='[{"repo":"owner/name","ref":"<40-hex commit sha>","path":"skills","license":"Apache-2.0"}]'
+```
+
+| Field | Meaning |
+| --- | --- |
+| `repo` | `owner/name` of a public GitHub repository |
+| `ref` | full commit sha to pin to (required) |
+| `path` | directory holding one folder per skill, each with a `SKILL.md` (default `skills`) |
+| `license` | SPDX id of the repository license (MIT, Apache-2.0 or BSD for anything worth listing) |
+
+The tree is listed through the public GitHub API and bodies are read from `raw.githubusercontent.com` at the pinned commit; set `GITHUB_TOKEN` to lift the unauthenticated rate limit. The merged result is cached in memory for five minutes (one minute after a failure). With the variable unset, `/api/skills/community` and `/skills/community` behave exactly as before. To apply a change: `gcloud run services update three-ws-api --region us-central1 --update-env-vars COMMUNITY_SKILL_SOURCES=...` (never `--set-env-vars`, which replaces the whole environment).
+
+The list response gains an `external` object (`count`, `total`, `sources` with per-source load status and dropped skills with reasons, and `skills`), and `GET /api/skills/community/<slug>` also resolves external slugs. Code: `api/_lib/community-skill-sources.js`; tests: `tests/community-skill-sources.test.js`.
+
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md). In short: add a folder under `skills/`, run `node tools/validate.mjs`, open a pull request.
diff --git a/packages/three-ws-cli/src/commands/skills.js b/packages/three-ws-cli/src/commands/skills.js
index 64694d120..801bc5c1a 100644
--- a/packages/three-ws-cli/src/commands/skills.js
+++ b/packages/three-ws-cli/src/commands/skills.js
@@ -5,7 +5,7 @@
// three-ws skills list [--tag <tag>] [--author <name>]
// three-ws skills search <query>
// three-ws skills show <slug>
-// three-ws skills import <slug> --agent <agent-id> [--disabled]
+// three-ws skills import <slug> --agent <agent-id> [--disabled] [--yes] [--acknowledge-gated]
// three-ws skills import <url-or-owner/repo>
// three-ws skills installed --agent <agent-id>
// three-ws skills drafts
@@ -22,16 +22,22 @@ import { requestJson, ApiError } from '../http.js';
import { bearerFor } from '../oauth.js';
import { readStore, resolveOrigin } from '../store.js';
import { systemEnv } from '../paths.js';
+import { createInterface } from 'node:readline/promises';
export const SKILLS_USAGE = `Usage:
three-ws skills list [--tag <tag>] [--author <name>] [--json]
three-ws skills search <query> [--json]
three-ws skills show <slug> [--json]
- three-ws skills import <slug> --agent <agent-id> [--disabled] [--json]
+ three-ws skills import <slug> --agent <agent-id> [--disabled] [--yes] [--acknowledge-gated] [--json]
three-ws skills import <openapi-url-or-owner/repo> [--json]
three-ws skills installed --agent <agent-id> [--json]
three-ws skills drafts [--json]
+An external skill (origin: external) comes from a third-party repository that
+three.ws has not reviewed. Importing one prints its source and pinned commit and
+asks you to confirm; without a terminal, pass --yes. It is scanned first, and a
+skill that asks to spend, sign or message also needs --acknowledge-gated.
+
Browse every skill: https://three.ws/skills/community`;
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -97,11 +103,78 @@ export function formatInstalled({ skills, budget }) {
return [head, `${pad('SLUG', 24)} ${pad('TOKENS', 7)} ${pad('STATE', 12)} ID`, ...rows].join('\n');
}
+/** The external skill with this slug, or null when the slug is unknown or in-repo. */
+async function externalSkill(origin, slug) {
+ try {
+ const { skill } = await requestJson(`${origin}/api/skills/community/${encodeURIComponent(slug)}`);
+ return skill?.origin === 'external' ? skill : null;
+ } catch (err) {
+ if (err instanceof ApiError && err.status === 404) return null;
+ throw err;
+ }
+}
+
+/** Ask on the terminal. Without one, the answer is no: an external skill never installs unattended. */
+async function askYesNo(question) {
+ if (!process.stdin.isTTY || !process.stderr.isTTY) return false;
+ const rl = createInterface({ input: process.stdin, output: process.stderr });
+ try {
+ return /^y(es)?$/i.test((await rl.question(`${question} [y/N] `)).trim());
+ } finally {
+ rl.close();
+ }
+}
+
+/** The notice shown before an external skill is installed. */
+export function externalNotice(skill) {
+ return [
+ `${skill.name} (${skill.slug}) is an EXTERNAL skill, not reviewed by three.ws.`,
+ ` Source: ${skill.source}`,
+ ` Commit: ${skill.ref}`,
+ ` License: ${skill.license}`,
+ ` Read it: ${skill.tree_url}`,
+ 'It is a set of instructions your agent will follow. It is scanned before install and never enabled automatically.',
+ ].join('\n');
+}
+
+/** Scan an external skill at its pinned commit, then approve exactly the scanned bytes. */
+async function importExternal({ skill, agent, headers, origin, flags, confirm }) {
+ const notice = externalNotice(skill);
+ if (!flags.yes && !(await confirm(`${notice}\nInstall onto agent ${agent}?`))) {
+ return {
+ code: 1,
+ output: `${notice}\n\nNot installed. Re-run with --yes to confirm (required when there is no terminal).`,
+ };
+ }
+ const { data: scanned } = await requestJson(`${origin}/api/skill-imports/scan`, {
+ method: 'POST',
+ headers,
+ json: { agent_id: agent, registry: skill.import.registry, skill: skill.import.skill },
+ });
+ const request = scanned.request;
+ if (request.status === 'refused' || request.verdict === 'refused') {
+ return { code: 1, output: `${notice}\n\nThe scan refused this skill (${request.verdict}); it was not installed. Details: ${origin}/skills/import` };
+ }
+ if (request.gated && !flags['acknowledge-gated']) {
+ return {
+ code: 1,
+ output: `${notice}\n\nThis skill asks to spend, sign or send messages. It stays under the spend gate and needs --acknowledge-gated to install. Review the scan at ${origin}/skills/import first.`,
+ request,
+ };
+ }
+ const { data } = await requestJson(`${origin}/api/skill-imports/requests/${request.id}`, {
+ method: 'POST',
+ headers,
+ json: { decision: 'approve', acknowledge_gated: Boolean(flags['acknowledge-gated']), enabled: !flags.disabled },
+ });
+ return { code: 0, data, installed: data.skill, notice };
+}
+
/**
* Run a `skills` subcommand. Returns { code, output } so the dispatcher decides
* where it goes; nothing here writes to stdout directly.
*/
-export async function runSkills(argv, { env = systemEnv(), origin: originFlag } = {}) {
+export async function runSkills(argv, { env = systemEnv(), origin: originFlag, confirm = askYesNo } = {}) {
const { sub, args, flags } = parseSkillsArgs(argv);
const origin = resolveOrigin({ flag: originFlag || flags.origin, env, store: readStore(env) });
const json = Boolean(flags.json);
@@ -177,6 +250,18 @@ export async function runSkills(argv, { env = systemEnv(), origin: originFlag }
: 'saved, disabled';
return done(data, `Imported ${skill.name} (${skill.slug}) onto ${agent}: ${state}.\nBudget: ${budget.used_tokens} / ${budget.cap_tokens} tokens.\nManage: ${origin}/skills/community?agent=${agent}`);
} catch (err) {
+ if (err instanceof ApiError && (err.code === 'not_found' || err.status === 404)) {
+ const external = await externalSkill(origin, args[0]);
+ if (external) {
+ const result = await importExternal({ skill: external, agent, headers, origin, flags, confirm });
+ if (result.code !== 0) return result;
+ const skill = result.installed;
+ return done(
+ result.data,
+ `${result.notice}\n\nImported ${external.name} (${external.slug}) onto ${agent}${skill?.injected ? ': active in the agent\'s next reply' : ': saved, disabled or over budget'}.\nManage: ${origin}/skills/community?agent=${agent}`,
+ );
+ }
+ }
if (err instanceof ApiError && err.code === 'already_installed') {
return { code: 1, output: `${args[0]} is already installed on this agent (skill ${err.body?.skill_id}). Manage it at ${origin}/skills/community?agent=${agent}` };
}
diff --git a/packages/three-ws-cli/tests/skills.test.js b/packages/three-ws-cli/tests/skills.test.js
index 2ea335a3f..5a4cd1f63 100644
--- a/packages/three-ws-cli/tests/skills.test.js
+++ b/packages/three-ws-cli/tests/skills.test.js
@@ -154,3 +154,91 @@ describe('three-ws skills drafts', () => {
expect(out).toContain('three-ws skills import');
});
});
+
+describe('three-ws skills import <external slug>', () => {
+ const agent = '11111111-1111-4111-8111-111111111111';
+ const SHA = 'c'.repeat(40);
+ const EXTERNAL = {
+ slug: 'fixture-skill',
+ name: 'Fixture Skill',
+ origin: 'external',
+ source: 'fixture-org/skills-repo',
+ ref: SHA,
+ license: 'MIT',
+ tree_url: `https://github.com/fixture-org/skills-repo/tree/${SHA}/skills/fixture-skill`,
+ import: { registry: `https://github.com/fixture-org/skills-repo/tree/${SHA}/skills`, skill: 'fixture-skill' },
+ };
+ const notFound = () => reply(404, { error: 'not_found', error_description: 'no community skill "fixture-skill"' });
+ let env;
+ let fetchMock;
+ let ttyDescriptors;
+
+ beforeEach(() => {
+ env = tempEnv();
+ writeStore({ origin: ORIGIN, auth: { type: 'apikey', key: KEY, prefix: KEY.slice(0, 12) } }, env);
+ fetchMock = vi.fn();
+ vi.stubGlobal('fetch', fetchMock);
+ ttyDescriptors = ['stdin', 'stderr'].map((n) => [n, Object.getOwnPropertyDescriptor(process[n], 'isTTY')]);
+ for (const [n] of ttyDescriptors) Object.defineProperty(process[n], 'isTTY', { value: false, configurable: true });
+ });
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ for (const [n, d] of ttyDescriptors) {
+ if (d) Object.defineProperty(process[n], 'isTTY', d);
+ else delete process[n].isTTY;
+ }
+ });
+
+ it('refuses without --yes in a non-interactive shell, printing source and commit, and installs nothing', async () => {
+ fetchMock.mockResolvedValueOnce(notFound()).mockResolvedValueOnce(reply(200, { skill: EXTERNAL }));
+ const { code, out } = await run(['skills', 'import', 'fixture-skill', '--agent', agent, '--origin', ORIGIN], env);
+ expect(code).toBe(1);
+ expect(out).toBe('');
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(fetchMock.mock.calls.map(([u]) => u)).not.toContain(`${ORIGIN}/api/skill-imports/scan`);
+ });
+
+ it('prints the source, commit and license in the refusal text', async () => {
+ fetchMock.mockResolvedValueOnce(notFound()).mockResolvedValueOnce(reply(200, { skill: EXTERNAL }));
+ const { runSkills } = await import('../src/commands/skills.js');
+ const result = await runSkills(['import', 'fixture-skill', '--agent', agent], { env, origin: ORIGIN });
+ expect(result.code).toBe(1);
+ expect(result.output).toContain('fixture-org/skills-repo');
+ expect(result.output).toContain(SHA);
+ expect(result.output).toContain('not reviewed by three.ws');
+ expect(result.output).toContain('--yes');
+ });
+
+ it('with --yes scans at the pinned commit, then approves the scanned request', async () => {
+ fetchMock
+ .mockResolvedValueOnce(notFound())
+ .mockResolvedValueOnce(reply(200, { skill: EXTERNAL }))
+ .mockResolvedValueOnce(reply(201, { data: { request: { id: 'r1', status: 'pending', verdict: 'clean', gated: false } } }))
+ .mockResolvedValueOnce(reply(200, { data: { skill: { id: 's9', slug: 'fixture-skill', injected: true }, budget: { used_tokens: 5, cap_tokens: 100 } } }));
+ const { code } = await run(['skills', 'import', 'fixture-skill', '--agent', agent, '--yes', '--json', '--origin', ORIGIN], env);
+ expect(code).toBe(0);
+ const [scanUrl, scanInit] = fetchMock.mock.calls[2];
+ expect(scanUrl).toBe(`${ORIGIN}/api/skill-imports/scan`);
+ expect(JSON.parse(scanInit.body)).toEqual({ agent_id: agent, registry: EXTERNAL.import.registry, skill: 'fixture-skill' });
+ const [approveUrl, approveInit] = fetchMock.mock.calls[3];
+ expect(approveUrl).toBe(`${ORIGIN}/api/skill-imports/requests/r1`);
+ expect(JSON.parse(approveInit.body)).toMatchObject({ decision: 'approve', acknowledge_gated: false, enabled: true });
+ });
+
+ it('does not approve a gated skill without --acknowledge-gated', async () => {
+ fetchMock
+ .mockResolvedValueOnce(notFound())
+ .mockResolvedValueOnce(reply(200, { skill: EXTERNAL }))
+ .mockResolvedValueOnce(reply(201, { data: { request: { id: 'r2', status: 'pending', verdict: 'caution', gated: true } } }));
+ const { runSkills } = await import('../src/commands/skills.js');
+ const result = await runSkills(['import', 'fixture-skill', '--agent', agent, '--yes'], { env, origin: ORIGIN });
+ expect(result.code).toBe(1);
+ expect(result.output).toContain('--acknowledge-gated');
+ expect(fetchMock).toHaveBeenCalledTimes(3);
+ });
+
+ it('reports a slug that is neither in-repo nor external as the original not-found error', async () => {
+ fetchMock.mockResolvedValueOnce(notFound()).mockResolvedValueOnce(notFound());
+ await expect(run(['skills', 'import', 'fixture-skill', '--agent', agent, '--yes', '--origin', ORIGIN], env)).rejects.toMatchObject({ status: 404, code: 'not_found' });
+ });
+});
diff --git a/pages/skills-community.html b/pages/skills-community.html
index 884b8fc57..337d08021 100644
--- a/pages/skills-community.html
+++ b/pages/skills-community.html
@@ -83,6 +83,12 @@
<nav class="sc-tags" id="sc-tags" aria-label="Filter by tag"></nav>
<div class="sc-grid" id="sc-grid" aria-busy="true"></div>
<div id="sc-browse-state"></div>
+ <section class="sc-external" id="sc-external" aria-labelledby="sc-external-title" hidden>
+ <h2 class="sc-h2" id="sc-external-title">External skills</h2>
+ <p class="sc-note">Pulled from third-party repositories the operator chose to list, each pinned to one commit. <strong>Not reviewed by three.ws.</strong> They are never enabled on an agent automatically: you read one, then scan and approve it yourself.</p>
+ <div class="sc-grid" id="sc-external-grid"></div>
+ <p class="sc-note" id="sc-external-sources"></p>
+ </section>
</section>
<section id="sc-mine" role="tabpanel" aria-labelledby="sc-tab-mine" hidden>
diff --git a/src/skills-community.css b/src/skills-community.css
index 8a7b562f9..13122ab2e 100644
--- a/src/skills-community.css
+++ b/src/skills-community.css
@@ -445,6 +445,38 @@
color: var(--accent, #a78bfa);
}
+/* ── external skills ──────────────────────────────────────────────────── */
+
+.sc-external {
+ margin-top: var(--space-xl, 40px);
+}
+
+.sc-badge-external {
+ border-color: color-mix(in srgb, var(--warn, #f59e0b) 55%, transparent);
+ color: var(--warn, #f59e0b);
+}
+
+.sc-card-source {
+ position: relative;
+ z-index: 1;
+ font-size: var(--text-xs, 12px);
+ color: var(--ink-dim, rgba(255, 255, 255, 0.6));
+ overflow-wrap: anywhere;
+}
+
+.sc-card-source a {
+ color: inherit;
+ text-decoration: underline;
+}
+
+.sc-external-scan {
+ margin: var(--space-sm, 12px) 0 0;
+ padding: var(--space-sm, 12px);
+ border: 1px solid var(--line, rgba(255, 255, 255, 0.12));
+ border-radius: var(--radius, 10px);
+ font-size: var(--text-sm, 14px);
+}
+
/* ── skeletons + states ───────────────────────────────────────────────── */
.sc-skeleton span,
diff --git a/src/skills-community.js b/src/skills-community.js
index ea2b819c5..40ee273db 100644
--- a/src/skills-community.js
+++ b/src/skills-community.js
@@ -195,6 +195,107 @@ function renderGrid() {
actions: '<button type="button" class="sc-btn sc-btn-primary" data-action="clear-filters">Clear filters</button><a class="sc-btn" href="https://github.com/nirholas/three.ws/blob/main/community-skills/CONTRIBUTING.md" rel="noopener">Contribute a skill</a>',
});
announce(`${list.length} of ${state.registry.total} skills shown`);
+ renderExternal();
+}
+
+// ── external skills (operator-pinned third-party repositories) ───────────
+
+function matchesExternal(s) {
+ if (state.tag && !s.tags.includes(state.tag)) return false;
+ if (state.author && s.author !== state.author) return false;
+ if (!state.q) return true;
+ const hay = `${s.slug} ${s.name} ${s.description} ${s.tags.join(' ')} ${s.author} ${s.source}`.toLowerCase();
+ return state.q.toLowerCase().split(/\s+/).filter(Boolean).every((w) => hay.includes(w));
+}
+
+function externalCardHtml(s) {
+ return `<article class="sc-card">
+ <button type="button" class="sc-card-hit" data-open="${esc(s.slug)}" aria-label="Preview ${esc(s.name)} (external, not reviewed by three.ws)"></button>
+ <header class="sc-card-head">
+ <h3 class="sc-card-title">${esc(s.name)}</h3>
+ <span class="sc-badge sc-badge-external">External</span>
+ </header>
+ <p class="sc-card-desc">${esc(s.description)}</p>
+ <p class="sc-card-source">Not reviewed by three.ws. From <a href="${esc(s.tree_url)}" rel="noopener noreferrer" target="_blank">${esc(s.source)} @ ${esc(s.ref.slice(0, 7))}</a>, ${esc(s.license)}</p>
+ <footer class="sc-card-foot">
+ <span title="Approximate prompt size">~${fmtTokens(s.tokens)} tokens</span>
+ </footer>
+ </article>`;
+}
+
+function renderExternal() {
+ const ext = state.registry?.external;
+ const section = $('sc-external');
+ if (!ext) {
+ section.hidden = true;
+ return;
+ }
+ section.hidden = false;
+ const list = ext.skills.filter(matchesExternal);
+ $('sc-external-grid').innerHTML = list.length
+ ? list.map(externalCardHtml).join('')
+ : stateBlock({
+ title: ext.total ? 'No external skills match' : 'No external skills loaded',
+ body: ext.total ? 'Clear the filters to see every external skill.' : 'The listed external sources returned no valid skills right now. The reviewed registry above is unaffected.',
+ });
+ const failed = ext.sources.filter((src) => !src.loaded);
+ $('sc-external-sources').innerHTML =
+ `Sources: ${ext.sources.map((src) => `<a href="${esc(src.url)}" rel="noopener noreferrer" target="_blank">${esc(src.repo)} @ ${esc(src.ref.slice(0, 7))}</a> (${esc(src.license)})`).join(', ')}.` +
+ (failed.length ? ` ${failed.length} source${failed.length === 1 ? '' : 's'} could not be reached and ${failed.length === 1 ? 'is' : 'are'} skipped for now.` : '');
+}
+
+async function scanExternal(skill, agentId) {
+ const note = $('sc-import-note');
+ const btn = $('sc-import-go');
+ btn.disabled = true;
+ btn.textContent = 'Scanning…';
+ note.className = 'sc-import-note';
+ try {
+ const { data } = await readJson(await apiFetch('/api/skill-imports/scan', {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ agent_id: agentId, registry: skill.import.registry, skill: skill.import.skill }),
+ }));
+ const req = data.request;
+ if (req.verdict === 'refused') {
+ note.classList.add('is-error');
+ note.textContent = 'The scan refused this skill, so it cannot be installed.';
+ btn.textContent = 'Scan and review';
+ btn.disabled = false;
+ return;
+ }
+ note.classList.add(req.gated ? 'is-warn' : 'is-ok');
+ note.innerHTML = `Scanned at commit ${esc(skill.ref.slice(0, 7))}: ${esc(req.verdict)}.${req.gated ? ' It asks to spend, sign or send messages and would stay under the spend gate.' : ''}
+ <span class="sc-ctas"><button type="button" class="sc-btn sc-btn-primary" data-approve="${esc(req.id)}" data-gated="${req.gated ? '1' : ''}">Approve and install</button><button type="button" class="sc-btn" data-refuse="${esc(req.id)}">Cancel</button></span>`;
+ btn.textContent = 'Scan again';
+ btn.disabled = false;
+ } catch (err) {
+ note.classList.add('is-error');
+ note.textContent = err.message;
+ btn.textContent = 'Scan and review';
+ btn.disabled = false;
+ }
+}
+
+async function decideExternal(requestId, decision, gated) {
+ const note = $('sc-import-note');
+ note.className = 'sc-import-note';
+ try {
+ const { data } = await readJson(await apiFetch(`/api/skill-imports/requests/${encodeURIComponent(requestId)}`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ decision, acknowledge_gated: Boolean(gated) }),
+ }));
+ if (decision === 'refuse') {
+ note.textContent = 'Cancelled. Nothing was installed.';
+ return;
+ }
+ note.classList.add(data.skill?.injected ? 'is-ok' : 'is-warn');
+ note.textContent = data.skill?.injected ? 'Installed. Your agent follows it from its next reply.' : 'Installed, but it is disabled or over the agent\'s token budget.';
+ } catch (err) {
+ note.classList.add(err.code === 'already_installed' ? 'is-warn' : 'is-error');
+ note.textContent = err.code === 'already_installed' ? 'This agent already has this skill.' : err.message;
+ }
}
// ── preview + import ──────────────────────────────────────────────────────
@@ -231,13 +332,15 @@ async function openPreview(slug) {
return;
}
if (state.openSlug !== slug) return;
- $('sc-preview-kicker').textContent = `${skill.slug} · v${skill.version}`;
+ const external = skill.origin === 'external';
+ $('sc-preview-kicker').textContent = external ? `${skill.slug} · external, not reviewed by three.ws` : `${skill.slug} · v${skill.version}`;
$('sc-preview-title').textContent = skill.name;
$('sc-preview-desc').textContent = skill.description;
- const files = [...skill.scripts, ...skill.references];
+ const files = [...(skill.scripts || []), ...(skill.references || [])];
$('sc-preview-meta').innerHTML = `
<span class="sc-meta">by <strong>${esc(skill.author)}</strong></span>
<span class="sc-meta">${esc(skill.license)}</span>
+ ${external ? `<span class="sc-meta"><span class="sc-badge sc-badge-external">External</span> <a href="${esc(skill.tree_url)}" rel="noopener noreferrer" target="_blank">${esc(skill.source)} @ ${esc(skill.ref.slice(0, 7))}</a></span>` : ''}
<span class="sc-meta" title="Counted against the agent's prompt budget">~${fmtTokens(skill.tokens)} tokens</span>
${files.length ? `<span class="sc-meta">${files.map((f) => `<code>${esc(f)}</code>`).join(' ')}</span>` : ''}
<span class="sc-meta-actions">
@@ -275,10 +378,11 @@ async function renderImport(skill) {
return;
}
const preselect = agents.some((a) => a.id === state.agentId) ? state.agentId : agents[0].id;
+ const external = skill.origin === 'external';
box.innerHTML = `<form class="sc-import-row" data-import="${esc(skill.slug)}">
<label class="sr-only" for="sc-import-agent">Agent to import onto</label>
<select class="sc-select" id="sc-import-agent">${agents.map((a) => `<option value="${esc(a.id)}"${a.id === preselect ? ' selected' : ''}>${esc(a.name)}</option>`).join('')}</select>
- <button type="submit" class="sc-btn sc-btn-primary" id="sc-import-go">Import to agent</button>
+ <button type="submit" class="sc-btn sc-btn-primary" id="sc-import-go">${external ? 'Scan and review' : 'Import to agent'}</button>
</form>
<p class="sc-import-note" id="sc-import-note" role="status"></p>`;
}
@@ -700,8 +804,10 @@ function bind() {
});
document.addEventListener('click', (e) => {
- const el = e.target.closest('[data-open],[data-tag],[data-view],[data-action],[data-edit],[data-delete],[data-resync],[data-manage]');
+ const el = e.target.closest('[data-open],[data-tag],[data-view],[data-action],[data-edit],[data-delete],[data-resync],[data-manage],[data-approve],[data-refuse]');
if (!el) return;
+ if (el.dataset.approve) return void decideExternal(el.dataset.approve, 'approve', el.dataset.gated === '1');
+ if (el.dataset.refuse) return void decideExternal(el.dataset.refuse, 'refuse', false);
if (el.dataset.manage) {
e.preventDefault();
closePreview();
@@ -752,7 +858,9 @@ function bind() {
const form = e.target.closest('[data-import]');
if (!form) return;
e.preventDefault();
- doImport(form.dataset.import, $('sc-import-agent').value);
+ const skill = state.details.get(form.dataset.import);
+ if (skill?.origin === 'external') scanExternal(skill, $('sc-import-agent').value);
+ else doImport(form.dataset.import, $('sc-import-agent').value);
});
}
diff --git a/tests/community-skill-sources.test.js b/tests/community-skill-sources.test.js
new file mode 100644
index 000000000..4d8d5fea9
--- /dev/null
+++ b/tests/community-skill-sources.test.js
@@ -0,0 +1,220 @@
+// External community skill sources: env parsing, validation, the merged API
+// response, failure isolation and the unset-means-unchanged guarantee. The
+// "GitHub" here is a local HTTP server serving a synthetic repository, so no
+// test touches the network or names a real third-party repository.
+
+import { describe, it, expect, beforeAll, afterAll, beforeEach, vi } from 'vitest';
+import { createServer } from 'node:http';
+import handler from '../api/skills/community.js';
+import { parseSources, loadExternalSkills, resetExternalCache, validateExternalSkill } from '../api/_lib/community-skill-sources.js';
+
+const SHA = 'a'.repeat(40);
+const OTHER_SHA = 'b'.repeat(40);
+const GOOD_BODY = 'Follow these steps carefully. '.repeat(12);
+
+const skillMd = (name, description, body = GOOD_BODY, extra = '') => `---\nname: ${name}\ndescription: ${description}\n${extra}---\n${body}\n`;
+
+const FILES = {
+ 'skills/alpha-skill/SKILL.md': skillMd('alpha-skill', 'Does the alpha thing for an agent in a careful way.', GOOD_BODY, 'tags: [alpha, demo]\nversion: 2.1.0\n'),
+ 'skills/beta-skill/SKILL.md': skillMd('beta-skill', 'Does the beta thing for an agent in a careful way.'),
+ 'skills/wrong-name/SKILL.md': skillMd('something-else', 'Frontmatter name does not match the directory.'),
+ 'skills/tiny-body/SKILL.md': skillMd('tiny-body', 'This skill has a body that is far too short.', 'short'),
+ 'skills/agent-hiring/SKILL.md': skillMd('agent-hiring', 'Clashes with a skill that ships in the repo registry.'),
+};
+
+let server;
+let base;
+const hits = [];
+let mode = 'ok';
+
+beforeAll(async () => {
+ server = createServer((req, res) => {
+ hits.push(req.url);
+ if (mode === 'down') {
+ res.statusCode = 503;
+ return res.end('unavailable');
+ }
+ const treeMatch = req.url.match(/^\/repos\/fixture-org\/skills-repo\/git\/trees\/([0-9a-f]{40})\?recursive=1$/);
+ if (treeMatch && treeMatch[1] === SHA) {
+ res.setHeader('content-type', 'application/json');
+ return res.end(JSON.stringify({ truncated: false, tree: Object.keys(FILES).map((path) => ({ path, type: 'blob' })) }));
+ }
+ const rawMatch = req.url.match(/^\/fixture-org\/skills-repo\/([0-9a-f]{40})\/(.+)$/);
+ if (rawMatch && rawMatch[1] === SHA && FILES[rawMatch[2]]) return res.end(FILES[rawMatch[2]]);
+ res.statusCode = 404;
+ res.end('not found');
+ });
+ await new Promise((r) => server.listen(0, '127.0.0.1', r));
+ base = `http://127.0.0.1:${server.address().port}`;
+});
+
+afterAll(() => new Promise((r) => server.close(r)));
+
+const ENV_KEYS = ['COMMUNITY_SKILL_SOURCES', 'COMMUNITY_SKILL_GITHUB_API', 'COMMUNITY_SKILL_RAW_BASE'];
+const saved = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+
+function setSources(list) {
+ process.env.COMMUNITY_SKILL_SOURCES = JSON.stringify(list);
+ process.env.COMMUNITY_SKILL_GITHUB_API = base;
+ process.env.COMMUNITY_SKILL_RAW_BASE = base;
+}
+
+beforeEach(() => {
+ for (const k of ENV_KEYS) {
+ if (saved[k] === undefined) delete process.env[k];
+ else process.env[k] = saved[k];
+ }
+ delete process.env.COMMUNITY_SKILL_SOURCES;
+ resetExternalCache();
+ hits.length = 0;
+ mode = 'ok';
+ vi.restoreAllMocks();
+});
+
+function makeRes() {
+ return {
+ statusCode: 0,
+ body: '',
+ headers: {},
+ setHeader(k, v) { this.headers[String(k).toLowerCase()] = v; },
+ getHeader(k) { return this.headers[String(k).toLowerCase()]; },
+ removeHeader(k) { delete this.headers[String(k).toLowerCase()]; },
+ get headersSent() { return false; },
+ get writableEnded() { return false; },
+ end(chunk) { if (chunk) this.body += chunk; return this; },
+ };
+}
+
+async function get(url) {
+ const res = makeRes();
+ await handler({ method: 'GET', url, headers: { origin: 'https://three.ws' } }, res);
+ return { status: res.statusCode, json: res.body && res.headers['content-type']?.includes('json') ? JSON.parse(res.body) : null, text: res.body };
+}
+
+describe('parseSources', () => {
+ it('treats unset and empty as no sources', () => {
+ expect(parseSources(undefined)).toEqual({ sources: [], problems: [] });
+ expect(parseSources(' ')).toEqual({ sources: [], problems: [] });
+ });
+ it('accepts a pinned source and defaults the path', () => {
+ const { sources, problems } = parseSources(JSON.stringify([{ repo: 'fixture-org/skills-repo', ref: SHA, license: 'MIT' }]));
+ expect(problems).toEqual([]);
+ expect(sources).toEqual([{ repo: 'fixture-org/skills-repo', ref: SHA, path: 'skills', license: 'MIT' }]);
+ });
+ it('rejects an unpinned ref, a traversal path, a bad repo and a missing license', () => {
+ const { sources, problems } = parseSources(
+ JSON.stringify([
+ { repo: 'o/r', ref: 'main', license: 'MIT' },
+ { repo: 'o/r', ref: SHA, path: '../x', license: 'MIT' },
+ { repo: 'not a repo', ref: SHA, license: 'MIT' },
+ { repo: 'o/r', ref: SHA },
+ ]),
+ );
+ expect(sources).toEqual([]);
+ expect(problems).toHaveLength(4);
+ expect(problems[0]).toMatch(/commit sha/);
+ });
+ it('reports invalid JSON and non-arrays without throwing', () => {
+ expect(parseSources('{').problems[0]).toMatch(/not valid JSON/);
+ expect(parseSources('{}').problems[0]).toMatch(/array/);
+ });
+});
+
+describe('validateExternalSkill', () => {
+ const source = { repo: 'fixture-org/skills-repo', ref: SHA, path: 'skills', license: 'MIT' };
+ it('applies the registry SKILL.md rules', () => {
+ expect(validateExternalSkill({ slug: 'ok-skill', text: skillMd('ok-skill', 'A description that is long enough.'), source }).entry.origin).toBe('external');
+ expect(validateExternalSkill({ slug: 'ok-skill', text: skillMd('other', 'A description that is long enough.'), source }).reason).toMatch(/must equal/);
+ expect(validateExternalSkill({ slug: 'ok-skill', text: 'no frontmatter at all', source }).reason).toMatch(/frontmatter/);
+ expect(validateExternalSkill({ slug: 'Bad_Slug', text: skillMd('Bad_Slug', 'A description that is long enough.'), source }).reason).toMatch(/slug/);
+ expect(validateExternalSkill({ slug: 'ok-skill', text: skillMd('ok-skill', 'short'), source }).reason).toMatch(/too short/);
+ });
+});
+
+describe('the API with COMMUNITY_SKILL_SOURCES unset', () => {
+ it('behaves as before: no external key, no network', async () => {
+ const { status, json } = await get('/api/skills/community');
+ expect(status).toBe(200);
+ expect(json).not.toHaveProperty('external');
+ expect(json.count).toBe(json.total);
+ expect(hits).toEqual([]);
+ const miss = await get('/api/skills/community/alpha-skill');
+ expect(miss.status).toBe(404);
+ });
+});
+
+describe('the API with a synthetic external source', () => {
+ const source = () => [{ repo: 'fixture-org/skills-repo', ref: SHA, path: 'skills', license: 'Apache-2.0' }];
+
+ it('lists valid skills as external with source, ref and license, and omits the invalid ones', async () => {
+ setSources(source());
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const { status, json } = await get('/api/skills/community');
+ expect(status).toBe(200);
+ expect(json.external.skills.map((s) => s.slug)).toEqual(['alpha-skill', 'beta-skill']);
+ for (const s of json.external.skills) {
+ expect(s).toMatchObject({ origin: 'external', source: 'fixture-org/skills-repo', ref: SHA, license: 'Apache-2.0', not_reviewed: true });
+ expect(s.tree_url).toContain(`/tree/${SHA}/skills/`);
+ expect(s).not.toHaveProperty('content');
+ }
+ expect(json.external.skills[0]).toMatchObject({ tags: ['alpha', 'demo'], version: '2.1.0' });
+ const reasons = json.external.sources[0].dropped.map((d) => `${d.slug}: ${d.reason}`);
+ expect(reasons.some((r) => r.startsWith('wrong-name'))).toBe(true);
+ expect(reasons.some((r) => r.startsWith('tiny-body'))).toBe(true);
+ expect(reasons.some((r) => r.startsWith('agent-hiring') && /already used/.test(r))).toBe(true);
+ expect(warn).toHaveBeenCalled();
+ expect(json.skills.every((s) => s.origin === undefined)).toBe(true);
+ });
+
+ it('serves one external skill with its body and as markdown, and filters by query', async () => {
+ setSources(source());
+ const one = await get('/api/skills/community/alpha-skill');
+ expect(one.status).toBe(200);
+ expect(one.json.skill).toMatchObject({ slug: 'alpha-skill', origin: 'external', ref: SHA });
+ expect(one.json.skill.body).toContain('Follow these steps');
+ const md = await get('/api/skills/community/alpha-skill?format=md');
+ expect(md.text.startsWith('---\nname: alpha-skill')).toBe(true);
+ const q = await get('/api/skills/community?q=beta');
+ expect(q.json.external.skills.map((s) => s.slug)).toEqual(['beta-skill']);
+ });
+
+ it('caches the merge within the TTL', async () => {
+ setSources(source());
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ await get('/api/skills/community');
+ const first = hits.length;
+ await get('/api/skills/community');
+ expect(hits.length).toBe(first);
+ });
+
+ it('keeps the in-repo registry intact when a source fails, and logs it', async () => {
+ setSources([...source(), { repo: 'fixture-org/missing-repo', ref: OTHER_SHA, path: 'skills', license: 'MIT' }]);
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const { json } = await get('/api/skills/community');
+ expect(json.count).toBe(json.total);
+ expect(json.skills.length).toBeGreaterThan(0);
+ const bad = json.external.sources.find((s) => s.repo === 'fixture-org/missing-repo');
+ expect(bad).toMatchObject({ loaded: false, count: 0 });
+ expect(bad.error).toMatch(/404/);
+ expect(json.external.skills.map((s) => s.slug)).toEqual(['alpha-skill', 'beta-skill']);
+ expect(warn.mock.calls.some(([m]) => /missing-repo.*failed to load/.test(m))).toBe(true);
+ });
+
+ it('survives every source being down', async () => {
+ mode = 'down';
+ setSources(source());
+ vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const { status, json } = await get('/api/skills/community');
+ expect(status).toBe(200);
+ expect(json.external.count).toBe(0);
+ expect(json.external.sources[0].loaded).toBe(false);
+ expect(json.skills.length).toBe(json.total);
+ });
+});
+
+describe('loadExternalSkills', () => {
+ it('is disabled and does no work when unset', async () => {
+ const r = await loadExternalSkills({ env: {} });
+ expect(r).toEqual({ enabled: false, count: 0, skills: [], sources: [] });
+ });
+});