@skillkit/core 1.16.0 → 1.17.0

package/dist/index.js

@@ -4555,6 +4555,16 @@ import { existsSync as existsSync7, mkdirSync as mkdirSync2, writeFileSync as wr
 import { join as join7, basename as basename6, resolve as resolve3, sep as sep2 } from "path";
 import { tmpdir as tmpdir4 } from "os";
 import { randomUUID as randomUUID4 } from "crypto";
+function skillNameFromUrl(url) {
+  try {
+    const parsed = new URL(url);
+    const segments = parsed.pathname.split("/").filter(Boolean);
+    return segments[segments.length - 1] || parsed.hostname.split(".")[0] || "default";
+  } catch {
+    return basename6(url) || "default";
+  }
+}
+var FRONTMATTER_REGEX = /^---\s*\n[\s\S]*?name:\s*.+/;
 function sanitizeSkillName(name) {
   if (!name || typeof name !== "string") return null;
   const base = basename6(name);
@@ -4566,6 +4576,11 @@ function sanitizeSkillName(name) {
   }
   return name;
 }
+var MINTLIFY_PATHS = [
+  "/.well-known/skills/default/skill.md",
+  "/skill.md",
+  "/.well-known/skill.md"
+];
 var WellKnownProvider = class {
   type = "wellknown";
   name = "Well-Known";
@@ -4597,6 +4612,51 @@ var WellKnownProvider = class {
   getSshUrl(_owner, _repo) {
     return "";
   }
+  async discoverFromUrl(url) {
+    const baseUrl = url.replace(/\/$/, "");
+    const tempDir = join7(tmpdir4(), `skillkit-wellknown-${randomUUID4()}`);
+    try {
+      mkdirSync2(tempDir, { recursive: true });
+      for (const mintlifyPath of MINTLIFY_PATHS) {
+        const fullUrl = `${baseUrl}${mintlifyPath}`;
+        try {
+          const response = await fetch(fullUrl);
+          if (response.ok) {
+            const content = await response.text();
+            if (FRONTMATTER_REGEX.test(content)) {
+              const skillName = skillNameFromUrl(baseUrl);
+              const safeName = sanitizeSkillName(skillName) ?? "default";
+              const skillDir = join7(tempDir, safeName);
+              mkdirSync2(skillDir, { recursive: true });
+              writeFileSync2(join7(skillDir, "SKILL.md"), content);
+              return {
+                success: true,
+                path: tempDir,
+                tempRoot: tempDir,
+                skills: [safeName],
+                discoveredSkills: [{ name: safeName, dirName: safeName, path: skillDir }]
+              };
+            }
+          }
+        } catch {
+          continue;
+        }
+      }
+      const indexResult = await this.clone(baseUrl, "", {});
+      if (indexResult.success) {
+        rmSync4(tempDir, { recursive: true, force: true });
+        return indexResult;
+      }
+      rmSync4(tempDir, { recursive: true, force: true });
+      return { success: false, error: "No well-known skills found" };
+    } catch (error) {
+      if (existsSync7(tempDir)) {
+        rmSync4(tempDir, { recursive: true, force: true });
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      return { success: false, error: `Failed to discover skills: ${message}` };
+    }
+  }
   async clone(source, _targetDir, _options = {}) {
     const tempDir = join7(tmpdir4(), `skillkit-wellknown-${randomUUID4()}`);
     try {
@@ -4621,6 +4681,32 @@ var WellKnownProvider = class {
         }
       }
       if (!index || !index.skills || index.skills.length === 0) {
+        for (const mintlifyPath of MINTLIFY_PATHS) {
+          const fullUrl = `${baseUrl}${mintlifyPath}`;
+          try {
+            const response = await fetch(fullUrl);
+            if (response.ok) {
+              const content = await response.text();
+              if (FRONTMATTER_REGEX.test(content)) {
+                const skillName = skillNameFromUrl(baseUrl);
+                const safeName = sanitizeSkillName(skillName) ?? "default";
+                const skillDir = join7(tempDir, safeName);
+                mkdirSync2(skillDir, { recursive: true });
+                writeFileSync2(join7(skillDir, "SKILL.md"), content);
+                return {
+                  success: true,
+                  path: tempDir,
+                  tempRoot: tempDir,
+                  skills: [safeName],
+                  discoveredSkills: [{ name: safeName, dirName: safeName, path: skillDir }]
+                };
+              }
+            }
+          } catch {
+            continue;
+          }
+        }
+        rmSync4(tempDir, { recursive: true, force: true });
         return {
           success: false,
           error: `No skills found at ${baseUrl}/.well-known/skills/index.json`
@@ -27643,10 +27729,37 @@ function evaluateSkillFile(filePath) {
     return null;
   }
 }
+function checkNameDirectoryMatch(content, dirPath) {
+  const frontmatter = extractFrontmatter4(content);
+  if (!frontmatter || typeof frontmatter.name !== "string") return null;
+  const dirName = basename17(dirPath);
+  if (frontmatter.name !== dirName) {
+    return `Skill name "${frontmatter.name}" does not match directory "${dirName}"`;
+  }
+  return null;
+}
+function checkTokenBudget(content) {
+  const normalizedContent = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  const fmMatch = normalizedContent.match(/^---\s*\n[\s\S]*?\n---\s*\n?/);
+  const body = fmMatch ? normalizedContent.slice(fmMatch[0].length) : normalizedContent;
+  const bodyLines = body.split("\n").length;
+  if (bodyLines > 500) {
+    return `Body is ${bodyLines} lines (exceeds 500). Consider moving content to references/ directory`;
+  }
+  return null;
+}
 function evaluateSkillDirectory(dirPath) {
   const skillMdPath = join42(dirPath, "SKILL.md");
   if (existsSync41(skillMdPath)) {
-    return evaluateSkillFile(skillMdPath);
+    const result = evaluateSkillFile(skillMdPath);
+    if (result) {
+      const content = readFileSync30(skillMdPath, "utf-8");
+      const nameWarning = checkNameDirectoryMatch(content, dirPath);
+      if (nameWarning) result.warnings.push(nameWarning);
+      const budgetWarning = checkTokenBudget(content);
+      if (budgetWarning) result.warnings.push(budgetWarning);
+    }
+    return result;
   }
   const mdcFiles = ["index.mdc", `${basename17(dirPath)}.mdc`];
   for (const file of mdcFiles) {
@@ -33181,7 +33294,7 @@ var SkillScanner = class {
 
 // src/scanner/reporter.ts
 import { basename as basename21 } from "path";
-var SCANNER_VERSION = true ? "1.16.0" : "0.0.0";
+var SCANNER_VERSION = true ? "1.17.0" : "0.0.0";
 var SEVERITY_COLORS = {
   ["critical" /* CRITICAL */]: "\x1B[91m",
   ["high" /* HIGH */]: "\x1B[31m",
@@ -33452,6 +33565,764 @@ function getThreatInfo(category) {
 function getDefaultSeverity(category) {
   return THREAT_TAXONOMY[category].defaultSeverity;
 }
+
+// src/validation/spec-validator.ts
+import { readFileSync as readFileSync38, existsSync as existsSync53 } from "fs";
+import { join as join54, basename as basename22 } from "path";
+var NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+var SPEC_VERSION = "1.0";
+var SpecValidator = class {
+  validate(skillPath, options) {
+    const checks = [];
+    const errors = [];
+    const warnings = [];
+    const skillMdPath = skillPath.endsWith(".md") ? skillPath : join54(skillPath, "SKILL.md");
+    if (!existsSync53(skillMdPath)) {
+      errors.push(`SKILL.md not found at ${skillMdPath}`);
+      return { valid: false, errors, warnings, specVersion: SPEC_VERSION, checks };
+    }
+    const raw = readFileSync38(skillMdPath, "utf-8");
+    const { frontmatter, body } = stripFrontmatter(raw);
+    const hasName = typeof frontmatter.name === "string" && frontmatter.name.length > 0;
+    checks.push({
+      name: "name-present",
+      passed: hasName,
+      message: hasName ? "Name field is present" : 'Missing required "name" field in frontmatter',
+      severity: hasName ? "info" : "error"
+    });
+    if (!hasName) errors.push('Missing required "name" field in frontmatter');
+    const hasDescription = typeof frontmatter.description === "string" && frontmatter.description.length > 0;
+    checks.push({
+      name: "description-present",
+      passed: hasDescription,
+      message: hasDescription ? "Description field is present" : 'Missing required "description" field in frontmatter',
+      severity: hasDescription ? "info" : "error"
+    });
+    if (!hasDescription) errors.push('Missing required "description" field in frontmatter');
+    if (hasName) {
+      const nameStr = frontmatter.name;
+      const nameValid = NAME_PATTERN.test(nameStr);
+      checks.push({
+        name: "name-format",
+        passed: nameValid,
+        message: nameValid ? "Name matches required pattern" : `Name "${nameStr}" does not match pattern: lowercase alphanumeric with hyphens`,
+        severity: nameValid ? "info" : "error"
+      });
+      if (!nameValid) errors.push(`Name "${nameStr}" does not match pattern: lowercase alphanumeric with hyphens`);
+    }
+    if (options?.strict) {
+      if (frontmatter.version !== void 0) {
+        warnings.push("version should be under metadata.skillkit-version");
+        checks.push({
+          name: "version-placement",
+          passed: false,
+          message: "version should be under metadata.skillkit-version",
+          severity: "warning"
+        });
+      }
+      if (frontmatter.author !== void 0) {
+        warnings.push("author should be under metadata.skillkit-author");
+        checks.push({
+          name: "author-placement",
+          passed: false,
+          message: "author should be under metadata.skillkit-author",
+          severity: "warning"
+        });
+      }
+      if (frontmatter.tags !== void 0) {
+        warnings.push("tags should be under metadata.skillkit-tags");
+        checks.push({
+          name: "tags-placement",
+          passed: false,
+          message: "tags should be under metadata.skillkit-tags",
+          severity: "warning"
+        });
+      }
+      if (frontmatter.agents !== void 0) {
+        warnings.push("agents should be under metadata.skillkit-agents");
+        checks.push({
+          name: "agents-placement",
+          passed: false,
+          message: "agents should be under metadata.skillkit-agents",
+          severity: "warning"
+        });
+      }
+      if (hasName) {
+        const skillDir = skillPath.endsWith(".md") ? join54(skillPath, "..") : skillPath;
+        const dirName = basename22(skillDir);
+        const nameStr = frontmatter.name;
+        const nameMatchesDir = nameStr === dirName;
+        checks.push({
+          name: "name-directory-match",
+          passed: nameMatchesDir,
+          message: nameMatchesDir ? "Name matches directory" : `Name "${nameStr}" does not match directory "${dirName}"`,
+          severity: nameMatchesDir ? "info" : "warning"
+        });
+        if (!nameMatchesDir) warnings.push(`Name "${nameStr}" does not match directory "${dirName}"`);
+      }
+      const bodyLines = body.split("\n").length;
+      const bodyWithinLimit = bodyLines <= 500;
+      checks.push({
+        name: "body-length",
+        passed: bodyWithinLimit,
+        message: bodyWithinLimit ? `Body is ${bodyLines} lines` : `Body is ${bodyLines} lines (exceeds 500). Consider moving content to references/ directory`,
+        severity: bodyWithinLimit ? "info" : "warning"
+      });
+      if (!bodyWithinLimit) warnings.push(`Body is ${bodyLines} lines (exceeds 500). Consider moving content to references/ directory`);
+    }
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+      specVersion: SPEC_VERSION,
+      checks
+    };
+  }
+};
+
+// src/agents-md/generator.ts
+import { existsSync as existsSync54, readFileSync as readFileSync39 } from "fs";
+import { join as join55 } from "path";
+function escapeTableCell(text) {
+  return text.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+var MANAGED_START = "<!-- skillkit:managed:start -->";
+var MANAGED_END = "<!-- skillkit:managed:end -->";
+var AgentsMdGenerator = class {
+  config;
+  detector;
+  constructor(config) {
+    this.config = config;
+    this.detector = new ProjectDetector(config.projectPath);
+  }
+  generate() {
+    this.detector.analyze();
+    const sections = [];
+    sections.push({
+      id: "project-overview",
+      title: "Project Overview",
+      content: this.generateProjectSection(),
+      managed: true
+    });
+    sections.push({
+      id: "technology-stack",
+      title: "Technology Stack",
+      content: this.generateStackSection(),
+      managed: true
+    });
+    if (this.config.includeSkills !== false) {
+      const skillsContent = this.generateSkillsSection(findAllSkills([join55(this.config.projectPath, "skills")]));
+      if (skillsContent) {
+        sections.push({
+          id: "installed-skills",
+          title: "Installed Skills",
+          content: skillsContent,
+          managed: true
+        });
+      }
+    }
+    if (this.config.includeBuildCommands !== false) {
+      const buildContent = this.generateBuildSection();
+      if (buildContent) {
+        sections.push({
+          id: "build-test",
+          title: "Build & Test",
+          content: buildContent,
+          managed: true
+        });
+      }
+    }
+    if (this.config.includeCodeStyle !== false) {
+      const styleContent = this.generateCodeStyleSection();
+      if (styleContent) {
+        sections.push({
+          id: "code-style",
+          title: "Code Style",
+          content: styleContent,
+          managed: true
+        });
+      }
+    }
+    const lines = ["# AGENTS.md", "", MANAGED_START];
+    for (const section of sections) {
+      lines.push(`## ${section.title}`);
+      lines.push(section.content);
+      lines.push("");
+    }
+    lines.push(MANAGED_END, "");
+    const content = lines.join("\n");
+    return {
+      content,
+      sections,
+      path: join55(this.config.projectPath, "AGENTS.md")
+    };
+  }
+  generateSkillsSection(skills) {
+    if (skills.length === 0) {
+      return "";
+    }
+    const lines = [
+      "| Skill | Description | Tags |",
+      "|-------|-------------|------|"
+    ];
+    for (const skill of skills) {
+      const name = escapeTableCell(skill.name);
+      const desc = escapeTableCell(skill.description);
+      lines.push(`| ${name} | ${desc} | |`);
+    }
+    return lines.join("\n");
+  }
+  generateProjectSection() {
+    const name = this.detector.getProjectName();
+    const description = this.detector.getProjectDescription();
+    const projectType = this.detector.detectProjectType();
+    const lines = [];
+    lines.push(`- **Name**: ${name}`);
+    if (description) {
+      lines.push(`- **Description**: ${description}`);
+    }
+    lines.push(`- **Type**: ${projectType}`);
+    return lines.join("\n");
+  }
+  generateBuildSection() {
+    const packageJsonPath = join55(this.config.projectPath, "package.json");
+    if (!existsSync54(packageJsonPath)) {
+      return "";
+    }
+    try {
+      const pkg = JSON.parse(readFileSync39(packageJsonPath, "utf-8"));
+      const scripts = pkg.scripts;
+      if (!scripts || Object.keys(scripts).length === 0) {
+        return "";
+      }
+      const relevantScripts = ["build", "dev", "start", "test", "lint", "format", "typecheck", "check"];
+      const lines = ["```bash"];
+      for (const key of relevantScripts) {
+        if (scripts[key]) {
+          lines.push(`# ${key}`);
+          lines.push(scripts[key]);
+          lines.push("");
+        }
+      }
+      if (lines.length === 1) {
+        return "";
+      }
+      lines.push("```");
+      return lines.join("\n");
+    } catch {
+      return "";
+    }
+  }
+  generateCodeStyleSection() {
+    const patterns = this.detector.detectPatterns();
+    const lines = [];
+    if (patterns.linting) {
+      lines.push(`- **Linting**: ${patterns.linting}`);
+    }
+    if (patterns.formatting) {
+      lines.push(`- **Formatting**: ${patterns.formatting}`);
+    }
+    if (patterns.testing) {
+      lines.push(`- **Testing**: ${patterns.testing}`);
+    }
+    if (patterns.styling) {
+      lines.push(`- **Styling**: ${patterns.styling}`);
+    }
+    return lines.length > 0 ? lines.join("\n") : "";
+  }
+  generateStackSection() {
+    const stack = this.detector.analyze();
+    const lines = [];
+    if (stack.languages.length > 0) {
+      lines.push(`- **Languages**: ${stack.languages.map((l) => l.version ? `${l.name} ${l.version}` : l.name).join(", ")}`);
+    }
+    if (stack.frameworks.length > 0) {
+      lines.push(`- **Frameworks**: ${stack.frameworks.map((f) => f.version ? `${f.name} ${f.version}` : f.name).join(", ")}`);
+    }
+    if (stack.libraries.length > 0) {
+      lines.push(`- **Libraries**: ${stack.libraries.map((l) => l.name).join(", ")}`);
+    }
+    if (stack.databases.length > 0) {
+      lines.push(`- **Databases**: ${stack.databases.map((d) => d.name).join(", ")}`);
+    }
+    if (stack.runtime.length > 0) {
+      lines.push(`- **Runtime**: ${stack.runtime.map((r) => r.version ? `${r.name} ${r.version}` : r.name).join(", ")}`);
+    }
+    return lines.length > 0 ? lines.join("\n") : "No technology stack detected.";
+  }
+};
+
+// src/agents-md/parser.ts
+var MANAGED_START2 = "<!-- skillkit:managed:start -->";
+var MANAGED_END2 = "<!-- skillkit:managed:end -->";
+var AgentsMdParser = class {
+  parse(content) {
+    const sections = [];
+    const lines = content.split("\n");
+    let inManaged = false;
+    let currentSection = null;
+    for (const line of lines) {
+      if (line.trim() === MANAGED_START2) {
+        inManaged = true;
+        continue;
+      }
+      if (line.trim() === MANAGED_END2) {
+        if (currentSection) {
+          sections.push({
+            id: currentSection.id,
+            title: currentSection.title,
+            content: currentSection.lines.join("\n").trim(),
+            managed: currentSection.managed
+          });
+          currentSection = null;
+        }
+        inManaged = false;
+        continue;
+      }
+      const headingMatch = line.match(/^##\s+(.+)$/);
+      if (headingMatch) {
+        if (currentSection) {
+          sections.push({
+            id: currentSection.id,
+            title: currentSection.title,
+            content: currentSection.lines.join("\n").trim(),
+            managed: currentSection.managed
+          });
+        }
+        const title = headingMatch[1];
+        currentSection = {
+          id: title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, ""),
+          title,
+          lines: [],
+          managed: inManaged
+        };
+        continue;
+      }
+      if (currentSection) {
+        currentSection.lines.push(line);
+      }
+    }
+    if (currentSection) {
+      sections.push({
+        id: currentSection.id,
+        title: currentSection.title,
+        content: currentSection.lines.join("\n").trim(),
+        managed: currentSection.managed
+      });
+    }
+    return sections;
+  }
+  hasManagedSections(content) {
+    return content.includes(MANAGED_START2) && content.includes(MANAGED_END2);
+  }
+  updateManagedSections(existing, newManaged) {
+    if (!this.hasManagedSections(existing)) {
+      return existing;
+    }
+    const startIdx = existing.indexOf(MANAGED_START2);
+    const endIdx = existing.indexOf(MANAGED_END2);
+    if (startIdx >= endIdx) {
+      return existing;
+    }
+    const managedBlock = this.buildManagedBlock(newManaged);
+    const before = existing.substring(0, startIdx);
+    const after = existing.substring(endIdx + MANAGED_END2.length);
+    return `${before}${managedBlock}${after}`;
+  }
+  buildManagedBlock(sections) {
+    const lines = [MANAGED_START2];
+    for (const section of sections) {
+      lines.push(`## ${section.title}`);
+      lines.push(section.content);
+      lines.push("");
+    }
+    lines.push(MANAGED_END2);
+    return lines.join("\n");
+  }
+};
+
+// src/save/extractor.ts
+import { existsSync as existsSync55, readFileSync as readFileSync40 } from "fs";
+import { basename as basename23, extname as extname7 } from "path";
+import TurndownService from "turndown";
+var LANGUAGE_MAP = {
+  ".ts": "typescript",
+  ".tsx": "typescript",
+  ".js": "javascript",
+  ".jsx": "javascript",
+  ".py": "python",
+  ".rb": "ruby",
+  ".go": "go",
+  ".rs": "rust",
+  ".java": "java",
+  ".kt": "kotlin",
+  ".swift": "swift",
+  ".c": "c",
+  ".cpp": "cpp",
+  ".cs": "csharp",
+  ".php": "php",
+  ".sh": "shell",
+  ".bash": "shell",
+  ".zsh": "shell",
+  ".yml": "yaml",
+  ".yaml": "yaml",
+  ".json": "json",
+  ".toml": "toml",
+  ".md": "markdown",
+  ".mdx": "markdown",
+  ".html": "html",
+  ".css": "css",
+  ".scss": "scss",
+  ".sql": "sql",
+  ".r": "r",
+  ".lua": "lua",
+  ".dart": "dart",
+  ".ex": "elixir",
+  ".exs": "elixir",
+  ".zig": "zig",
+  ".nim": "nim",
+  ".vue": "vue",
+  ".svelte": "svelte"
+};
+var GITHUB_URL_PATTERN = /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/([^/]+)\/(.+)$/;
+var GITHUB_RAW_PATTERN = /^https?:\/\/raw\.githubusercontent\.com\//;
+var FETCH_TIMEOUT = 3e4;
+var ContentExtractor = class {
+  turndown;
+  constructor() {
+    this.turndown = new TurndownService({
+      headingStyle: "atx",
+      codeBlockStyle: "fenced"
+    });
+  }
+  async extractFromUrl(url, options) {
+    if (this.isGitHubUrl(url)) {
+      return this.fetchGitHubContent(url, options);
+    }
+    const response = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT) });
+    if (!response.ok) {
+      throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    const body = await response.text();
+    if (contentType.includes("text/html")) {
+      const { title: title2, content } = this.htmlToMarkdown(body, url);
+      const finalContent2 = options?.maxLength ? content.slice(0, options.maxLength) : content;
+      return {
+        title: options?.preferredTitle ?? title2,
+        content: finalContent2,
+        sourceUrl: url,
+        tags: [],
+        extractedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        contentType: "webpage",
+        metadata: { url }
+      };
+    }
+    const title = options?.preferredTitle ?? new URL(url).pathname.split("/").pop() ?? "Untitled";
+    const finalContent = options?.maxLength ? body.slice(0, options.maxLength) : body;
+    return {
+      title,
+      content: finalContent,
+      sourceUrl: url,
+      tags: [],
+      extractedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      contentType: "text",
+      metadata: { url }
+    };
+  }
+  extractFromText(text, options) {
+    const firstLine = text.split("\n")[0]?.trim() ?? "";
+    const title = options?.preferredTitle ?? (firstLine.length > 0 && firstLine.length <= 100 ? firstLine : "Untitled");
+    const content = options?.maxLength ? text.slice(0, options.maxLength) : text;
+    return {
+      title,
+      content,
+      tags: [],
+      extractedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      contentType: "text",
+      metadata: {}
+    };
+  }
+  extractFromFile(filePath, options) {
+    if (!existsSync55(filePath)) {
+      throw new Error(`File not found: ${filePath}`);
+    }
+    const raw = readFileSync40(filePath, "utf-8");
+    const name = basename23(filePath);
+    const language = this.detectLanguage(name);
+    const isCode = language !== void 0 && language !== "markdown";
+    const title = options?.preferredTitle ?? name;
+    const content = options?.maxLength ? raw.slice(0, options.maxLength) : raw;
+    return {
+      title,
+      content: isCode ? `\`\`\`${language}
+${content}
+\`\`\`` : content,
+      sourcePath: filePath,
+      tags: language ? [language] : [],
+      extractedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      contentType: isCode ? "code" : "file",
+      language,
+      metadata: { filename: name }
+    };
+  }
+  isGitHubUrl(url) {
+    return GITHUB_URL_PATTERN.test(url) || GITHUB_RAW_PATTERN.test(url);
+  }
+  async fetchGitHubContent(url, options) {
+    let rawUrl = url;
+    const match = url.match(GITHUB_URL_PATTERN);
+    if (match) {
+      const [, owner, repo, branch, path4] = match;
+      rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${path4}`;
+    }
+    const response = await fetch(rawUrl, { signal: AbortSignal.timeout(FETCH_TIMEOUT) });
+    if (!response.ok) {
+      throw new Error(`Failed to fetch GitHub content: ${response.status} ${response.statusText}`);
+    }
+    const body = await response.text();
+    const filename = rawUrl.split("/").pop() ?? "file";
+    const language = this.detectLanguage(filename);
+    const isCode = language !== void 0 && language !== "markdown";
+    const title = options?.preferredTitle ?? filename;
+    const content = options?.maxLength ? body.slice(0, options.maxLength) : body;
+    return {
+      title,
+      content: isCode ? `\`\`\`${language}
+${content}
+\`\`\`` : content,
+      sourceUrl: url,
+      tags: language ? ["github", language] : ["github"],
+      extractedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      contentType: "github",
+      language,
+      metadata: {
+        url,
+        rawUrl,
+        filename
+      }
+    };
+  }
+  htmlToMarkdown(html, url) {
+    const titleMatch = html.match(/<title[^>]*>([^<]+)<\/title>/i);
+    const title = titleMatch?.[1]?.trim() ?? new URL(url).hostname;
+    const bodyMatch = html.match(/<body[^>]*>([\s\S]*)<\/body>/i);
+    const bodyHtml = bodyMatch?.[1] ?? html;
+    const content = this.turndown.turndown(bodyHtml);
+    return { title, content };
+  }
+  detectLanguage(filename) {
+    const ext = extname7(filename).toLowerCase();
+    return LANGUAGE_MAP[ext];
+  }
+};
+
+// src/save/tagger.ts
+var TECH_KEYWORDS = /* @__PURE__ */ new Set([
+  "react",
+  "vue",
+  "angular",
+  "svelte",
+  "nextjs",
+  "nuxt",
+  "remix",
+  "typescript",
+  "javascript",
+  "python",
+  "rust",
+  "go",
+  "java",
+  "ruby",
+  "node",
+  "deno",
+  "bun",
+  "docker",
+  "kubernetes",
+  "terraform",
+  "aws",
+  "gcp",
+  "azure",
+  "vercel",
+  "netlify",
+  "cloudflare",
+  "graphql",
+  "rest",
+  "grpc",
+  "websocket",
+  "redis",
+  "postgres",
+  "mongodb",
+  "sqlite",
+  "mysql",
+  "prisma",
+  "drizzle",
+  "tailwind",
+  "css",
+  "html",
+  "sass",
+  "webpack",
+  "vite",
+  "esbuild",
+  "git",
+  "ci",
+  "cd",
+  "testing",
+  "security",
+  "authentication",
+  "api",
+  "cli",
+  "sdk",
+  "mcp",
+  "llm",
+  "ai",
+  "ml",
+  "openai",
+  "anthropic"
+]);
+var TAG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+var AutoTagger = class {
+  detectTags(content) {
+    const tagCounts = /* @__PURE__ */ new Map();
+    this.extractFromUrl(content.sourceUrl, tagCounts);
+    this.extractFromHeadings(content.content, tagCounts);
+    this.extractFromCodeBlocks(content.content, tagCounts);
+    this.extractFromKeywords(content.content, tagCounts);
+    if (content.language) {
+      this.addTag(content.language.toLowerCase(), tagCounts, 3);
+    }
+    if (content.contentType !== "text") {
+      this.addTag(content.contentType, tagCounts, 1);
+    }
+    return Array.from(tagCounts.entries()).sort((a, b) => b[1] - a[1]).slice(0, 10).map(([tag]) => tag);
+  }
+  extractFromUrl(url, counts) {
+    if (!url) return;
+    try {
+      const parsed = new URL(url);
+      const segments = parsed.pathname.split("/").filter(Boolean).map((s) => s.toLowerCase().replace(/[^a-z0-9-]/g, ""));
+      for (const seg of segments) {
+        if (seg.length >= 2 && seg.length <= 30 && TAG_PATTERN.test(seg)) {
+          this.addTag(seg, counts, 2);
+        }
+      }
+    } catch {
+    }
+  }
+  extractFromHeadings(content, counts) {
+    const headingRe = /^#{1,2}\s+(.+)$/gm;
+    let match;
+    while ((match = headingRe.exec(content)) !== null) {
+      const words = match[1].toLowerCase().split(/\s+/);
+      for (const word of words) {
+        const cleaned = word.replace(/[^a-z0-9-]/g, "");
+        if (cleaned.length >= 2 && TAG_PATTERN.test(cleaned)) {
+          this.addTag(cleaned, counts, 2);
+        }
+      }
+    }
+  }
+  extractFromCodeBlocks(content, counts) {
+    const codeBlockRe = /^```(\w+)/gm;
+    let match;
+    while ((match = codeBlockRe.exec(content)) !== null) {
+      const lang = match[1].toLowerCase();
+      if (lang.length >= 2 && TAG_PATTERN.test(lang)) {
+        this.addTag(lang, counts, 3);
+      }
+    }
+  }
+  extractFromKeywords(content, counts) {
+    const lower = content.toLowerCase();
+    for (const keyword of TECH_KEYWORDS) {
+      const re = new RegExp(`\\b${keyword}\\b`, "i");
+      if (re.test(lower)) {
+        this.addTag(keyword, counts, 1);
+      }
+    }
+  }
+  addTag(tag, counts, weight) {
+    if (!TAG_PATTERN.test(tag)) return;
+    counts.set(tag, (counts.get(tag) ?? 0) + weight);
+  }
+};
+
+// src/save/skill-generator.ts
+import { mkdirSync as mkdirSync28, writeFileSync as writeFileSync28 } from "fs";
+import { join as join56 } from "path";
+import { homedir as homedir19 } from "os";
+var MAX_NAME_LENGTH = 64;
+var SUMMARY_LINE_LIMIT = 100;
+var SPLIT_THRESHOLD = 500;
+var DESCRIPTION_MAX = 200;
+var SkillGenerator = class {
+  tagger = new AutoTagger();
+  generate(content, options = {}) {
+    const name = options.name ? this.slugify(options.name) : this.slugify(content.title || "untitled-skill");
+    const tags = this.tagger.detectTags(content);
+    const description = this.makeDescription(content.content);
+    const source = content.sourceUrl ?? content.sourcePath ?? "";
+    const frontmatter = this.buildFrontmatter(name, description, tags, source);
+    const lines = content.content.split("\n");
+    const needsSplit = lines.length > SPLIT_THRESHOLD;
+    const body = needsSplit ? lines.slice(0, SUMMARY_LINE_LIMIT).join("\n") : content.content;
+    const skillMd = `${frontmatter}
+${body}
+`;
+    const outputDir = options.outputDir ?? this.defaultOutputDir(name, options.global);
+    mkdirSync28(outputDir, { recursive: true });
+    const skillPath = join56(outputDir, "SKILL.md");
+    writeFileSync28(skillPath, skillMd, "utf-8");
+    if (needsSplit) {
+      const refsDir = join56(outputDir, "references");
+      mkdirSync28(refsDir, { recursive: true });
+      writeFileSync28(
+        join56(refsDir, "full-content.md"),
+        content.content,
+        "utf-8"
+      );
+    }
+    return { skillPath, skillMd, name };
+  }
+  slugify(input) {
+    const slug = input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").replace(/-{2,}/g, "-");
+    const trimmed = slug.slice(0, MAX_NAME_LENGTH).replace(/-+$/, "");
+    return trimmed || "untitled-skill";
+  }
+  makeDescription(content) {
+    const firstLine = content.split("\n").find((l) => l.trim().length > 0) ?? "";
+    const cleaned = firstLine.replace(/^#+\s*/, "").trim();
+    return cleaned.length > DESCRIPTION_MAX ? cleaned.slice(0, DESCRIPTION_MAX - 3) + "..." : cleaned || "Saved skill";
+  }
+  buildFrontmatter(name, description, tags, source) {
+    const yamlTags = tags.map((t) => `  - ${t}`).join("\n");
+    const savedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const lines = [
+      "---",
+      `name: ${name}`,
+      `description: ${this.yamlEscape(description)}`,
+      tags.length > 0 ? `tags:
+${yamlTags}` : null,
+      "metadata:",
+      source ? `  source: ${source}` : null,
+      `  savedAt: ${savedAt}`,
+      "---"
+    ].filter((l) => l !== null);
+    return lines.join("\n") + "\n";
+  }
+  yamlEscape(value) {
+    const singleLine = value.replace(/\r?\n/g, " ").trim();
+    if (/[:#{}[\],&*?|>!%@`]/.test(singleLine) || singleLine.startsWith("'") || singleLine.startsWith('"')) {
+      return `"${singleLine.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    }
+    return singleLine;
+  }
+  defaultOutputDir(name, global) {
+    if (global) {
+      return join56(homedir19(), ".skillkit", "skills", name);
+    }
+    return join56(".skillkit", "skills", name);
+  }
+};
 export {
   AGENT_CLI_CONFIGS,
   AGENT_CONFIG,
@@ -33471,8 +34342,11 @@ export {
   AgentOptimizer,
   AgentPermissionMode,
   AgentType,
+  AgentsMdGenerator,
+  AgentsMdParser,
   AnthropicProvider,
   AuditLogger,
+  AutoTagger,
   BUILTIN_PIPELINES,
   BaseAIProvider,
   BitbucketProvider,
@@ -33493,6 +34367,7 @@ export {
   ConnectorConfigSchema,
   ConnectorMappingSchema,
   ConnectorPlaceholderSchema,
+  ContentExtractor,
   ContextEngine,
   ContextLoader,
   ContextManager,
@@ -33597,6 +34472,7 @@ export {
   SkillComposer,
   SkillExecutionEngine,
   SkillFrontmatter,
+  SkillGenerator,
   SkillInjector,
   SkillLocation,
   SkillMdTranslator,
@@ -33609,6 +34485,7 @@ export {
   SkillWizard,
   SkillkitConfig,
   SkillsSource,
+  SpecValidator,
   StaticAnalyzer,
   TAG_TO_CATEGORY,
   TAG_TO_TECH,