skillex 0.3.1 → 0.4.0

package/dist/cli.js

@@ -1,16 +1,81 @@
 import * as path from "node:path";
 import { listAdapters } from "./adapters.js";
-import { computeCatalogCacheKey, readCatalogCache, searchCatalogSkills, } from "./catalog.js";
+import { buildRawGitHubUrl, searchCatalogSkills, } from "./catalog.js";
+import { runDoctorChecks } from "./doctor.js";
+import { fetchText } from "./http.js";
 import { DEFAULT_INSTALL_SCOPE, getScopedStatePaths } from "./config.js";
-import { addProjectSource, getInstalledSkills, initProject, installSkills, listProjectSources, loadProjectCatalogs, removeProjectSource, removeSkills, resolveProjectSource, syncInstalledSkills, updateInstalledSkills, } from "./install.js";
+import { addProjectSource, getInstalledSkills, initProject, installSkills, listProjectSources, loadProjectCatalogs, removeProjectSource, removeSkills, syncInstalledSkills, updateInstalledSkills, } from "./install.js";
 import * as output from "./output.js";
-import { setVerbose } from "./output.js";
+import { setVerbose, suggestClosest } from "./output.js";
 import { parseSkillCommandReference, runSkillScript } from "./runner.js";
+import { getRecommendedSkillIds } from "./recommended.js";
 import { runInteractiveUi } from "./ui.js";
 import { startWebUiServer } from "./web-ui.js";
 import { CliError } from "./types.js";
 import { VALID_CONFIG_KEYS, readUserConfig, writeUserConfig } from "./user-config.js";
 // ---------------------------------------------------------------------------
