vskill 1.0.21 → 1.1.1

package/README.md

@@ -305,6 +305,8 @@ Full changelog → [github.com/anton-abyzov/vskill/releases](https://github.com/
 
 Issues and PRs welcome at [github.com/anton-abyzov/vskill](https://github.com/anton-abyzov/vskill). To submit a skill to the registry, see [verified-skill.com/docs/submitting](https://verified-skill.com/docs/submitting).
 
+Inside this repo dependency install scripts are disabled (`.npmrc`): run `npm ci`, then `npm run setup` (rebuilds esbuild), and `npm run security:scan` before pushing — see [SECURITY.md](SECURITY.md).
+
 ## License
 
 MIT

package/agents.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-06-17T16:49:56.735Z",
+  "generatedAt": "2026-09-14T07:11:29.092Z",
   "agentPrefixes": [
     ".adal",
     ".agent",

package/dist/commands/add.d.ts

@@ -1,4 +1,11 @@
 import type { AgentDefinition } from "../agents/agents-registry.js";
+/**
+ * Subdirectories fetched alongside SKILL.md when installing a skill that lives
+ * in a repo subdirectory. Must stay a subset of the prefixes the installer
+ * accepts in installer/bundle-files.ts, or the write is rejected.
+ */
+export declare const BUNDLE_SUBDIRS: readonly ["agents", "references", "scripts", "assets", "tests"];
+export declare function isBundleTextFile(name: string): boolean;
 interface MarketplaceDetectionResult {
     isMarketplace: boolean;
     manifestContent?: string;

package/dist/commands/add.js

@@ -36,6 +36,30 @@ import { extractFrontmatterVersion } from "../utils/version.js";
 import { claudePluginInstall, claudePluginUninstall, claudePluginMarketplaceAdd, claudePluginMarketplaceList, } from "../utils/claude-plugin.js";
 import { buildPerAgentReport, resolvePluginId, } from "../lib/skill-lifecycle.js";
 // ---------------------------------------------------------------------------
+/**
+ * Subdirectories fetched alongside SKILL.md when installing a skill that lives
+ * in a repo subdirectory. Must stay a subset of the prefixes the installer
+ * accepts in installer/bundle-files.ts, or the write is rejected.
+ */
+export const BUNDLE_SUBDIRS = ["agents", "references", "scripts", "assets", "tests"];
+/**
+ * Extensions carried in a skill bundle. Bundle contents are transported as
+ * UTF-8 strings, so this is a text-only allowlist — binaries would be corrupted.
+ */
+const BUNDLE_TEXT_EXTENSIONS = [
+    ".md", ".txt", ".json", ".jsonc", ".yaml", ".yml", ".toml", ".csv",
+    ".py", ".sh", ".bash", ".zsh", ".js", ".mjs", ".cjs", ".ts", ".sql",
+    ".excalidraw", ".svg", ".css", ".html",
+];
+/** Per-file and per-skill ceilings, so one fat repo cannot stall an install. */
+const MAX_BUNDLE_FILE_BYTES = 512 * 1024;
+const MAX_BUNDLE_FILES = 100;
+export function isBundleTextFile(name) {
+    const lower = name.toLowerCase();
+    if (lower.startsWith("."))
+        return false; // .DS_Store, dotfiles
+    return BUNDLE_TEXT_EXTENSIONS.some((ext) => lower.endsWith(ext));
+}
 /** Validate that a download_url from GitHub Contents API points to a trusted GitHub domain. */
 function isGitHubDownloadUrl(url) {
     try {
@@ -2400,41 +2424,80 @@ async function installSingleSkillLegacy(owner, repo, skill, opts, skillSubpathOv
     }
     const branch = refOverride || (await getDefaultBranch(owner, repo));
     const sourceCommitSha = await getBranchHeadSha(owner, repo, branch);
-    const skillSubpath = skillSubpathOverride || (skill ? `skills/${skill}/SKILL.md` : "SKILL.md");
-    const url = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${skillSubpath}`;
-    // Fetch SKILL.md
-    const content = await fetchSkillContent(url);
-    // Fetch agents/*.md if skill is in a subdirectory (skills/{name}/)
+    // Candidate subpaths: explicit override wins; otherwise try the conventional
+    // skills/{name}/ layout first, then root-level {name}/ (e.g. higgsfield-ai/skills).
+    const subpathCandidates = skillSubpathOverride
+        ? [skillSubpathOverride]
+        : skill
+            ? [`skills/${skill}/SKILL.md`, `${skill}/SKILL.md`]
+            : ["SKILL.md"];
+    // Fetch SKILL.md — first candidate that exists wins
+    let skillSubpath = subpathCandidates[0];
+    let content;
+    for (let i = 0; i < subpathCandidates.length; i++) {
+        const candidate = subpathCandidates[i];
+        const candidateUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${candidate}`;
+        const isLast = i === subpathCandidates.length - 1;
+        if (isLast) {
+            content = await fetchSkillContent(candidateUrl);
+            skillSubpath = candidate;
+            break;
+        }
+        const probe = await githubFetch(candidateUrl);
+        if (probe.ok) {
+            content = await probe.text();
+            skillSubpath = candidate;
+            break;
+        }
+    }
+    if (content === undefined)
+        return process.exit(1);
+    // Fetch the skill's bundled subdirectories when the skill lives in a
+    // subdirectory of the repo. These are the skill-authoring convention and the
+    // same prefixes the installer accepts (see installer/bundle-files.ts):
+    // agents/ holds sub-agent prompts, references/ the docs SKILL.md links to,
+    // scripts/ the executable tooling, assets/ static files, tests/ its tests.
+    // A skill whose SKILL.md says "run scripts/foo.py" and installs without
+    // scripts/ is not degraded — it is broken.
     let legacyAgentFiles;
     if (skill) {
-        try {
-            const agentsBasePath = skillSubpathOverride
-                ? skillSubpathOverride.replace(/\/SKILL\.md$/, "/agents")
-                : `skills/${skill}/agents`;
-            // ?ref= keeps the agents/ listing on the same branch as SKILL.md
-            // (deep links may pin a non-default branch).
-            const agentsDirUrl = `https://api.github.com/repos/${owner}/${repo}/contents/${agentsBasePath}?ref=${encodeURIComponent(branch)}`;
-            const dirRes = await githubFetch(agentsDirUrl, { headers: { Accept: "application/vnd.github.v3+json" } });
-            if (dirRes.ok) {
+        let fetched = 0;
+        for (const subdir of BUNDLE_SUBDIRS) {
+            try {
+                const basePath = skillSubpath.replace(/\/SKILL\.md$/, `/${subdir}`);
+                // ?ref= keeps the listing on the same branch as SKILL.md
+                // (deep links may pin a non-default branch).
+                const dirUrl = `https://api.github.com/repos/${owner}/${repo}/contents/${basePath}?ref=${encodeURIComponent(branch)}`;
+                const dirRes = await githubFetch(dirUrl, { headers: { Accept: "application/vnd.github.v3+json" } });
+                if (!dirRes.ok)
+                    continue;
                 const entries = (await dirRes.json());
-                const mdEntries = entries.filter((e) => e.name.endsWith(".md") && e.download_url && isGitHubDownloadUrl(e.download_url));
-                if (mdEntries.length > 0) {
-                    legacyAgentFiles = {};
-                    const fetches = mdEntries.map(async (entry) => {
-                        try {
-                            const res = await githubFetch(entry.download_url);
-                            if (res.ok)
-                                legacyAgentFiles[`agents/${entry.name}`] = await res.text();
-                        }
-                        catch { /* skip */ }
-                    });
-                    await Promise.allSettled(fetches);
-                    if (Object.keys(legacyAgentFiles).length === 0)
-                        legacyAgentFiles = undefined;
-                }
+                const wanted = entries.filter((e) => e.type !== "dir" &&
+                    isBundleTextFile(e.name) &&
+                    (e.size ?? 0) <= MAX_BUNDLE_FILE_BYTES &&
+                    e.download_url &&
+                    isGitHubDownloadUrl(e.download_url));
+                if (wanted.length === 0)
+                    continue;
+                legacyAgentFiles ??= {};
+                const budget = wanted.slice(0, Math.max(0, MAX_BUNDLE_FILES - fetched));
+                fetched += budget.length;
+                const fetches = budget.map(async (entry) => {
+                    try {
+                        const res = await githubFetch(entry.download_url);
+                        if (res.ok)
+                            legacyAgentFiles[`${subdir}/${entry.name}`] = await res.text();
+                    }
+                    catch { /* skip */ }
+                });
+                await Promise.allSettled(fetches);
+                if (fetched >= MAX_BUNDLE_FILES)
+                    break;
             }
+            catch { /* subdir doesn't exist or API error — fine */ }
         }
-        catch { /* agents/ dir doesn't exist or API error — fine */ }
+        if (legacyAgentFiles && Object.keys(legacyAgentFiles).length === 0)
+            legacyAgentFiles = undefined;
     }
     // Platform security check (best-effort, non-blocking on network error)
     const platformSecurity = await checkPlatformSecurity(skillName);