@skill-tools/core 0.1.0

package/dist/index.js

@@ -0,0 +1,370 @@
+import { existsSync } from 'fs';
+import { readFile, stat, readdir } from 'fs/promises';
+import { isAbsolute, resolve, dirname, basename, join } from 'path';
+import matter from 'gray-matter';
+import { encodingForModel } from 'js-tiktoken';
+
+// src/parser.ts
+var encoder = null;
+function getEncoder() {
+  if (!encoder) {
+    encoder = encodingForModel("gpt-4o");
+  }
+  return encoder;
+}
+function countTokens(text) {
+  if (text.length === 0) {
+    return 0;
+  }
+  const enc = getEncoder();
+  return enc.encode(text).length;
+}
+
+// src/parser.ts
+var FILE_REFERENCE_PATTERN = /(?:^|\s|`)((?:scripts|references|assets)\/[\w./-]+(?:\.\w+)?)/gm;
+var MARKDOWN_LINK_PATTERN = /\[([^\]]*)\]\((?!https?:\/\/)([^)]+)\)/g;
+var NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]?$/;
+var CONSECUTIVE_HYPHENS = /--/;
+async function parseSkill(filePath) {
+  const absolutePath = isAbsolute(filePath) ? filePath : resolve(filePath);
+  const dirPath = dirname(absolutePath);
+  let rawContent;
+  try {
+    rawContent = await readFile(absolutePath, "utf-8");
+  } catch (err) {
+    return {
+      ok: false,
+      skill: null,
+      diagnostics: [
+        {
+          ruleId: "file-readable",
+          severity: "error",
+          message: `Cannot read file: ${err instanceof Error ? err.message : String(err)}`,
+          file: absolutePath
+        }
+      ]
+    };
+  }
+  if (rawContent.trim().length === 0) {
+    return {
+      ok: false,
+      skill: null,
+      diagnostics: [
+        {
+          ruleId: "file-not-empty",
+          severity: "error",
+          message: "SKILL.md file is empty",
+          file: absolutePath
+        }
+      ]
+    };
+  }
+  return parseSkillContent(rawContent, absolutePath, dirPath);
+}
+function parseSkillContent(rawContent, filePath, dirPath) {
+  const diagnostics = [];
+  let hasErrors = false;
+  let parsed;
+  try {
+    parsed = matter(rawContent);
+  } catch (err) {
+    return {
+      ok: false,
+      skill: null,
+      diagnostics: [
+        {
+          ruleId: "frontmatter-valid-yaml",
+          severity: "error",
+          message: `Invalid YAML frontmatter: ${err instanceof Error ? err.message : String(err)}`,
+          file: filePath,
+          line: 1
+        }
+      ]
+    };
+  }
+  const hasFrontmatter = rawContent.trimStart().startsWith("---") && Object.keys(parsed.data).length > 0;
+  if (!hasFrontmatter) {
+    diagnostics.push({
+      ruleId: "frontmatter-required",
+      severity: "error",
+      message: "SKILL.md must have YAML frontmatter between --- delimiters",
+      file: filePath,
+      line: 1,
+      fix: "Add frontmatter at the top of the file:\n---\nname: my-skill\ndescription: A short description\n---"
+    });
+    hasErrors = true;
+  }
+  const data = parsed.data;
+  if (data.name != null && typeof data.name !== "string") {
+    diagnostics.push({
+      ruleId: "name-type",
+      severity: "error",
+      message: 'Frontmatter "name" field must be a string',
+      file: filePath,
+      line: 1,
+      fix: "Ensure the name is a string: name: my-skill-name"
+    });
+    hasErrors = true;
+  } else if (data.name == null || typeof data.name === "string" && data.name.trim().length === 0) {
+    diagnostics.push({
+      ruleId: "name-required",
+      severity: "error",
+      message: 'Frontmatter must contain a "name" field (required by spec)',
+      file: filePath,
+      line: 1,
+      fix: "Add a name field: name: my-skill-name"
+    });
+    hasErrors = true;
+  } else if (typeof data.name === "string") {
+    if (!NAME_PATTERN.test(data.name)) {
+      diagnostics.push({
+        ruleId: "name-format",
+        severity: "error",
+        message: `Skill name "${data.name}" is invalid. Must be 1-64 chars, lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen`,
+        file: filePath,
+        line: 1,
+        fix: `Use a name like: ${String(data.name).toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "")}`
+      });
+      hasErrors = true;
+    } else if (CONSECUTIVE_HYPHENS.test(data.name)) {
+      diagnostics.push({
+        ruleId: "name-format",
+        severity: "error",
+        message: `Skill name "${data.name}" contains consecutive hyphens (--), which is not allowed`,
+        file: filePath,
+        line: 1,
+        fix: `Replace consecutive hyphens with single hyphens: ${data.name.replace(/--+/g, "-")}`
+      });
+      hasErrors = true;
+    }
+  }
+  if (data.description != null && typeof data.description !== "string") {
+    diagnostics.push({
+      ruleId: "description-type",
+      severity: "error",
+      message: 'Frontmatter "description" field must be a string',
+      file: filePath,
+      line: 1,
+      fix: 'Ensure the description is a string: description: "A clear description"'
+    });
+    hasErrors = true;
+  } else if (data.description == null || typeof data.description === "string" && data.description.trim().length === 0) {
+    diagnostics.push({
+      ruleId: "description-required",
+      severity: "error",
+      message: 'Frontmatter must contain a "description" field (required by spec)',
+      file: filePath,
+      line: 1,
+      fix: 'Add a description: description: "What this skill does and when to use it"'
+    });
+    hasErrors = true;
+  } else if (typeof data.description === "string") {
+    const descLen = data.description.length;
+    if (descLen < 10) {
+      diagnostics.push({
+        ruleId: "description-length",
+        severity: "warning",
+        message: `Description is too short (${descLen} chars). Should be at least 50 characters for effective agent routing`,
+        file: filePath,
+        line: 1,
+        fix: "Expand the description to explain what the skill does, when to use it, and what triggers it"
+      });
+    } else if (descLen > 1024) {
+      diagnostics.push({
+        ruleId: "description-length",
+        severity: "error",
+        message: `Description exceeds max length (${descLen} chars). Must be at most 1,024 characters per spec`,
+        file: filePath,
+        line: 1,
+        fix: "Shorten the description to the essential information. Move details to the instructions body"
+      });
+      hasErrors = true;
+    }
+  }
+  const body = parsed.content.trim();
+  if (body.length === 0) {
+    diagnostics.push({
+      ruleId: "body-required",
+      severity: "error",
+      message: "SKILL.md must have markdown content after the frontmatter",
+      file: filePath,
+      fix: "Add instructions below the frontmatter that teach an agent how to use this skill"
+    });
+    hasErrors = true;
+  }
+  const sections = parseSections(parsed.content);
+  const fileReferences = extractFileReferences(parsed.content, filePath, dirPath);
+  for (const ref of fileReferences) {
+    if (!ref.exists) {
+      diagnostics.push({
+        ruleId: "file-reference-exists",
+        severity: "error",
+        message: `Referenced file not found: ${ref.path}`,
+        file: filePath,
+        line: ref.line,
+        fix: `Create the file at ${ref.path} or remove the reference`
+      });
+      hasErrors = true;
+    }
+  }
+  const tokenCount = countTokens(rawContent);
+  if (tokenCount > 5e3) {
+    diagnostics.push({
+      ruleId: "token-budget",
+      severity: "warning",
+      message: `Token count (${tokenCount}) exceeds the recommended 5,000 token budget`,
+      file: filePath,
+      fix: "Move detailed content to references/ directory to keep the main SKILL.md lean"
+    });
+  }
+  const knownFields = ["name", "description", "version"];
+  const dangerousKeys = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+  const metadata = {
+    ...typeof data.name === "string" ? { name: data.name } : {},
+    ...typeof data.description === "string" ? { description: data.description } : {},
+    ...data.version != null ? { version: String(data.version) } : {},
+    ...Object.fromEntries(
+      Object.entries(data).filter(([k]) => !knownFields.includes(k) && !dangerousKeys.has(k))
+    )
+  };
+  if (hasErrors) {
+    return {
+      ok: false,
+      skill: null,
+      diagnostics
+    };
+  }
+  const lineCount = body.split("\n").length;
+  const skill = {
+    metadata,
+    body,
+    sections,
+    fileReferences,
+    filePath,
+    dirPath,
+    tokenCount,
+    lineCount,
+    rawContent
+  };
+  return { ok: true, skill, diagnostics };
+}
+function parseSections(content, _filePath) {
+  const lines = content.split("\n");
+  const sections = [];
+  let currentSection = null;
+  const frontmatterOffset = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+    if (headingMatch) {
+      if (currentSection) {
+        sections.push({
+          heading: currentSection.heading,
+          depth: currentSection.depth,
+          content: currentSection.lines.join("\n").trim(),
+          line: currentSection.line
+        });
+      }
+      currentSection = {
+        heading: headingMatch[2],
+        depth: headingMatch[1].length,
+        line: frontmatterOffset + i + 1,
+        lines: []
+      };
+    } else if (currentSection) {
+      currentSection.lines.push(line);
+    }
+  }
+  if (currentSection) {
+    sections.push({
+      heading: currentSection.heading,
+      depth: currentSection.depth,
+      content: currentSection.lines.join("\n").trim(),
+      line: currentSection.line
+    });
+  }
+  return sections;
+}
+function extractFileReferences(content, _filePath, dirPath) {
+  const references = [];
+  const seen = /* @__PURE__ */ new Set();
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const m of line.matchAll(FILE_REFERENCE_PATTERN)) {
+      const refPath = m[1];
+      if (seen.has(refPath)) continue;
+      seen.add(refPath);
+      const absoluteRefPath = resolve(dirPath, refPath);
+      if (!absoluteRefPath.startsWith(`${resolve(dirPath)}/`)) continue;
+      references.push({
+        path: refPath,
+        line: i + 1,
+        exists: existsSync(absoluteRefPath)
+      });
+    }
+    for (const m of line.matchAll(MARKDOWN_LINK_PATTERN)) {
+      const refPath = m[2];
+      if (refPath.startsWith("#") || refPath.startsWith("data:") || seen.has(refPath)) continue;
+      seen.add(refPath);
+      const absoluteRefPath = resolve(dirPath, refPath);
+      if (!absoluteRefPath.startsWith(`${resolve(dirPath)}/`)) continue;
+      references.push({
+        path: refPath,
+        line: i + 1,
+        exists: existsSync(absoluteRefPath)
+      });
+    }
+  }
+  return references;
+}
+async function resolveSkillFiles(searchPath) {
+  const absolutePath = resolve(searchPath);
+  const locations = [];
+  const pathStat = await stat(absolutePath).catch(() => null);
+  if (!pathStat) {
+    return locations;
+  }
+  if (pathStat.isFile() && basename(absolutePath) === "SKILL.md") {
+    const directory = resolve(absolutePath, "..");
+    locations.push({
+      skillFile: absolutePath,
+      directory,
+      dirName: basename(directory)
+    });
+    return locations;
+  }
+  if (!pathStat.isDirectory()) {
+    return locations;
+  }
+  const directSkill = join(absolutePath, "SKILL.md");
+  const directStat = await stat(directSkill).catch(() => null);
+  if (directStat?.isFile()) {
+    locations.push({
+      skillFile: directSkill,
+      directory: absolutePath,
+      dirName: basename(absolutePath)
+    });
+    return locations;
+  }
+  const entries = await readdir(absolutePath, { withFileTypes: true });
+  const subdirChecks = entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map(async (entry) => {
+    const subdir = join(absolutePath, entry.name);
+    const skillFile = join(subdir, "SKILL.md");
+    const skillStat = await stat(skillFile).catch(() => null);
+    if (skillStat?.isFile()) {
+      locations.push({
+        skillFile,
+        directory: subdir,
+        dirName: entry.name
+      });
+    }
+  });
+  await Promise.all(subdirChecks);
+  locations.sort((a, b) => a.dirName.localeCompare(b.dirName));
+  return locations;
+}
+
+export { countTokens, parseSkill, parseSkillContent, resolveSkillFiles };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tokenizer.ts","../src/parser.ts","../src/resolver.ts"],"names":["resolve"],"mappings":"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","file":"index.js","sourcesContent":["import { encodingForModel } from 'js-tiktoken';\n\n/**\n * Cached encoder instance. Created lazily on first use.\n * Uses cl100k_base encoding (GPT-4 / Claude-compatible).\n */\nlet encoder: ReturnType<typeof encodingForModel> | null = null;\n\n/**\n * Returns the shared tiktoken encoder instance.\n * Uses cl100k_base which is compatible with both OpenAI and Anthropic models.\n */\nfunction getEncoder(): ReturnType<typeof encodingForModel> {\n\tif (!encoder) {\n\t\tencoder = encodingForModel('gpt-4o');\n\t}\n\treturn encoder;\n}\n\n/**\n * Count the number of tokens in a string.\n *\n * Uses the cl100k_base tokenizer (GPT-4o compatible), which provides\n * a reasonable approximation for both OpenAI and Anthropic models.\n * Actual token counts may vary slightly between providers.\n *\n * @param text - The text to count tokens for\n * @returns The number of tokens\n *\n * @example\n * ```ts\n * const count = countTokens('Hello, world!');\n * // => 4\n * ```\n */\nexport function countTokens(text: string): number {\n\tif (text.length === 0) {\n\t\treturn 0;\n\t}\n\tconst enc = getEncoder();\n\treturn enc.encode(text).length;\n}\n","import { existsSync } from 'node:fs';\nimport { readFile } from 'node:fs/promises';\nimport { dirname, isAbsolute, resolve } from 'node:path';\nimport matter from 'gray-matter';\nimport { countTokens } from './tokenizer.js';\nimport type {\n\tDiagnostic,\n\tParseResult,\n\tSkill,\n\tSkillFileReference,\n\tSkillMetadata,\n\tSkillSection,\n} from './types.js';\n\n/**\n * Pattern for matching file references in markdown content.\n * Matches paths like `scripts/foo.sh`, `references/bar.md`, `assets/img.png`.\n * Intentionally narrow to avoid false positives on URLs or code snippets.\n */\nconst FILE_REFERENCE_PATTERN = /(?:^|\\s|`)((?:scripts|references|assets)\\/[\\w./-]+(?:\\.\\w+)?)/gm;\n\n/**\n * Pattern for matching markdown links to local files.\n * Matches [text](path.ext) where path doesn't start with http:// or https://\n */\nconst MARKDOWN_LINK_PATTERN = /\\[([^\\]]*)\\]\\((?!https?:\\/\\/)([^)]+)\\)/g;\n\n/**\n * Pattern for the skill name: lowercase letters, numbers, and hyphens, max 64 chars.\n * Per the Agent Skills spec (agentskills.io):\n * - 1-64 characters\n * - Lowercase alphanumeric and hyphens only\n * - Must not start or end with a hyphen\n * - Must not contain consecutive hyphens (--)\n */\nconst NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]?$/;\nconst CONSECUTIVE_HYPHENS = /--/;\n\n/**\n * Parse a SKILL.md file from a file path.\n *\n * Reads the file, parses frontmatter and markdown body, extracts sections,\n * resolves file references, and counts tokens. Returns either a successful\n * parse result with the Skill object, or a failed result with diagnostics\n * explaining what went wrong.\n *\n * @param filePath - Absolute or relative path to a SKILL.md file\n * @returns ParseResult with either a Skill object or error diagnostics\n *\n * @example\n * ```ts\n * const result = await parseSkill('./my-skill/SKILL.md');\n * if (result.ok) {\n *   console.log(result.skill.metadata.name);\n * } else {\n *   console.error(result.diagnostics);\n * }\n * ```\n */\nexport async function parseSkill(filePath: string): Promise<ParseResult> {\n\tconst absolutePath = isAbsolute(filePath) ? filePath : resolve(filePath);\n\tconst dirPath = dirname(absolutePath);\n\n\t// Read the file\n\tlet rawContent: string;\n\ttry {\n\t\trawContent = await readFile(absolutePath, 'utf-8');\n\t} catch (err) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tskill: null,\n\t\t\tdiagnostics: [\n\t\t\t\t{\n\t\t\t\t\truleId: 'file-readable',\n\t\t\t\t\tseverity: 'error',\n\t\t\t\t\tmessage: `Cannot read file: ${err instanceof Error ? err.message : String(err)}`,\n\t\t\t\t\tfile: absolutePath,\n\t\t\t\t},\n\t\t\t],\n\t\t};\n\t}\n\n\t// Check for empty file\n\tif (rawContent.trim().length === 0) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tskill: null,\n\t\t\tdiagnostics: [\n\t\t\t\t{\n\t\t\t\t\truleId: 'file-not-empty',\n\t\t\t\t\tseverity: 'error',\n\t\t\t\t\tmessage: 'SKILL.md file is empty',\n\t\t\t\t\tfile: absolutePath,\n\t\t\t\t},\n\t\t\t],\n\t\t};\n\t}\n\n\treturn parseSkillContent(rawContent, absolutePath, dirPath);\n}\n\n/**\n * Parse SKILL.md content from a raw string.\n * Useful when you already have the content in memory.\n *\n * @param rawContent - The raw SKILL.md file content\n * @param filePath - The file path (used for diagnostics and file reference resolution)\n * @param dirPath - The skill directory path (used for file reference resolution)\n * @returns ParseResult with either a Skill object or error diagnostics\n */\nexport function parseSkillContent(\n\trawContent: string,\n\tfilePath: string,\n\tdirPath: string,\n): ParseResult {\n\tconst diagnostics: Diagnostic[] = [];\n\tlet hasErrors = false;\n\n\t// Parse frontmatter\n\tlet parsed: matter.GrayMatterFile<string>;\n\ttry {\n\t\tparsed = matter(rawContent);\n\t} catch (err) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tskill: null,\n\t\t\tdiagnostics: [\n\t\t\t\t{\n\t\t\t\t\truleId: 'frontmatter-valid-yaml',\n\t\t\t\t\tseverity: 'error',\n\t\t\t\t\tmessage: `Invalid YAML frontmatter: ${err instanceof Error ? err.message : String(err)}`,\n\t\t\t\t\tfile: filePath,\n\t\t\t\t\tline: 1,\n\t\t\t\t},\n\t\t\t],\n\t\t};\n\t}\n\n\t// Check frontmatter existence — use raw content check since gray-matter's\n\t// .matter property can be unreliable across successive calls\n\tconst hasFrontmatter =\n\t\trawContent.trimStart().startsWith('---') &&\n\t\tObject.keys(parsed.data as Record<string, unknown>).length > 0;\n\tif (!hasFrontmatter) {\n\t\tdiagnostics.push({\n\t\t\truleId: 'frontmatter-required',\n\t\t\tseverity: 'error',\n\t\t\tmessage: 'SKILL.md must have YAML frontmatter between --- delimiters',\n\t\t\tfile: filePath,\n\t\t\tline: 1,\n\t\t\tfix: 'Add frontmatter at the top of the file:\\n---\\nname: my-skill\\ndescription: A short description\\n---',\n\t\t});\n\t\thasErrors = true;\n\t}\n\n\t// Validate metadata fields\n\tconst data = parsed.data as Record<string, unknown>;\n\n\t// Validate name (REQUIRED per agentskills.io spec)\n\tif (data.name != null && typeof data.name !== 'string') {\n\t\tdiagnostics.push({\n\t\t\truleId: 'name-type',\n\t\t\tseverity: 'error',\n\t\t\tmessage: 'Frontmatter \"name\" field must be a string',\n\t\t\tfile: filePath,\n\t\t\tline: 1,\n\t\t\tfix: 'Ensure the name is a string: name: my-skill-name',\n\t\t});\n\t\thasErrors = true;\n\t} else if (\n\t\tdata.name == null ||\n\t\t(typeof data.name === 'string' && data.name.trim().length === 0)\n\t) {\n\t\tdiagnostics.push({\n\t\t\truleId: 'name-required',\n\t\t\tseverity: 'error',\n\t\t\tmessage: 'Frontmatter must contain a \"name\" field (required by spec)',\n\t\t\tfile: filePath,\n\t\t\tline: 1,\n\t\t\tfix: 'Add a name field: name: my-skill-name',\n\t\t});\n\t\thasErrors = true;\n\t} else if (typeof data.name === 'string') {\n\t\tif (!NAME_PATTERN.test(data.name)) {\n\t\t\tdiagnostics.push({\n\t\t\t\truleId: 'name-format',\n\t\t\t\tseverity: 'error',\n\t\t\t\tmessage: `Skill name \"${data.name}\" is invalid. Must be 1-64 chars, lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen`,\n\t\t\t\tfile: filePath,\n\t\t\t\tline: 1,\n\t\t\t\tfix: `Use a name like: ${String(data.name)\n\t\t\t\t\t.toLowerCase()\n\t\t\t\t\t.replace(/[^a-z0-9-]/g, '-')\n\t\t\t\t\t.replace(/-+/g, '-')\n\t\t\t\t\t.replace(/^-|-$/g, '')}`,\n\t\t\t});\n\t\t\thasErrors = true;\n\t\t} else if (CONSECUTIVE_HYPHENS.test(data.name)) {\n\t\t\tdiagnostics.push({\n\t\t\t\truleId: 'name-format',\n\t\t\t\tseverity: 'error',\n\t\t\t\tmessage: `Skill name \"${data.name}\" contains consecutive hyphens (--), which is not allowed`,\n\t\t\t\tfile: filePath,\n\t\t\t\tline: 1,\n\t\t\t\tfix: `Replace consecutive hyphens with single hyphens: ${data.name.replace(/--+/g, '-')}`,\n\t\t\t});\n\t\t\thasErrors = true;\n\t\t}\n\t}\n\n\t// Validate description (REQUIRED per agentskills.io spec)\n\tif (data.description != null && typeof data.description !== 'string') {\n\t\tdiagnostics.push({\n\t\t\truleId: 'description-type',\n\t\t\tseverity: 'error',\n\t\t\tmessage: 'Frontmatter \"description\" field must be a string',\n\t\t\tfile: filePath,\n\t\t\tline: 1,\n\t\t\tfix: 'Ensure the description is a string: description: \"A clear description\"',\n\t\t});\n\t\thasErrors = true;\n\t} else if (\n\t\tdata.description == null ||\n\t\t(typeof data.description === 'string' && data.description.trim().length === 0)\n\t) {\n\t\tdiagnostics.push({\n\t\t\truleId: 'description-required',\n\t\t\tseverity: 'error',\n\t\t\tmessage: 'Frontmatter must contain a \"description\" field (required by spec)',\n\t\t\tfile: filePath,\n\t\t\tline: 1,\n\t\t\tfix: 'Add a description: description: \"What this skill does and when to use it\"',\n\t\t});\n\t\thasErrors = true;\n\t} else if (typeof data.description === 'string') {\n\t\tconst descLen = data.description.length;\n\t\tif (descLen < 10) {\n\t\t\tdiagnostics.push({\n\t\t\t\truleId: 'description-length',\n\t\t\t\tseverity: 'warning',\n\t\t\t\tmessage: `Description is too short (${descLen} chars). Should be at least 50 characters for effective agent routing`,\n\t\t\t\tfile: filePath,\n\t\t\t\tline: 1,\n\t\t\t\tfix: 'Expand the description to explain what the skill does, when to use it, and what triggers it',\n\t\t\t});\n\t\t} else if (descLen > 1024) {\n\t\t\tdiagnostics.push({\n\t\t\t\truleId: 'description-length',\n\t\t\t\tseverity: 'error',\n\t\t\t\tmessage: `Description exceeds max length (${descLen} chars). Must be at most 1,024 characters per spec`,\n\t\t\t\tfile: filePath,\n\t\t\t\tline: 1,\n\t\t\t\tfix: 'Shorten the description to the essential information. Move details to the instructions body',\n\t\t\t});\n\t\t\thasErrors = true;\n\t\t}\n\t}\n\n\t// Check markdown body\n\tconst body = parsed.content.trim();\n\tif (body.length === 0) {\n\t\tdiagnostics.push({\n\t\t\truleId: 'body-required',\n\t\t\tseverity: 'error',\n\t\t\tmessage: 'SKILL.md must have markdown content after the frontmatter',\n\t\t\tfile: filePath,\n\t\t\tfix: 'Add instructions below the frontmatter that teach an agent how to use this skill',\n\t\t});\n\t\thasErrors = true;\n\t}\n\n\t// Parse sections\n\tconst sections = parseSections(parsed.content, filePath);\n\n\t// Extract file references\n\tconst fileReferences = extractFileReferences(parsed.content, filePath, dirPath);\n\n\t// Check for missing referenced files\n\tfor (const ref of fileReferences) {\n\t\tif (!ref.exists) {\n\t\t\tdiagnostics.push({\n\t\t\t\truleId: 'file-reference-exists',\n\t\t\t\tseverity: 'error',\n\t\t\t\tmessage: `Referenced file not found: ${ref.path}`,\n\t\t\t\tfile: filePath,\n\t\t\t\tline: ref.line,\n\t\t\t\tfix: `Create the file at ${ref.path} or remove the reference`,\n\t\t\t});\n\t\t\thasErrors = true;\n\t\t}\n\t}\n\n\t// Count tokens\n\tconst tokenCount = countTokens(rawContent);\n\tif (tokenCount > 5000) {\n\t\tdiagnostics.push({\n\t\t\truleId: 'token-budget',\n\t\t\tseverity: 'warning',\n\t\t\tmessage: `Token count (${tokenCount}) exceeds the recommended 5,000 token budget`,\n\t\t\tfile: filePath,\n\t\t\tfix: 'Move detailed content to references/ directory to keep the main SKILL.md lean',\n\t\t});\n\t}\n\n\t// Build metadata from all frontmatter fields\n\tconst knownFields = ['name', 'description', 'version'];\n\tconst dangerousKeys = new Set(['__proto__', 'constructor', 'prototype']);\n\tconst metadata: SkillMetadata = {\n\t\t...(typeof data.name === 'string' ? { name: data.name } : {}),\n\t\t...(typeof data.description === 'string' ? { description: data.description } : {}),\n\t\t...(data.version != null ? { version: String(data.version) } : {}),\n\t\t...Object.fromEntries(\n\t\t\tObject.entries(data).filter(([k]) => !knownFields.includes(k) && !dangerousKeys.has(k)),\n\t\t),\n\t};\n\n\tif (hasErrors) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tskill: null,\n\t\t\tdiagnostics,\n\t\t};\n\t}\n\n\tconst lineCount = body.split('\\n').length;\n\n\tconst skill: Skill = {\n\t\tmetadata,\n\t\tbody,\n\t\tsections,\n\t\tfileReferences,\n\t\tfilePath,\n\t\tdirPath,\n\t\ttokenCount,\n\t\tlineCount,\n\t\trawContent,\n\t};\n\n\treturn { ok: true, skill, diagnostics };\n}\n\n/**\n * Parse the markdown body into sections based on headings.\n */\nfunction parseSections(content: string, _filePath: string): SkillSection[] {\n\tconst lines = content.split('\\n');\n\tconst sections: SkillSection[] = [];\n\tlet currentSection: { heading: string; depth: number; line: number; lines: string[] } | null =\n\t\tnull;\n\n\t// Calculate the frontmatter offset (lines before content)\n\t// gray-matter strips the frontmatter, so we need to count from line 1 of the content\n\tconst frontmatterOffset = 0; // Sections are relative to the content start\n\n\tfor (let i = 0; i < lines.length; i++) {\n\t\tconst line = lines[i]!;\n\t\tconst headingMatch = line.match(/^(#{1,6})\\s+(.+)$/);\n\n\t\tif (headingMatch) {\n\t\t\t// Save previous section\n\t\t\tif (currentSection) {\n\t\t\t\tsections.push({\n\t\t\t\t\theading: currentSection.heading,\n\t\t\t\t\tdepth: currentSection.depth,\n\t\t\t\t\tcontent: currentSection.lines.join('\\n').trim(),\n\t\t\t\t\tline: currentSection.line,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tcurrentSection = {\n\t\t\t\theading: headingMatch[2]!,\n\t\t\t\tdepth: headingMatch[1]!.length,\n\t\t\t\tline: frontmatterOffset + i + 1,\n\t\t\t\tlines: [],\n\t\t\t};\n\t\t} else if (currentSection) {\n\t\t\tcurrentSection.lines.push(line);\n\t\t}\n\t}\n\n\t// Don't forget the last section\n\tif (currentSection) {\n\t\tsections.push({\n\t\t\theading: currentSection.heading,\n\t\t\tdepth: currentSection.depth,\n\t\t\tcontent: currentSection.lines.join('\\n').trim(),\n\t\t\tline: currentSection.line,\n\t\t});\n\t}\n\n\treturn sections;\n}\n\n/**\n * Extract file references from the markdown body.\n * Looks for paths starting with scripts/, references/, or assets/.\n */\nfunction extractFileReferences(\n\tcontent: string,\n\t_filePath: string,\n\tdirPath: string,\n): SkillFileReference[] {\n\tconst references: SkillFileReference[] = [];\n\tconst seen = new Set<string>();\n\tconst lines = content.split('\\n');\n\n\tfor (let i = 0; i < lines.length; i++) {\n\t\tconst line = lines[i]!;\n\t\t// Match directory-prefixed paths: scripts/, references/, assets/\n\t\tfor (const m of line.matchAll(FILE_REFERENCE_PATTERN)) {\n\t\t\tconst refPath = m[1]!;\n\t\t\tif (seen.has(refPath)) continue;\n\t\t\tseen.add(refPath);\n\n\t\t\tconst absoluteRefPath = resolve(dirPath, refPath);\n\t\t\t// Guard against path traversal — reference must stay within skill directory\n\t\t\tif (!absoluteRefPath.startsWith(`${resolve(dirPath)}/`)) continue;\n\t\t\treferences.push({\n\t\t\t\tpath: refPath,\n\t\t\t\tline: i + 1,\n\t\t\t\texists: existsSync(absoluteRefPath),\n\t\t\t});\n\t\t}\n\n\t\t// Match markdown links to local files: [text](local-file.md)\n\t\tfor (const m of line.matchAll(MARKDOWN_LINK_PATTERN)) {\n\t\t\tconst refPath = m[2]!;\n\t\t\t// Skip anchors, data URIs, and already-seen paths\n\t\t\tif (refPath.startsWith('#') || refPath.startsWith('data:') || seen.has(refPath)) continue;\n\t\t\tseen.add(refPath);\n\n\t\t\tconst absoluteRefPath = resolve(dirPath, refPath);\n\t\t\t// Guard against path traversal — reference must stay within skill directory\n\t\t\tif (!absoluteRefPath.startsWith(`${resolve(dirPath)}/`)) continue;\n\t\t\treferences.push({\n\t\t\t\tpath: refPath,\n\t\t\t\tline: i + 1,\n\t\t\t\texists: existsSync(absoluteRefPath),\n\t\t\t});\n\t\t}\n\t}\n\n\treturn references;\n}\n","import { readdir, stat } from 'node:fs/promises';\nimport { basename, join, resolve } from 'node:path';\n\n/**\n * Information about a discovered skill in the filesystem.\n */\nexport interface SkillLocation {\n\t/** Absolute path to the SKILL.md file */\n\treadonly skillFile: string;\n\t/** Absolute path to the skill directory */\n\treadonly directory: string;\n\t/** The directory name (used as a fallback identifier) */\n\treadonly dirName: string;\n}\n\n/**\n * Resolve all SKILL.md files in a directory tree.\n *\n * Searches for SKILL.md files in the given path. If the path itself\n * contains a SKILL.md, returns just that one. If the path is a directory,\n * searches one level deep for subdirectories containing SKILL.md files.\n *\n * @param searchPath - Absolute or relative path to search\n * @returns Array of discovered skill locations\n *\n * @example\n * ```ts\n * // Single skill directory\n * const skills = await resolveSkillFiles('./my-skill/');\n * // => [{ skillFile: '/abs/path/my-skill/SKILL.md', ... }]\n *\n * // Directory of skills\n * const skills = await resolveSkillFiles('./skills/');\n * // => [\n * //   { skillFile: '/abs/path/skills/deploy/SKILL.md', ... },\n * //   { skillFile: '/abs/path/skills/test-runner/SKILL.md', ... },\n * // ]\n * ```\n */\nexport async function resolveSkillFiles(searchPath: string): Promise<SkillLocation[]> {\n\tconst absolutePath = resolve(searchPath);\n\tconst locations: SkillLocation[] = [];\n\n\t// Check if the path itself is a SKILL.md file\n\tconst pathStat = await stat(absolutePath).catch(() => null);\n\tif (!pathStat) {\n\t\treturn locations;\n\t}\n\n\tif (pathStat.isFile() && basename(absolutePath) === 'SKILL.md') {\n\t\tconst directory = resolve(absolutePath, '..');\n\t\tlocations.push({\n\t\t\tskillFile: absolutePath,\n\t\t\tdirectory,\n\t\t\tdirName: basename(directory),\n\t\t});\n\t\treturn locations;\n\t}\n\n\tif (!pathStat.isDirectory()) {\n\t\treturn locations;\n\t}\n\n\t// Check if this directory contains a SKILL.md\n\tconst directSkill = join(absolutePath, 'SKILL.md');\n\tconst directStat = await stat(directSkill).catch(() => null);\n\tif (directStat?.isFile()) {\n\t\tlocations.push({\n\t\t\tskillFile: directSkill,\n\t\t\tdirectory: absolutePath,\n\t\t\tdirName: basename(absolutePath),\n\t\t});\n\t\treturn locations;\n\t}\n\n\t// Search one level deep for subdirectories with SKILL.md\n\tconst entries = await readdir(absolutePath, { withFileTypes: true });\n\tconst subdirChecks = entries\n\t\t.filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))\n\t\t.map(async (entry) => {\n\t\t\tconst subdir = join(absolutePath, entry.name);\n\t\t\tconst skillFile = join(subdir, 'SKILL.md');\n\t\t\tconst skillStat = await stat(skillFile).catch(() => null);\n\t\t\tif (skillStat?.isFile()) {\n\t\t\t\tlocations.push({\n\t\t\t\t\tskillFile,\n\t\t\t\t\tdirectory: subdir,\n\t\t\t\t\tdirName: entry.name,\n\t\t\t\t});\n\t\t\t}\n\t\t});\n\n\tawait Promise.all(subdirChecks);\n\n\t// Sort by directory name for consistent ordering\n\tlocations.sort((a, b) => a.dirName.localeCompare(b.dirName));\n\n\treturn locations;\n}\n"]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@skill-tools/core",
+  "version": "0.1.0",
+  "description": "Core parser, types, and utilities for Agent Skills (SKILL.md)",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "agent-skills",
+    "skill-md",
+    "parser",
+    "validation",
+    "ai-agent"
+  ],
+  "author": "Piyush Vyas <pyyush>",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/skill-tools/skill-tools"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "js-tiktoken": "^1.0.18"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "@types/node": "^25.2.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "format": "biome format --write src/",
+    "format:check": "biome format src/",
+    "clean": "rm -rf dist"
+  }
+}