skills 1.1.3 → 1.1.5

package/README.md

@@ -6,6 +6,7 @@ The CLI for the open agent skills ecosystem.
 Supports **Opencode**, **Claude Code**, **Codex**, **Cursor**, and [25 more](#available-agents).
 <!-- agent-list:end -->
 
+<!-- agent-list:end -->
 
 <!-- agent-list:end -->
 
@@ -225,6 +226,19 @@ Describe the scenarios where this skill should be used.
 - `name`: Unique identifier (lowercase, hyphens allowed)
 - `description`: Brief explanation of what the skill does
 
+### Optional Fields
+
+- `metadata.internal`: Set to `true` to hide the skill from normal discovery. Internal skills are only visible and installable when `INSTALL_INTERNAL_SKILLS=1` is set. Useful for work-in-progress skills or skills meant only for internal tooling.
+
+```markdown
+---
+name: my-internal-skill
+description: An internal skill not shown by default
+metadata:
+  internal: true
+---
+```
+
 ### Skill Discovery
 
 The CLI searches for skills in these locations within a repository:
@@ -295,18 +309,23 @@ Ensure the repository contains valid `SKILL.md` files with both `name` and `desc
 
 Ensure you have write access to the target directory.
 
-## Telemetry
-
-This CLI collects anonymous usage data to help improve the tool. No personal information is collected.
+## Environment Variables
 
-To disable telemetry:
+| Variable                  | Description                                                                |
+| ------------------------- | -------------------------------------------------------------------------- |
+| `INSTALL_INTERNAL_SKILLS` | Set to `1` or `true` to show and install skills marked as `internal: true` |
+| `DISABLE_TELEMETRY`       | Set to disable anonymous usage telemetry                                   |
+| `DO_NOT_TRACK`            | Alternative way to disable telemetry                                       |
 
 ```bash
-DISABLE_TELEMETRY=1 npx skills add vercel-labs/agent-skills
-# or
-DO_NOT_TRACK=1 npx skills add vercel-labs/agent-skills
+# Install internal skills
+INSTALL_INTERNAL_SKILLS=1 npx skills add vercel-labs/agent-skills --list
 ```
 
+## Telemetry
+
+This CLI collects anonymous usage data to help improve the tool. No personal information is collected.
+
 Telemetry is automatically disabled in CI environments.
 
 ## Related Links

package/dist/cli.js

@@ -129,11 +129,43 @@ function parseSource(input) {
       subpath
     };
   }
+  if (isWellKnownUrl(input)) {
+    return {
+      type: "well-known",
+      url: input
+    };
+  }
   return {
     type: "git",
     url: input
   };
 }
+function isWellKnownUrl(input) {
+  if (!input.startsWith("http://") && !input.startsWith("https://")) {
+    return false;
+  }
+  try {
+    const parsed = new URL(input);
+    const excludedHosts = [
+      "github.com",
+      "gitlab.com",
+      "huggingface.co",
+      "raw.githubusercontent.com"
+    ];
+    if (excludedHosts.includes(parsed.hostname)) {
+      return false;
+    }
+    if (input.toLowerCase().endsWith("/skill.md")) {
+      return false;
+    }
+    if (input.endsWith(".git")) {
+      return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
 
 // src/git.ts
 import simpleGit from "simple-git";
@@ -202,6 +234,10 @@ import { readdir, readFile, stat } from "fs/promises";
 import { join as join2, basename, dirname } from "path";
 import matter from "gray-matter";
 var SKIP_DIRS = ["node_modules", ".git", "dist", "build", "__pycache__"];
+function shouldInstallInternalSkills() {
+  const envValue = process.env.INSTALL_INTERNAL_SKILLS;
+  return envValue === "1" || envValue === "true";
+}
 async function hasSkillMd(dir) {
   try {
     const skillPath = join2(dir, "SKILL.md");
@@ -218,6 +254,10 @@ async function parseSkillMd(skillMdPath) {
     if (!data.name || !data.description) {
       return null;
     }
+    const isInternal = data.metadata?.internal === true;
+    if (isInternal && !shouldInstallInternalSkills()) {
+      return null;
+    }
     return {
       name: data.name,
       description: data.description,
@@ -881,6 +921,86 @@ async function installRemoteSkillForAgent(skill, agentType, options = {}) {
     };
   }
 }
+async function installWellKnownSkillForAgent(skill, agentType, options = {}) {
+  const agent = agents[agentType];
+  const isGlobal = options.global ?? false;
+  const cwd = options.cwd || process.cwd();
+  const installMode = options.mode ?? "symlink";
+  const skillName = sanitizeName(skill.installName);
+  const canonicalBase = getCanonicalSkillsDir(isGlobal, cwd);
+  const canonicalDir = join4(canonicalBase, skillName);
+  const agentBase = isGlobal ? agent.globalSkillsDir : join4(cwd, agent.skillsDir);
+  const agentDir = join4(agentBase, skillName);
+  if (!isPathSafe(canonicalBase, canonicalDir)) {
+    return {
+      success: false,
+      path: agentDir,
+      mode: installMode,
+      error: "Invalid skill name: potential path traversal detected"
+    };
+  }
+  if (!isPathSafe(agentBase, agentDir)) {
+    return {
+      success: false,
+      path: agentDir,
+      mode: installMode,
+      error: "Invalid skill name: potential path traversal detected"
+    };
+  }
+  async function writeSkillFiles(targetDir) {
+    await mkdir(targetDir, { recursive: true });
+    for (const [filePath, content] of skill.files) {
+      const fullPath = join4(targetDir, filePath);
+      if (!isPathSafe(targetDir, fullPath)) {
+        continue;
+      }
+      const parentDir = dirname2(fullPath);
+      if (parentDir !== targetDir) {
+        await mkdir(parentDir, { recursive: true });
+      }
+      await writeFile(fullPath, content, "utf-8");
+    }
+  }
+  try {
+    if (installMode === "copy") {
+      await writeSkillFiles(agentDir);
+      return {
+        success: true,
+        path: agentDir,
+        mode: "copy"
+      };
+    }
+    await writeSkillFiles(canonicalDir);
+    const symlinkCreated = await createSymlink(canonicalDir, agentDir);
+    if (!symlinkCreated) {
+      try {
+        await rm2(agentDir, { recursive: true, force: true });
+      } catch {
+      }
+      await writeSkillFiles(agentDir);
+      return {
+        success: true,
+        path: agentDir,
+        canonicalPath: canonicalDir,
+        mode: "symlink",
+        symlinkFailed: true
+      };
+    }
+    return {
+      success: true,
+      path: agentDir,
+      canonicalPath: canonicalDir,
+      mode: "symlink"
+    };
+  } catch (error) {
+    return {
+      success: false,
+      path: agentDir,
+      mode: installMode,
+      error: error instanceof Error ? error.message : "Unknown error"
+    };
+  }
+}
 
 // src/telemetry.ts
 var TELEMETRY_URL = "https://add-skill.vercel.sh/t";
@@ -1082,12 +1202,268 @@ var HuggingFaceProvider = class {
 };
 var huggingFaceProvider = new HuggingFaceProvider();
 
+// src/providers/wellknown.ts
+import matter4 from "gray-matter";
+var WellKnownProvider = class {
+  id = "well-known";
+  displayName = "Well-Known Skills";
+  WELL_KNOWN_PATH = ".well-known/skills";
+  INDEX_FILE = "index.json";
+  /**
+   * Check if a URL could be a well-known skills endpoint.
+   * This is a fallback provider - it matches any HTTP(S) URL that is not
+   * a recognized pattern (GitHub, GitLab, owner/repo shorthand, etc.)
+   */
+  match(url) {
+    if (!url.startsWith("http://") && !url.startsWith("https://")) {
+      return { matches: false };
+    }
+    try {
+      const parsed = new URL(url);
+      const excludedHosts = ["github.com", "gitlab.com", "huggingface.co"];
+      if (excludedHosts.includes(parsed.hostname)) {
+        return { matches: false };
+      }
+      return {
+        matches: true,
+        sourceIdentifier: `wellknown/${parsed.hostname}`
+      };
+    } catch {
+      return { matches: false };
+    }
+  }
+  /**
+   * Fetch the skills index from a well-known endpoint.
+   * Tries both the path-relative .well-known and the root .well-known.
+   */
+  async fetchIndex(baseUrl) {
+    try {
+      const parsed = new URL(baseUrl);
+      const basePath = parsed.pathname.replace(/\/$/, "");
+      const urlsToTry = [
+        // Path-relative: https://example.com/docs/.well-known/skills/index.json
+        {
+          indexUrl: `${parsed.protocol}//${parsed.hostname}${basePath}/${this.WELL_KNOWN_PATH}/${this.INDEX_FILE}`,
+          baseUrl: `${parsed.protocol}//${parsed.hostname}${basePath}`
+        }
+      ];
+      if (basePath && basePath !== "") {
+        urlsToTry.push({
+          indexUrl: `${parsed.protocol}//${parsed.hostname}/${this.WELL_KNOWN_PATH}/${this.INDEX_FILE}`,
+          baseUrl: `${parsed.protocol}//${parsed.hostname}`
+        });
+      }
+      for (const { indexUrl, baseUrl: resolvedBase } of urlsToTry) {
+        try {
+          const response = await fetch(indexUrl);
+          if (!response.ok) {
+            continue;
+          }
+          const index = await response.json();
+          if (!index.skills || !Array.isArray(index.skills)) {
+            continue;
+          }
+          let allValid = true;
+          for (const entry of index.skills) {
+            if (!this.isValidSkillEntry(entry)) {
+              allValid = false;
+              break;
+            }
+          }
+          if (allValid) {
+            return { index, resolvedBaseUrl: resolvedBase };
+          }
+        } catch {
+          continue;
+        }
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Validate a skill entry from the index.
+   */
+  isValidSkillEntry(entry) {
+    if (!entry || typeof entry !== "object") return false;
+    const e = entry;
+    if (typeof e.name !== "string" || !e.name) return false;
+    if (typeof e.description !== "string" || !e.description) return false;
+    if (!Array.isArray(e.files) || e.files.length === 0) return false;
+    const nameRegex = /^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$/;
+    if (!nameRegex.test(e.name) && e.name.length > 1) {
+      if (e.name.length === 1 && !/^[a-z0-9]$/.test(e.name)) {
+        return false;
+      }
+    }
+    for (const file of e.files) {
+      if (typeof file !== "string") return false;
+      if (file.startsWith("/") || file.includes("..")) return false;
+    }
+    const hasSkillMd2 = e.files.some((f) => typeof f === "string" && f.toLowerCase() === "skill.md");
+    if (!hasSkillMd2) return false;
+    return true;
+  }
+  /**
+   * Fetch a single skill and all its files from a well-known endpoint.
+   */
+  async fetchSkill(url) {
+    try {
+      const parsed = new URL(url);
+      const result = await this.fetchIndex(url);
+      if (!result) {
+        return null;
+      }
+      const { index, resolvedBaseUrl } = result;
+      let skillName = null;
+      const pathMatch = parsed.pathname.match(/\/.well-known\/skills\/([^/]+)\/?$/);
+      if (pathMatch && pathMatch[1] && pathMatch[1] !== "index.json") {
+        skillName = pathMatch[1];
+      } else if (index.skills.length === 1) {
+        skillName = index.skills[0].name;
+      }
+      if (!skillName) {
+        return null;
+      }
+      const skillEntry = index.skills.find((s) => s.name === skillName);
+      if (!skillEntry) {
+        return null;
+      }
+      return this.fetchSkillByEntry(resolvedBaseUrl, skillEntry);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Fetch a skill by its index entry.
+   * @param baseUrl - The base URL (e.g., https://example.com or https://example.com/docs)
+   * @param entry - The skill entry from index.json
+   */
+  async fetchSkillByEntry(baseUrl, entry) {
+    try {
+      const skillBaseUrl = `${baseUrl.replace(/\/$/, "")}/${this.WELL_KNOWN_PATH}/${entry.name}`;
+      const skillMdUrl = `${skillBaseUrl}/SKILL.md`;
+      const response = await fetch(skillMdUrl);
+      if (!response.ok) {
+        return null;
+      }
+      const content = await response.text();
+      const { data } = matter4(content);
+      if (!data.name || !data.description) {
+        return null;
+      }
+      const files = /* @__PURE__ */ new Map();
+      files.set("SKILL.md", content);
+      const otherFiles = entry.files.filter((f) => f.toLowerCase() !== "skill.md");
+      const filePromises = otherFiles.map(async (filePath) => {
+        try {
+          const fileUrl = `${skillBaseUrl}/${filePath}`;
+          const fileResponse = await fetch(fileUrl);
+          if (fileResponse.ok) {
+            const fileContent = await fileResponse.text();
+            return { path: filePath, content: fileContent };
+          }
+        } catch {
+        }
+        return null;
+      });
+      const fileResults = await Promise.all(filePromises);
+      for (const result of fileResults) {
+        if (result) {
+          files.set(result.path, result.content);
+        }
+      }
+      return {
+        name: data.name,
+        description: data.description,
+        content,
+        installName: entry.name,
+        sourceUrl: skillMdUrl,
+        metadata: data.metadata,
+        files,
+        indexEntry: entry
+      };
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Fetch all skills from a well-known endpoint.
+   */
+  async fetchAllSkills(url) {
+    try {
+      const result = await this.fetchIndex(url);
+      if (!result) {
+        return [];
+      }
+      const { index, resolvedBaseUrl } = result;
+      const skillPromises = index.skills.map(
+        (entry) => this.fetchSkillByEntry(resolvedBaseUrl, entry)
+      );
+      const results = await Promise.all(skillPromises);
+      return results.filter((s) => s !== null);
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Convert a user-facing URL to a skill URL.
+   * For well-known, this extracts the base domain and constructs the proper path.
+   */
+  toRawUrl(url) {
+    try {
+      const parsed = new URL(url);
+      if (url.toLowerCase().endsWith("/skill.md")) {
+        return url;
+      }
+      const pathMatch = parsed.pathname.match(/\/.well-known\/skills\/([^/]+)\/?$/);
+      if (pathMatch && pathMatch[1]) {
+        const basePath2 = parsed.pathname.replace(/\/.well-known\/skills\/.*$/, "");
+        return `${parsed.protocol}//${parsed.hostname}${basePath2}/${this.WELL_KNOWN_PATH}/${pathMatch[1]}/SKILL.md`;
+      }
+      const basePath = parsed.pathname.replace(/\/$/, "");
+      return `${parsed.protocol}//${parsed.hostname}${basePath}/${this.WELL_KNOWN_PATH}/${this.INDEX_FILE}`;
+    } catch {
+      return url;
+    }
+  }
+  /**
+   * Get the source identifier for telemetry/storage.
+   * Returns the domain in owner/repo format: second-level-domain/top-level-domain.
+   * e.g., "mintlify.com" → "mintlify/com", "lovable.dev" → "lovable/dev"
+   * This matches the owner/repo pattern used by GitHub sources for consistency in the leaderboard.
+   */
+  getSourceIdentifier(url) {
+    try {
+      const parsed = new URL(url);
+      const hostParts = parsed.hostname.split(".");
+      if (hostParts.length >= 2) {
+        const tld = hostParts[hostParts.length - 1];
+        const sld = hostParts[hostParts.length - 2];
+        return `${sld}/${tld}`;
+      }
+      return parsed.hostname.replace(".", "/");
+    } catch {
+      return "unknown/unknown";
+    }
+  }
+  /**
+   * Check if a URL has a well-known skills index.
+   */
+  async hasSkillsIndex(url) {
+    const result = await this.fetchIndex(url);
+    return result !== null;
+  }
+};
+var wellKnownProvider = new WellKnownProvider();
+
 // src/providers/index.ts
 registerProvider(mintlifyProvider);
 registerProvider(huggingFaceProvider);
 
 // src/mintlify.ts
-import matter4 from "gray-matter";
+import matter5 from "gray-matter";
 async function fetchMintlifySkill(url) {
   try {
     const response = await fetch(url);
@@ -1095,7 +1471,7 @@ async function fetchMintlifySkill(url) {
       return null;
     }
     const content = await response.text();
-    const { data } = matter4(content);
+    const { data } = matter5(content);
     const mintlifySite = data.metadata?.["mintlify-proj"];
     if (!mintlifySite) {
       return null;
@@ -1219,7 +1595,7 @@ async function dismissPrompt(promptKey) {
 // package.json
 var package_default = {
   name: "skills",
-  version: "1.1.3",
+  version: "1.1.5",
   description: "The open agent skills ecosystem",
   type: "module",
   bin: {
@@ -1651,6 +2027,333 @@ async function handleRemoteSkill(source, url, options, spinner2) {
   p.outro(chalk.green("Done!"));
   await promptForFindSkills();
 }
+async function handleWellKnownSkills(source, url, options, spinner2) {
+  spinner2.start("Discovering skills from well-known endpoint...");
+  const skills = await wellKnownProvider.fetchAllSkills(url);
+  if (skills.length === 0) {
+    spinner2.stop(chalk.red("No skills found"));
+    p.outro(
+      chalk.red(
+        "No skills found at this URL. Make sure the server has a /.well-known/skills/index.json file."
+      )
+    );
+    process.exit(1);
+  }
+  spinner2.stop(`Found ${chalk.green(skills.length)} skill${skills.length > 1 ? "s" : ""}`);
+  for (const skill of skills) {
+    p.log.info(`Skill: ${chalk.cyan(skill.installName)}`);
+    p.log.message(chalk.dim(skill.description));
+    if (skill.files.size > 1) {
+      p.log.message(chalk.dim(`  Files: ${Array.from(skill.files.keys()).join(", ")}`));
+    }
+  }
+  if (options.list) {
+    console.log();
+    p.log.step(chalk.bold("Available Skills"));
+    for (const skill of skills) {
+      p.log.message(`  ${chalk.cyan(skill.installName)}`);
+      p.log.message(`    ${chalk.dim(skill.description)}`);
+      if (skill.files.size > 1) {
+        p.log.message(`    ${chalk.dim(`Files: ${skill.files.size}`)}`);
+      }
+    }
+    console.log();
+    p.outro("Run without --list to install");
+    process.exit(0);
+  }
+  let selectedSkills;
+  if (options.skill && options.skill.length > 0) {
+    selectedSkills = skills.filter(
+      (s) => options.skill.some(
+        (name) => s.installName.toLowerCase() === name.toLowerCase() || s.name.toLowerCase() === name.toLowerCase()
+      )
+    );
+    if (selectedSkills.length === 0) {
+      p.log.error(`No matching skills found for: ${options.skill.join(", ")}`);
+      p.log.info("Available skills:");
+      for (const s of skills) {
+        p.log.message(`  - ${s.installName}`);
+      }
+      process.exit(1);
+    }
+    p.log.info(
+      `Selected ${selectedSkills.length} skill${selectedSkills.length !== 1 ? "s" : ""}: ${selectedSkills.map((s) => chalk.cyan(s.installName)).join(", ")}`
+    );
+  } else if (skills.length === 1) {
+    selectedSkills = skills;
+    const firstSkill = skills[0];
+    p.log.info(`Skill: ${chalk.cyan(firstSkill.installName)}`);
+  } else if (options.yes) {
+    selectedSkills = skills;
+    p.log.info(`Installing all ${skills.length} skills`);
+  } else {
+    const skillChoices = skills.map((s) => ({
+      value: s,
+      label: s.installName,
+      hint: s.description.length > 60 ? s.description.slice(0, 57) + "..." : s.description
+    }));
+    const selected = await multiselect2({
+      message: "Select skills to install",
+      options: skillChoices,
+      required: true
+    });
+    if (p.isCancel(selected)) {
+      p.cancel("Installation cancelled");
+      process.exit(0);
+    }
+    selectedSkills = selected;
+  }
+  let targetAgents;
+  const validAgents = Object.keys(agents);
+  if (options.agent && options.agent.length > 0) {
+    const invalidAgents = options.agent.filter((a) => !validAgents.includes(a));
+    if (invalidAgents.length > 0) {
+      p.log.error(`Invalid agents: ${invalidAgents.join(", ")}`);
+      p.log.info(`Valid agents: ${validAgents.join(", ")}`);
+      process.exit(1);
+    }
+    targetAgents = options.agent;
+  } else if (options.all) {
+    targetAgents = validAgents;
+    p.log.info(`Installing to all ${targetAgents.length} agents`);
+  } else {
+    spinner2.start("Detecting installed agents...");
+    const installedAgents = await detectInstalledAgents();
+    spinner2.stop(
+      `Detected ${installedAgents.length} agent${installedAgents.length !== 1 ? "s" : ""}`
+    );
+    if (installedAgents.length === 0) {
+      if (options.yes) {
+        targetAgents = validAgents;
+        p.log.info("Installing to all agents (none detected)");
+      } else {
+        p.log.warn("No coding agents detected. You can still install skills.");
+        const allAgentChoices = Object.entries(agents).map(([key, config]) => ({
+          value: key,
+          label: config.displayName
+        }));
+        const selected = await multiselect2({
+          message: "Select agents to install skills to",
+          options: allAgentChoices,
+          required: true,
+          initialValues: Object.keys(agents)
+        });
+        if (p.isCancel(selected)) {
+          p.cancel("Installation cancelled");
+          process.exit(0);
+        }
+        targetAgents = selected;
+      }
+    } else if (installedAgents.length === 1 || options.yes) {
+      targetAgents = installedAgents;
+      if (installedAgents.length === 1) {
+        const firstAgent = installedAgents[0];
+        p.log.info(`Installing to: ${chalk.cyan(agents[firstAgent].displayName)}`);
+      } else {
+        p.log.info(
+          `Installing to: ${installedAgents.map((a) => chalk.cyan(agents[a].displayName)).join(", ")}`
+        );
+      }
+    } else {
+      const selected = await selectAgentsInteractive(installedAgents, { global: options.global });
+      if (p.isCancel(selected)) {
+        p.cancel("Installation cancelled");
+        process.exit(0);
+      }
+      targetAgents = selected;
+    }
+  }
+  let installGlobally = options.global ?? false;
+  if (options.global === void 0 && !options.yes) {
+    const scope = await p.select({
+      message: "Installation scope",
+      options: [
+        {
+          value: false,
+          label: "Project",
+          hint: "Install in current directory (committed with your project)"
+        },
+        {
+          value: true,
+          label: "Global",
+          hint: "Install in home directory (available across all projects)"
+        }
+      ]
+    });
+    if (p.isCancel(scope)) {
+      p.cancel("Installation cancelled");
+      process.exit(0);
+    }
+    installGlobally = scope;
+  }
+  let installMode = "symlink";
+  if (!options.yes) {
+    const modeChoice = await p.select({
+      message: "Installation method",
+      options: [
+        {
+          value: "symlink",
+          label: "Symlink (Recommended)",
+          hint: "Single source of truth, easy updates"
+        },
+        { value: "copy", label: "Copy to all agents", hint: "Independent copies for each agent" }
+      ]
+    });
+    if (p.isCancel(modeChoice)) {
+      p.cancel("Installation cancelled");
+      process.exit(0);
+    }
+    installMode = modeChoice;
+  }
+  const cwd = process.cwd();
+  const summaryLines = [];
+  const agentNames = targetAgents.map((a) => agents[a].displayName);
+  const overwriteStatus = /* @__PURE__ */ new Map();
+  for (const skill of selectedSkills) {
+    const agentStatus = /* @__PURE__ */ new Map();
+    for (const agent of targetAgents) {
+      agentStatus.set(
+        agent,
+        await isSkillInstalled(skill.installName, agent, { global: installGlobally })
+      );
+    }
+    overwriteStatus.set(skill.installName, agentStatus);
+  }
+  for (const skill of selectedSkills) {
+    if (summaryLines.length > 0) summaryLines.push("");
+    if (installMode === "symlink") {
+      const canonicalPath = getCanonicalPath(skill.installName, { global: installGlobally });
+      const shortCanonical = shortenPath(canonicalPath, cwd);
+      summaryLines.push(`${chalk.cyan(shortCanonical)}`);
+      summaryLines.push(`  ${chalk.dim("symlink \u2192")} ${formatList(agentNames)}`);
+      if (skill.files.size > 1) {
+        summaryLines.push(`  ${chalk.dim("files:")} ${skill.files.size}`);
+      }
+    } else {
+      summaryLines.push(`${chalk.cyan(skill.installName)}`);
+      summaryLines.push(`  ${chalk.dim("copy \u2192")} ${formatList(agentNames)}`);
+    }
+    const skillOverwrites = overwriteStatus.get(skill.installName);
+    const overwriteAgents = targetAgents.filter((a) => skillOverwrites?.get(a)).map((a) => agents[a].displayName);
+    if (overwriteAgents.length > 0) {
+      summaryLines.push(`  ${chalk.yellow("overwrites:")} ${formatList(overwriteAgents)}`);
+    }
+  }
+  console.log();
+  p.note(summaryLines.join("\n"), "Installation Summary");
+  if (!options.yes) {
+    const confirmed = await p.confirm({ message: "Proceed with installation?" });
+    if (p.isCancel(confirmed) || !confirmed) {
+      p.cancel("Installation cancelled");
+      process.exit(0);
+    }
+  }
+  spinner2.start("Installing skills...");
+  const results = [];
+  for (const skill of selectedSkills) {
+    for (const agent of targetAgents) {
+      const result = await installWellKnownSkillForAgent(skill, agent, {
+        global: installGlobally,
+        mode: installMode
+      });
+      results.push({
+        skill: skill.installName,
+        agent: agents[agent].displayName,
+        ...result
+      });
+    }
+  }
+  spinner2.stop("Installation complete");
+  console.log();
+  const successful = results.filter((r) => r.success);
+  const failed = results.filter((r) => !r.success);
+  const sourceIdentifier = wellKnownProvider.getSourceIdentifier(url);
+  track({
+    event: "install",
+    source: sourceIdentifier,
+    skills: selectedSkills.map((s) => s.installName).join(","),
+    agents: targetAgents.join(","),
+    ...installGlobally && { global: "1" },
+    sourceType: "well-known"
+  });
+  if (successful.length > 0 && installGlobally) {
+    const successfulSkillNames = new Set(successful.map((r) => r.skill));
+    for (const skill of selectedSkills) {
+      if (successfulSkillNames.has(skill.installName)) {
+        try {
+          await addSkillToLock(skill.installName, {
+            source: sourceIdentifier,
+            sourceType: "well-known",
+            sourceUrl: skill.sourceUrl,
+            skillFolderHash: ""
+            // Well-known skills don't have a folder hash
+          });
+        } catch {
+        }
+      }
+    }
+  }
+  if (successful.length > 0) {
+    const bySkill = /* @__PURE__ */ new Map();
+    for (const r of successful) {
+      const skillResults = bySkill.get(r.skill) || [];
+      skillResults.push(r);
+      bySkill.set(r.skill, skillResults);
+    }
+    const skillCount = bySkill.size;
+    const agentCount = new Set(successful.map((r) => r.agent)).size;
+    const symlinkFailures = successful.filter((r) => r.mode === "symlink" && r.symlinkFailed);
+    const copiedAgents = symlinkFailures.map((r) => r.agent);
+    const resultLines = [];
+    for (const [skillName, skillResults] of bySkill) {
+      const firstResult = skillResults[0];
+      if (firstResult.mode === "copy") {
+        resultLines.push(`${chalk.green("\u2713")} ${skillName} ${chalk.dim("(copied)")}`);
+        for (const r of skillResults) {
+          const shortPath = shortenPath(r.path, cwd);
+          resultLines.push(`  ${chalk.dim("\u2192")} ${shortPath}`);
+        }
+      } else {
+        if (firstResult.canonicalPath) {
+          const shortPath = shortenPath(firstResult.canonicalPath, cwd);
+          resultLines.push(`${chalk.green("\u2713")} ${shortPath}`);
+        } else {
+          resultLines.push(`${chalk.green("\u2713")} ${skillName}`);
+        }
+        const symlinked = skillResults.filter((r) => !r.symlinkFailed).map((r) => r.agent);
+        const copied = skillResults.filter((r) => r.symlinkFailed).map((r) => r.agent);
+        if (symlinked.length > 0) {
+          resultLines.push(`  ${chalk.dim("symlink \u2192")} ${formatList(symlinked)}`);
+        }
+        if (copied.length > 0) {
+          resultLines.push(`  ${chalk.yellow("copied \u2192")} ${formatList(copied)}`);
+        }
+      }
+    }
+    const title = chalk.green(
+      `Installed ${skillCount} skill${skillCount !== 1 ? "s" : ""} to ${agentCount} agent${agentCount !== 1 ? "s" : ""}`
+    );
+    p.note(resultLines.join("\n"), title);
+    if (symlinkFailures.length > 0) {
+      p.log.warn(chalk.yellow(`Symlinks failed for: ${formatList(copiedAgents)}`));
+      p.log.message(
+        chalk.dim(
+          "  Files were copied instead. On Windows, enable Developer Mode for symlink support."
+        )
+      );
+    }
+  }
+  if (failed.length > 0) {
+    console.log();
+    p.log.error(chalk.red(`Failed to install ${failed.length}`));
+    for (const r of failed) {
+      p.log.message(`  ${chalk.red("\u2717")} ${r.skill} \u2192 ${r.agent}: ${chalk.dim(r.error)}`);
+    }
+  }
+  console.log();
+  p.outro(chalk.green("Done!"));
+  await promptForFindSkills();
+}
 async function handleDirectUrlSkillLegacy(source, url, options, spinner2) {
   spinner2.start("Fetching skill.md...");
   const mintlifySkill = await fetchMintlifySkill(url);
@@ -1924,6 +2627,10 @@ async function runAdd(args, options = {}) {
       await handleRemoteSkill(source, parsed.url, options, spinner2);
       return;
     }
+    if (parsed.type === "well-known") {
+      await handleWellKnownSkills(source, parsed.url, options, spinner2);
+      return;
+    }
     let skillsDir;
     if (parsed.type === "local") {
       spinner2.start("Validating local path...");
@@ -1950,7 +2657,9 @@ async function runAdd(args, options = {}) {
       await cleanup(tempDir);
       process.exit(1);
     }
-    spinner2.stop(`Found ${chalk.green(skills.length)} skill${skills.length > 1 ? "s" : ""}`);
+    spinner2.stop(
+      `Found ${chalk.green(skills.length)} skill${skills.length > 1 ? "s" : ""} ${chalk.dim("(via Well-known Agent Skill Discovery)")}`
+    );
     if (options.list) {
       console.log();
       p.log.step(chalk.bold("Available Skills"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "The open agent skills ecosystem",
   "type": "module",
   "bin": {