+// Flag schema (drives parsing, validation, and "did you mean" suggestions)
+// ---------------------------------------------------------------------------
+/** Flags that accept a value (e.g. `--repo foo` or `--repo=foo`). */
+const STRING_FLAGS = new Set([
+    "repo",
+    "ref",
+    "adapter",
+    "scope",
+    "cwd",
+    "mode",
+    "tag",
+    "tags",
+    "compatibility",
+    "agent-skills-dir",
+    "catalog-path",
+    "catalog-url",
+    "skills-dir",
+    "label",
+    "timeout",
+]);
+/** Flags that are pure booleans (presence = true; supports `--name=value` parsing too). */
+const BOOLEAN_FLAGS = new Set([
+    "help",
+    "verbose",
+    "v",
+    "json",
+    "no-cache",
+    "all",
+    "trust",
+    "yes",
+    "global",
+    "auto-sync",
+    "dry-run",
+    "exit-code",
+    "raw",
+    "install-recommended",
+]);
+/** Union of all flags the parser accepts anywhere in the CLI. */
+const KNOWN_FLAGS = new Set([...STRING_FLAGS, ...BOOLEAN_FLAGS]);
+const COMMANDS = [
+    "init",
+    "list",
+    "search",
+    "install",
+    "update",
+    "remove",
+    "sync",
+    "run",
+    "show",
+    "browse",
+    "tui",
+    "ui",
+    "status",
+    "doctor",
+    "config",
+    "source",
+    "ls",
+    "rm",
+    "uninstall",
+    "help",
+];
+// ---------------------------------------------------------------------------
 // Per-command help text
 // ---------------------------------------------------------------------------
 const COMMAND_HELP = {
@@ -19,16 +84,18 @@ const COMMAND_HELP = {
 Initialize Skillex state for the local workspace or global user scope.
 
 Options:
-  --repo <owner/repo>   GitHub repository with skills (default: lgili/skillex)
-  --ref <ref>           Branch, tag, or commit (default: main)
-  --adapter <id>        Force a specific adapter
-  --auto-sync           Enable or disable auto-sync (default: on)
-  --scope <scope>       local or global (default: local)
-  --global              Shortcut for --scope global
-  --cwd <path>          Target project directory (default: current directory)
+  --repo <owner/repo>      GitHub repository with skills (default: lgili/skillex)
+  --ref <ref>              Branch, tag, or commit (default: main)
+  --adapter <id>           Force a specific adapter
+  --auto-sync              Enable or disable auto-sync (default: on)
+  --install-recommended    After init, install a curated starter pack
+  --scope <scope>          local or global (default: local)
+  --global                 Shortcut for --scope global
+  --cwd <path>             Target project directory (default: current directory)
 
 Example:
   skillex init
+  skillex init --install-recommended
   skillex init --repo myorg/my-skills
   skillex init --global --adapter codex`,
     list: `Usage: skillex list [options]
@@ -51,12 +118,13 @@ Search skills by text, compatibility, or tags.
 Options:
   --repo <owner/repo>   GitHub repository (limits this command to one source)
   --compatibility <id>  Filter by adapter compatibility
-  --tag <tag>           Filter by tag
+  --tag <tag>           Filter by tag (alias: --tags for compatibility)
   --no-cache            Bypass local catalog cache
   --json                Output results as JSON
 
 Example:
-  skillex search git --compatibility claude`,
+  skillex search git --compatibility claude
+  skillex search --tag workflow`,
     install: `Usage: skillex install <skill-id...> [options]
          skillex install --all [options]
          skillex install <owner/repo[@ref]> [options]
@@ -107,6 +175,7 @@ Synchronize installed skills to adapter targets.
 Options:
   --adapter <id>        Target adapter (overrides saved config)
   --dry-run             Preview changes without writing to disk
+  --exit-code           With --dry-run, exit 1 when adapters would change (CI)
   --mode <symlink|copy> Sync write mode (default: symlink)
   --scope <scope>       local or global (default: local)
   --global              Shortcut for --scope global
@@ -114,6 +183,7 @@ Options:
 Example:
   skillex sync
   skillex sync --adapter cursor --dry-run
+  skillex sync --dry-run --exit-code        # CI: fail when out of sync
   skillex sync --global --adapter codex`,
     run: `Usage: skillex run <skill-id:command> [options]
 
@@ -125,6 +195,20 @@ Options:
 
 Example:
   skillex run git-master:cleanup --yes`,
+    show: `Usage: skillex show <skill-id> [options]
+
+Print the manifest summary and rendered SKILL.md content of a skill from
+the configured catalog sources without installing it.
+
+Options:
+  --repo <owner/repo>   Limit resolution to one source
+  --raw                 Print SKILL.md verbatim (no manifest header)
+  --json                Print manifest + raw SKILL.md as a single JSON object
+  --no-cache            Bypass local catalog cache
+
+Example:
+  skillex show git-master
+  skillex show code-review --raw`,
     browse: `Usage: skillex browse [options]
          skillex tui [options]
          skillex [options]
@@ -270,6 +354,9 @@ export async function main(argv) {
         case "run":
             await handleRun(positionals, flags, userConfig);
             return;
+        case "show":
+            await handleShow(positionals, flags, userConfig);
+            return;
         case "ui":
             await handleWebUi(flags, userConfig);
             return;
@@ -285,8 +372,12 @@ export async function main(argv) {
         case "source":
             await handleSource(positionals, flags, userConfig);
             return;
-        default:
-            throw new CliError(`Unknown command: ${resolvedCommand}. Run "skillex help" to see available commands.`);
+        default: {
+            const suggestion = suggestClosest(resolvedCommand, COMMANDS);
+            throw new CliError(suggestion
+                ? `Unknown command: ${resolvedCommand}. Did you mean: ${suggestion}? Run "skillex help" for the full list.`
+                : `Unknown command: ${resolvedCommand}. Run "skillex help" to see available commands.`);
+        }
     }
 }
 // ---------------------------------------------------------------------------
@@ -294,6 +385,7 @@ export async function main(argv) {
 // ---------------------------------------------------------------------------
 async function handleInit(flags, userConfig) {
     const repo = asOptionalString(flags.repo) ?? userConfig.defaultRepo;
+    const installRecommended = parseBooleanFlag(flags["install-recommended"], "install-recommended") ?? false;
     const opts = commonOptions(flags, userConfig);
     const result = await initProject({
         ...opts,
@@ -321,7 +413,24 @@ async function handleInit(flags, userConfig) {
     if (result.lockfile.adapters.detected.length > 0) {
         output.info(`  Detected : ${result.lockfile.adapters.detected.join(", ")}`);
     }
-    output.info("\nNext: run 'skillex list' to browse available skills");
+    if (installRecommended) {
+        const recommended = getRecommendedSkillIds();
+        output.info(`\nInstalling ${recommended.length} recommended skill(s)...`);
+        const installResult = await installSkills(recommended, {
+            ...opts,
+            onProgress: (current, total, skillId) => output.progress(current, total, skillId),
+        });
+        output.success(`Installed ${installResult.installedCount} skill(s) from the recommended pack`);
+        for (const skill of installResult.installedSkills) {
+            output.info(`  + ${skill.id}@${skill.version}`);
+        }
+        printAutoSyncResult(installResult.autoSync);
+        return;
+    }
+    output.info("\nNext steps:");
+    output.info("  • Browse and install interactively:  skillex");
+    output.info("  • Install a curated starter pack:    skillex init --install-recommended");
+    output.info("  • List the full catalog:             skillex list");
 }
 async function handleList(flags, userConfig) {
     const opts = commonOptions(flags, userConfig);
@@ -352,7 +461,9 @@ async function handleSearch(positionals, flags, userConfig) {
     const aggregated = await loadProjectCatalogs({ ...opts, ...cacheOptions(opts) });
     const searchOptions = { query: positionals.join(" ") };
     const compatibility = asOptionalString(flags.compatibility);
-    const tag = asOptionalString(flags.tag);
+    // `--tag` is canonical; `--tags` is accepted as an alias because earlier README
+    // versions documented the plural form. The parser already permits both names.
+    const tag = asOptionalString(flags.tag) ?? asOptionalString(flags.tags);
     if (compatibility)
         searchOptions.compatibility = compatibility;
     if (tag)
@@ -426,9 +537,13 @@ async function handleRemove(positionals, flags, userConfig) {
     for (const skillId of result.missingSkills) {
         output.warn(`${skillId} is not installed`);
     }
-    printAutoSyncResult(result.autoSync);
+    // Remove can fan out across multiple previously-synced adapters; report each.
+    for (const sync of result.autoSyncs) {
+        printAutoSyncResult(sync);
+    }
 }
 async function handleSync(flags, userConfig) {
+    const exitCodeFlag = parseBooleanFlag(flags["exit-code"], "exit-code") ?? false;
     const result = await syncInstalledSkills(commonOptions(flags, userConfig));
     if (result.dryRun) {
         output.info(`Preview: ${result.skillCount} skill(s)`);
@@ -436,6 +551,10 @@ async function handleSync(flags, userConfig) {
             output.info(`  ${entry.adapter} → ${entry.targetPath} [${entry.syncMode}]${entry.changed ? "" : " (no changes)"}`);
         }
         process.stdout.write(result.diff);
+        // Mirror `git diff --exit-code`: when --exit-code is set, drift is a non-zero exit.
+        if (exitCodeFlag && result.changed) {
+            process.exitCode = 1;
+        }
         return;
     }
     output.success(`Synced ${result.skillCount} skill(s)`);
@@ -461,6 +580,52 @@ async function handleRun(positionals, flags, userConfig) {
         process.exitCode = exitCode;
     }
 }
+async function handleShow(positionals, flags, userConfig) {
+    const skillId = positionals[0];
+    if (!skillId) {
+        throw new CliError("Provide a skill id. Usage: skillex show <skill-id> [--raw|--json]", "SHOW_REQUIRES_SKILL");
+    }
+    const opts = commonOptions(flags, userConfig);
+    const aggregated = await loadProjectCatalogs({ ...opts, ...cacheOptions(opts) });
+    const matches = aggregated.skills.filter((s) => s.id === skillId);
+    if (matches.length === 0) {
+        throw new CliError(`Skill "${skillId}" not found in the configured sources.`, "SHOW_SKILL_NOT_FOUND");
+    }
+    if (matches.length > 1) {
+        const sourceList = matches.map((m) => `${m.source.repo}@${m.source.ref}`).join(", ");
+        throw new CliError(`Skill "${skillId}" exists in multiple sources: ${sourceList}. Use --repo to choose one.`, "SHOW_AMBIGUOUS_SOURCE");
+    }
+    const skill = matches[0];
+    const skillFile = skill.entry || "SKILL.md";
+    const remotePath = skill.path ? `${skill.path}/${skillFile}` : skillFile;
+    const url = buildRawGitHubUrl(skill.source.repo, skill.source.ref, remotePath);
+    const body = await fetchText(url, { headers: { Accept: "text/plain" } });
+    const raw = parseBooleanFlag(flags.raw, "raw") ?? false;
+    if (flags.json === true) {
+        output.info(JSON.stringify({
+            ...skill,
+            entryContent: body,
+        }, null, 2));
+        return;
+    }
+    if (raw) {
+        process.stdout.write(body.endsWith("\n") ? body : `${body}\n`);
+        return;
+    }
+    output.info(`${skill.name} (${skill.id}) — v${skill.version}`);
+    output.info(`Source       : ${skill.source.repo}@${skill.source.ref}${skill.source.label ? ` [${skill.source.label}]` : ""}`);
+    if (skill.author)
+        output.info(`Author       : ${skill.author}`);
+    if (skill.tags.length)
+        output.info(`Tags         : ${skill.tags.join(", ")}`);
+    if (skill.compatibility.length)
+        output.info(`Compatibility: ${skill.compatibility.join(", ")}`);
+    output.info(`Files        : ${skill.files.length}`);
+    output.info("");
+    output.info("─".repeat(60));
+    output.info("");
+    process.stdout.write(body.endsWith("\n") ? body : `${body}\n`);
+}
 async function handleBrowse(flags, userConfig) {
     const options = commonOptions(flags, userConfig);
     const state = await getInstalledSkills(options);
@@ -550,113 +715,12 @@ async function handleStatus(flags, userConfig) {
 }
 async function handleDoctor(flags, userConfig) {
     const opts = commonOptions(flags, userConfig);
-    const cwd = opts.cwd ?? process.cwd();
-    const statePaths = getScopedStatePaths(cwd, {
-        scope: opts.scope,
-        baseDir: opts.agentSkillsDir,
-    });
-    const checks = [];
-    // 1. Lockfile
-    const state = await getInstalledSkills(opts);
-    if (state) {
-        checks.push({ name: "lockfile", passed: true, message: `Found at ${statePaths.lockfilePath}` });
-    }
-    else {
-        checks.push({
-            name: "lockfile",
-            passed: false,
-            message: "Lockfile not found",
-            hint: "Run: skillex init",
-        });
-    }
-    // 2. Sources configured
-    const stateSources = state?.sources ?? [];
-    if (stateSources.length > 0) {
-        checks.push({
-            name: "source",
-            passed: true,
-            message: stateSources.map((source) => `${source.repo}@${source.ref}`).join(", "),
-        });
-    }
-    else {
-        checks.push({
-            name: "source",
-            passed: false,
-            message: "No catalog source configured",
-            hint: "Run: skillex init",
-        });
-    }
-    // 3. Adapter detected
-    const hasAdapter = Boolean(state?.adapters?.active || (state?.adapters?.detected?.length ?? 0) > 0);
-    if (hasAdapter) {
-        const adapter = state?.adapters?.active ?? state?.adapters?.detected?.[0];
-        checks.push({ name: "adapter", passed: true, message: `Active: ${adapter}` });
-    }
-    else {
-        checks.push({
-            name: "adapter",
-            passed: false,
-            message: "No adapter detected",
-            hint: `Use --adapter <id>. Available: ${listAdapters().map((a) => a.id).join(", ")}`,
-        });
-    }
-    // 4. GitHub reachable
-    try {
-        const response = await fetch("https://api.github.com", {
-            method: "HEAD",
-            headers: { "User-Agent": "skillex" },
-            signal: AbortSignal.timeout(5000),
-        });
-        if (response.status < 500) {
-            checks.push({ name: "github", passed: true, message: "GitHub API is reachable" });
-        }
-        else {
-            checks.push({
-                name: "github",
-                passed: false,
-                message: `GitHub API returned ${response.status}`,
-                hint: "Try again in a moment.",
-            });
-        }
-    }
-    catch {
-        checks.push({
-            name: "github",
-            passed: false,
-            message: "GitHub API is unreachable",
-            hint: "Check your internet connection or proxy settings.",
-        });
-    }
-    // 5. GitHub token (warning only — never fails)
-    const token = process.env.GITHUB_TOKEN;
-    if (token) {
-        checks.push({ name: "token", passed: true, message: "GitHub token set (authenticated — 5,000 req/hr)" });
-    }
-    else {
-        checks.push({ name: "token", passed: true, message: "No GitHub token (unauthenticated — 60 req/hr)" });
-    }
-    // 6. Cache
-    const cacheDir = path.join(statePaths.stateDir, ".cache");
-    if ((state?.sources?.length ?? 0) > 0) {
-        const source = await resolveProjectSource(opts);
-        const cacheKey = computeCatalogCacheKey(source);
-        const cached = await readCatalogCache(cacheDir, cacheKey);
-        if (cached) {
-            checks.push({ name: "cache", passed: true, message: "Catalog cache is fresh" });
-        }
-        else {
-            checks.push({ name: "cache", passed: true, message: "No cached catalog (will fetch on next command)" });
-        }
-    }
-    else {
-        checks.push({ name: "cache", passed: true, message: "Cache not checked (no repo configured)" });
-    }
-    const anyFailed = checks.some((c) => !c.passed);
+    const report = await runDoctorChecks(opts);
     if (flags.json === true) {
         const jsonResult = {};
-        for (const check of checks) {
+        for (const check of report.checks) {
             jsonResult[check.name] = {
-                passed: check.passed,
+                passed: check.status !== "fail",
                 message: check.message,
                 ...(check.hint ? { hint: check.hint } : {}),
             };
@@ -664,21 +728,27 @@ async function handleDoctor(flags, userConfig) {
         output.info(JSON.stringify(jsonResult, null, 2));
     }
     else {
-        for (const check of checks) {
-            const symbol = check.passed ? "✓" : "✗";
+        for (const check of report.checks) {
+            const symbol = check.status === "fail" ? "✗" : check.status === "warn" ? "⚠" : "✓";
             const line = `${symbol} ${check.name.padEnd(10)} ${check.message}`;
-            if (check.passed) {
-                output.info(line);
-            }
-            else {
+            if (check.status === "fail") {
                 output.error(line);
                 if (check.hint) {
                     output.info(`           Hint: ${check.hint}`);
                 }
             }
+            else if (check.status === "warn") {
+                output.warn(line);
+                if (check.hint) {
+                    output.info(`           Hint: ${check.hint}`);
+                }
+            }
+            else {
+                output.info(line);
+            }
         }
     }
-    if (anyFailed) {
+    if (report.hasFailures) {
         process.exitCode = 1;
     }
 }
@@ -791,13 +861,13 @@ function commonOptions(flags, userConfig = {}) {
     const skillsDir = asOptionalString(flags["skills-dir"]);
     const agentSkillsDir = asOptionalString(flags["agent-skills-dir"]);
     const adapter = asOptionalString(flags.adapter) ?? userConfig.defaultAdapter;
-    const autoSync = parseBooleanFlag(flags["auto-sync"]) ?? (userConfig.disableAutoSync ? false : undefined);
-    const dryRun = parseBooleanFlag(flags["dry-run"]);
-    const trust = parseBooleanFlag(flags.trust);
-    const yes = parseBooleanFlag(flags.yes);
+    const autoSync = parseBooleanFlag(flags["auto-sync"], "auto-sync") ?? (userConfig.disableAutoSync ? false : undefined);
+    const dryRun = parseBooleanFlag(flags["dry-run"], "dry-run");
+    const trust = parseBooleanFlag(flags.trust, "trust");
+    const yes = parseBooleanFlag(flags.yes, "yes");
     const mode = parseSyncMode(asOptionalString(flags.mode));
     const timeout = parsePositiveInt(asOptionalString(flags.timeout));
-    const noCache = parseBooleanFlag(flags["no-cache"]);
+    const noCache = parseBooleanFlag(flags["no-cache"], "no-cache");
     if (repo)
         options.repo = repo;
     if (ref)
@@ -842,7 +912,7 @@ function cacheOptions(opts) {
 }
 function resolveScope(flags) {
     const rawScope = asOptionalString(flags.scope);
-    const globalFlag = parseBooleanFlag(flags.global);
+    const globalFlag = parseBooleanFlag(flags.global, "global");
     if (rawScope && rawScope !== "local" && rawScope !== "global") {
         throw new CliError(`Invalid scope: ${rawScope}. Use "local" or "global".`, "INVALID_SCOPE");
     }
@@ -854,14 +924,35 @@ function resolveScope(flags) {
     }
     return rawScope || DEFAULT_INSTALL_SCOPE;
 }
-function parseArgs(argv) {
+/**
+ * Parses argv into a typed `ParsedArgs` shape with strict validation:
+ *
+ * - Unknown flags raise `UNKNOWN_FLAG` with a "did you mean" suggestion.
+ * - Boolean flags (`BOOLEAN_FLAGS`) accept presence-only or `--flag=value` forms.
+ * - String flags (`STRING_FLAGS`) require a value via `--flag=value` or
+ *   `--flag value`. Missing values raise `MISSING_FLAG_VALUE`.
+ * - The literal `--` token marks end-of-options; remaining tokens become
+ *   `positionalAfter` and are forwarded to handlers (used by `run` to pass
+ *   arguments to the underlying script without flag interpretation).
+ */
+export function parseArgs(argv) {
     const flags = {};
     const positionals = [];
+    const positionalAfter = [];
     let command;
+    let endOfOptions = false;
     for (let index = 0; index < argv.length; index += 1) {
         const token = argv[index];
         if (token === undefined)
             continue;
+        if (endOfOptions) {
+            positionalAfter.push(token);
+            continue;
+        }
+        if (token === "--") {
+            endOfOptions = true;
+            continue;
+        }
         if (!command && !token.startsWith("-")) {
             command = token;
             continue;
@@ -871,25 +962,39 @@ function parseArgs(argv) {
             continue;
         }
         if (token.startsWith("--")) {
-            const [rawKey, inlineValue] = token.slice(2).split("=", 2);
+            const eq = token.indexOf("=");
+            const rawKey = eq === -1 ? token.slice(2) : token.slice(2, eq);
+            const inlineValue = eq === -1 ? undefined : token.slice(eq + 1);
             if (!rawKey)
                 continue;
+            if (!KNOWN_FLAGS.has(rawKey)) {
+                const suggestion = suggestClosest(rawKey, [...KNOWN_FLAGS]);
+                throw new CliError(suggestion
+                    ? `Unknown flag: --${rawKey}. Did you mean --${suggestion}?`
+                    : `Unknown flag: --${rawKey}. Run 'skillex --help' to list flags.`, "UNKNOWN_FLAG");
+            }
             if (inlineValue !== undefined) {
                 flags[rawKey] = inlineValue;
                 continue;
             }
-            const next = argv[index + 1];
-            if (!next || next.startsWith("-")) {
+            // Boolean flag without an inline value: presence = true.
+            if (BOOLEAN_FLAGS.has(rawKey)) {
                 flags[rawKey] = true;
                 continue;
             }
+            // String flag: require a following value that is not another flag and not the
+            // end-of-options sentinel.
+            const next = argv[index + 1];
+            if (next === undefined || next === "--" || next.startsWith("-")) {
+                throw new CliError(`Missing value for --${rawKey}. Pass --${rawKey} <value> or --${rawKey}=<value>.`, "MISSING_FLAG_VALUE");
+            }
             flags[rawKey] = next;
             index += 1;
             continue;
         }
         positionals.push(token);
     }
-    return { command, positionals, flags };
+    return { command, positionals, positionalAfter, flags };
 }
 function printHelp() {
     output.info(`skillex — AI agent skill manager
@@ -943,7 +1048,7 @@ function truncate(value, maxLength) {
         return value;
     return `${value.slice(0, maxLength - 3)}...`;
 }
-function parseBooleanFlag(value) {
+function parseBooleanFlag(value, flagName) {
     if (value === undefined)
         return undefined;
     if (value === true)
@@ -953,7 +1058,8 @@ function parseBooleanFlag(value) {
         return true;
     if (["false", "0", "no", "off"].includes(normalized))
         return false;
-    throw new CliError(`Invalid boolean value: ${value}`, "INVALID_BOOLEAN_FLAG");
+    const target = flagName ? `--${flagName}` : "boolean flag";
+    throw new CliError(`Invalid value "${value}" for ${target}. Use true, false, yes, no, on, off, 1, or 0.`, "INVALID_BOOLEAN_FLAG");
 }
 function parsePositiveInt(value) {
     if (!value)

package/dist/confirm.js

@@ -10,12 +10,14 @@ import { CliError } from "./types.js";
  */
 export async function confirmAction(message) {
     if (!input.isTTY || !output.isTTY) {
-        throw new CliError("Confirmacao interativa indisponivel neste terminal. Use a flag correspondente.", "TTY_REQUIRED");
+        throw new CliError("Interactive confirmation is unavailable in this terminal. Use the matching CLI flag (e.g. --trust, --yes) to skip the prompt.", "TTY_REQUIRED");
     }
     const rl = createInterface({ input, output });
     try {
         const answer = await rl.question(`${message} [y/N] `);
         const normalized = answer.trim().toLowerCase();
+        // Accept English (y/yes) and historical Portuguese (s/sim) responses to avoid
+        // breaking muscle memory for existing users.
         return normalized === "y" || normalized === "yes" || normalized === "s" || normalized === "sim";
     }
     finally {

package/dist/direct-github.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Direct-GitHub install path. Parallels the catalog install path but reads
+ * `skill.json` (or `SKILL.md` frontmatter) directly from a GitHub
+ * repository, allowing users to install skills that are not yet published
+ * in any catalog source.
+ */
+import type { DirectGitHubRef, SkillManifest } from "./types.js";
+/** Resolved direct-install payload as returned by `fetchDirectGitHubSkill`. */
+export interface DirectInstallPayload {
+    manifest: SkillManifest;
+    repo: string;
+    ref: string;
+    source: string;
+}
+/** Trust-prompt options accepted by `confirmDirectInstall`. */
+export interface ConfirmDirectInstallOptions {
+    trust?: boolean | undefined;
+    confirm?: (() => Promise<boolean>) | undefined;
+    warn?: ((message: string) => void) | undefined;
+}
+/**
+ * Parses a direct GitHub install reference in `owner/repo[@ref]` format.
+ *
+ * The ref segment (when present) MUST match `^[A-Za-z0-9_.\-/]+$`. Empty
+ * refs (e.g. `owner/repo@`) and refs containing whitespace, newlines, or
+ * shell metacharacters are rejected with `CliError("INVALID_DIRECT_REF")`
+ * rather than silently defaulting to `main`.
+ *
+ * @param input - User-supplied install argument.
+ * @returns Parsed direct GitHub reference or `null` when the value is not a direct ref.
+ * @throws {CliError} When the value looks like a direct ref but the ref portion is invalid.
+ */
+export declare function parseDirectGitHubRef(input: string): DirectGitHubRef | null;
+/**
+ * Parses a `github:owner/repo@ref` source string from the lockfile back into a
+ * `DirectGitHubRef`.
+ */
+export declare function parseGitHubSource(source: string): DirectGitHubRef | null;
+/**
+ * Fetches the manifest for a direct-install skill, falling back to SKILL.md
+ * frontmatter when no `skill.json` is present at the repository root.
+ */
+export declare function fetchDirectGitHubSkill(reference: DirectGitHubRef): Promise<DirectInstallPayload>;
+/**
+ * Downloads the resolved direct-install skill into the managed skills store.
+ */
+export declare function downloadDirectGitHubSkill(skill: DirectInstallPayload, skillsDirPath: string): Promise<void>;
+/**
+ * Promotes a partial direct-install manifest into a fully-typed `SkillManifest`,
+ * providing safe defaults for missing fields.
+ */
+export declare function normalizeDirectManifest(manifest: Partial<SkillManifest> & {
+    scripts?: Record<string, string>;
+}, reference: DirectGitHubRef): SkillManifest;
+/**
+ * Prompts the user to confirm a direct GitHub install (skipped when the
+ * caller passes `trust: true`). Throws `InstallError` with code
+ * `INSTALL_CANCELLED` on rejection.
+ */
+export declare function confirmDirectInstall(skillRef: string, options: ConfirmDirectInstallOptions): Promise<void>;