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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
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.jsnew file mode 100644index 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.jsindex 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.mdindex 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`.+## ContributingSee [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.jsindex 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.jsindex 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.htmlindex 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.cssindex 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.jsindex 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.jsnew file mode 100644index 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: [] });+ });+});