load-skills 0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# load-skills
+
+`load-skills` loads skill content from configurable locations and validates skill spec constraints.
+
+## Install
+
+```bash
+bun add load-skills
+```
+
+## Usage
+
+```ts
+import { loadSkills } from "load-skills";
+
+const { skills, report } = await loadSkills({
+  paths: ["./.agents/skills"],
+  recursive: false,
+});
+```
+
+`config` is optional. Calling `loadSkills()` uses:
+
+- `paths: ["./.agents/skills"]`
+- `recursive: false`
+
+`skills` includes loaded skill payloads:
+
+- `meta`: parsed frontmatter object
+- `content`: `SKILL.md` content without frontmatter
+- `references`: absolute file paths from `references/`
+- `scripts`: script descriptors from `scripts/` as `{ path, type }`
+- `state`: `"valid"` or `"invalid"`
+- `warnings`: warning objects with machine-readable `code`
+
+`report` includes one entry per configured path:
+
+- `paths`: one entry per configured path:
+  - `inputPath`: raw path from config
+  - `resolvedPath`: absolute resolved path
+  - `count`: number of included skills from that path
+  - `skillNames`: included skill names from that path
+  - `error` (optional): `path_not_found` or `path_not_directory`
+- `ignoredDuplicates`: map of skipped duplicate skills (first-find-wins), keyed by kept skill name
+
+## Path Priority
+
+`paths` is also a priority list. If the same `meta.name` appears in multiple paths, the first one found is included and later ones are ignored.
+
+## Warning codes
+
+- `missing_frontmatter`: `SKILL.md` is missing a valid `--- ... ---` frontmatter block.
+- `invalid_yaml_frontmatter`: Frontmatter exists but YAML parsing failed or did not produce an object.
+- `missing_required_meta_name`: Frontmatter is missing required `name`.
+- `missing_required_meta_description`: Frontmatter is missing required `description`.
+- `invalid_meta_name`: `name` is present but not a non-empty string.
+- `invalid_meta_description`: `description` is present but not a non-empty string.
+- `skill_md_content_size_limit_exceeded`: `SKILL.md` body exceeds 500 lines.
+- `reference_large_without_toc`: A `references/` file exceeds 300 lines without a table-of-contents marker.
+- `resource_read_error`: A resource file or directory could not be read during scanning.

package/dist/discovery.d.ts

@@ -0,0 +1,12 @@
+import type { LoadSkillsConfig, LoadSkillsPathReport } from "./types.js";
+export interface DiscoveredSkillFile {
+    skillFilePath: string;
+    pathReportIndex: number;
+    inputPath: string;
+}
+export interface DiscoveryResult {
+    discoveredSkillFiles: DiscoveredSkillFile[];
+    report: LoadSkillsPathReport[];
+}
+export declare function discoverSkillFiles(config: LoadSkillsConfig): Promise<DiscoveryResult>;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGzE,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,oBAAoB,EAAE,mBAAmB,EAAE,CAAC;IAC5C,MAAM,EAAE,oBAAoB,EAAE,CAAC;CAChC;AAED,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,eAAe,CAAC,CA6D1B"}

package/dist/discovery.js

@@ -0,0 +1,103 @@
+import { constants } from "node:fs";
+import { access, readdir, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { pathExists } from "./utils.js";
+export async function discoverSkillFiles(config) {
+    const cwd = config.cwd ?? process.cwd();
+    const recursive = config.recursive ?? false;
+    const inputPaths = config.paths ?? ["./.agents/skills"];
+    const pathPairs = inputPaths.map((inputPath) => ({
+        inputPath,
+        resolvedPath: path.resolve(cwd, inputPath),
+    }));
+    const report = [];
+    const discoveredSkillFiles = [];
+    const discovered = new Set();
+    for (const pair of pathPairs) {
+        const rootPath = pair.resolvedPath;
+        const inputPath = pair.inputPath;
+        const reportItem = {
+            inputPath,
+            resolvedPath: rootPath,
+            count: 0,
+            skillNames: [],
+        };
+        const rootExists = await pathExists(rootPath);
+        if (!rootExists) {
+            reportItem.error = "path_not_found";
+            report.push(reportItem);
+            continue;
+        }
+        const rootStat = await stat(rootPath);
+        if (!rootStat.isDirectory()) {
+            reportItem.error = "path_not_directory";
+            report.push(reportItem);
+            continue;
+        }
+        const found = recursive
+            ? await discoverRecursive(rootPath)
+            : await discoverNonRecursive(rootPath);
+        const pathReportIndex = report.length;
+        for (const skillFilePath of found) {
+            const canonical = await realpath(skillFilePath);
+            if (!discovered.has(canonical)) {
+                discovered.add(canonical);
+                discoveredSkillFiles.push({
+                    skillFilePath: canonical,
+                    pathReportIndex,
+                    inputPath,
+                });
+            }
+        }
+        report.push(reportItem);
+    }
+    return {
+        discoveredSkillFiles,
+        report,
+    };
+}
+async function discoverNonRecursive(rootPath) {
+    const entries = await readdir(rootPath, { withFileTypes: true });
+    const paths = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const candidate = path.join(rootPath, entry.name, "SKILL.md");
+        if (await isReadableFile(candidate)) {
+            paths.push(candidate);
+        }
+    }
+    return paths;
+}
+async function discoverRecursive(rootPath) {
+    const paths = [];
+    async function walk(currentPath) {
+        const entries = await readdir(currentPath, { withFileTypes: true });
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            const fullPath = path.join(currentPath, entry.name);
+            if (entry.isFile() && entry.name === "SKILL.md") {
+                paths.push(fullPath);
+                continue;
+            }
+            if (entry.isDirectory()) {
+                await walk(fullPath);
+            }
+        }
+    }
+    await walk(rootPath);
+    return paths;
+}
+async function isReadableFile(targetPath) {
+    try {
+        const targetStat = await stat(targetPath);
+        if (!targetStat.isFile()) {
+            return false;
+        }
+        await access(targetPath, constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { loadSkills } from "./loadSkills.js";
+export type { LoadedSkill, LoadSkillsConfig, IgnoredDuplicateSkill, LoadSkillsPathError, LoadSkillsPathReport, LoadSkillsReport, LoadSkillsResult, SkillScript, SkillScriptType, SkillState, SkillWarning, SkillWarningCode, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EACV,WAAW,EACX,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,UAAU,EACV,YAAY,EACZ,gBAAgB,GACjB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { loadSkills } from "./loadSkills.js";

package/dist/loadSkills.d.ts

@@ -0,0 +1,3 @@
+import type { LoadSkillsConfig, LoadSkillsResult } from "./types.js";
+export declare function loadSkills(config?: LoadSkillsConfig): Promise<LoadSkillsResult>;
+//# sourceMappingURL=loadSkills.d.ts.map

package/dist/loadSkills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadSkills.d.ts","sourceRoot":"","sources":["../src/loadSkills.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAGV,gBAAgB,EAChB,gBAAgB,EAIjB,MAAM,YAAY,CAAC;AAOpB,wBAAsB,UAAU,CAC9B,MAAM,CAAC,EAAE,gBAAgB,GACxB,OAAO,CAAC,gBAAgB,CAAC,CAoG3B"}

package/dist/loadSkills.js

@@ -0,0 +1,217 @@
+import { constants } from "node:fs";
+import { open, readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { discoverSkillFiles } from "./discovery.js";
+import { parseSkillDocument } from "./parseSkill.js";
+import { getErrorMessage, pathExists } from "./utils.js";
+import { applyValidationRules, validateLargeReferences, } from "./validateSkill.js";
+export async function loadSkills(config) {
+    const resolvedConfig = config ?? {};
+    const discovery = await discoverSkillFiles(resolvedConfig);
+    const results = [];
+    const reportPaths = discovery.report.map((entry) => ({ ...entry }));
+    const ignoredDuplicates = {};
+    const includedByName = new Map();
+    for (const discovered of discovery.discoveredSkillFiles) {
+        const skillFilePath = discovered.skillFilePath;
+        const skillPath = path.dirname(skillFilePath);
+        const skillWarnings = [];
+        const rawSkillText = await readFile(skillFilePath, "utf8");
+        const parsed = parseSkillDocument(rawSkillText);
+        skillWarnings.push(...parsed.warnings);
+        const resourceScan = await collectResources(skillPath);
+        skillWarnings.push(...resourceScan.warnings);
+        const largeReferenceWarnings = validateLargeReferences(resourceScan.referenceContents);
+        skillWarnings.push(...largeReferenceWarnings);
+        const skill = applyValidationRules({
+            meta: parsed.meta,
+            content: parsed.content,
+            references: resourceScan.references,
+            scripts: resourceScan.scripts,
+            state: "valid",
+            warnings: skillWarnings,
+            skillPath,
+            skillFilePath,
+        });
+        const reportItem = reportPaths[discovered.pathReportIndex];
+        if (!reportItem) {
+            continue;
+        }
+        const resolvedName = typeof skill.meta.name === "string" && skill.meta.name.trim() !== ""
+            ? skill.meta.name.trim()
+            : path.basename(skill.skillPath);
+        if (typeof skill.meta.name === "string" && skill.meta.name.trim() !== "") {
+            const normalizedName = skill.meta.name.trim().toLowerCase();
+            const existing = includedByName.get(normalizedName);
+            if (existing) {
+                const ignoredEntry = {
+                    skillName: resolvedName,
+                    normalizedSkillName: normalizedName,
+                    ignoredSkillPath: skill.skillPath,
+                    ignoredSkillFilePath: skill.skillFilePath,
+                    ignoredFromInputPath: discovered.inputPath,
+                    keptSkillPath: existing.skillPath,
+                    keptSkillFilePath: existing.skillFilePath,
+                    keptFromInputPath: existing.inputPath,
+                };
+                const key = existing.skillName;
+                ignoredDuplicates[key] = [
+                    ...(ignoredDuplicates[key] ?? []),
+                    ignoredEntry,
+                ];
+                continue;
+            }
+            includedByName.set(normalizedName, {
+                skillName: resolvedName,
+                skillPath: skill.skillPath,
+                skillFilePath: skill.skillFilePath,
+                inputPath: discovered.inputPath,
+            });
+        }
+        results.push(skill);
+        reportItem.skillNames.push(resolvedName);
+        reportItem.count += 1;
+    }
+    for (const reportItem of reportPaths) {
+        reportItem.skillNames.sort((a, b) => a.localeCompare(b));
+    }
+    return {
+        skills: results,
+        report: {
+            paths: reportPaths,
+            ignoredDuplicates,
+        },
+    };
+}
+async function collectResources(skillPath) {
+    const referencesRoot = path.join(skillPath, "references");
+    const scriptsRoot = path.join(skillPath, "scripts");
+    const warnings = [];
+    const referenceFiles = await listFilesRecursively(referencesRoot, warnings);
+    const scriptFiles = await listFilesRecursively(scriptsRoot, warnings);
+    const referenceContents = [];
+    for (const filePath of referenceFiles) {
+        try {
+            const content = await readFile(filePath, "utf8");
+            referenceContents.push({
+                path: filePath,
+                content,
+                lineCount: content.length === 0 ? 0 : content.split(/\r?\n/).length,
+            });
+        }
+        catch (error) {
+            warnings.push({
+                code: "resource_read_error",
+                message: `Unable to read reference file ${filePath}: ${getErrorMessage(error)}`,
+            });
+        }
+    }
+    const scripts = [];
+    for (const filePath of scriptFiles) {
+        scripts.push({
+            path: filePath,
+            type: await inferScriptType(filePath),
+        });
+    }
+    return {
+        references: referenceFiles.sort((a, b) => a.localeCompare(b)),
+        referenceContents,
+        scripts: scripts.sort((a, b) => a.path.localeCompare(b.path)),
+        warnings,
+    };
+}
+async function listFilesRecursively(maybeRoot, warnings) {
+    const exists = await pathExists(maybeRoot);
+    if (!exists) {
+        return [];
+    }
+    const rootStats = await stat(maybeRoot);
+    if (!rootStats.isDirectory()) {
+        warnings.push({
+            code: "resource_read_error",
+            message: `Expected directory but found non-directory resource root: ${maybeRoot}`,
+        });
+        return [];
+    }
+    const files = [];
+    async function walk(current) {
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch (error) {
+            warnings.push({
+                code: "resource_read_error",
+                message: `Unable to read resource directory ${current}: ${getErrorMessage(error)}`,
+            });
+            return;
+        }
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            const fullPath = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                await walk(fullPath);
+            }
+            else if (entry.isFile()) {
+                files.push(fullPath);
+            }
+        }
+    }
+    await walk(maybeRoot);
+    return files;
+}
+async function inferScriptType(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === ".js" || ext === ".mjs" || ext === ".cjs") {
+        return "javascript";
+    }
+    if (ext === ".ts" || ext === ".mts" || ext === ".cts") {
+        return "typescript";
+    }
+    if (ext === ".py") {
+        return "python";
+    }
+    if (ext === ".sh" || ext === ".bash" || ext === ".zsh") {
+        return "shell";
+    }
+    if (ext === ".rb") {
+        return "ruby";
+    }
+    try {
+        const firstLine = await readFirstLine(filePath);
+        if (firstLine.startsWith("#!")) {
+            if (firstLine.includes("python")) {
+                return "python";
+            }
+            if (firstLine.includes("bash") ||
+                firstLine.includes("sh") ||
+                firstLine.includes("zsh")) {
+                return "shell";
+            }
+            if (firstLine.includes("ruby")) {
+                return "ruby";
+            }
+            if (firstLine.includes("node") ||
+                firstLine.includes("deno") ||
+                firstLine.includes("bun")) {
+                return "javascript";
+            }
+        }
+    }
+    catch {
+        // If we cannot inspect shebang, keep fallback type.
+    }
+    return "other";
+}
+async function readFirstLine(filePath) {
+    const handle = await open(filePath, constants.O_RDONLY);
+    try {
+        const maxBytes = 1024;
+        const buffer = Buffer.alloc(maxBytes);
+        const { bytesRead } = await handle.read(buffer, 0, maxBytes, 0);
+        const snippet = buffer.subarray(0, bytesRead).toString("utf8");
+        return snippet.split(/\r?\n/, 1)[0]?.toLowerCase() ?? "";
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/parseSkill.d.ts

@@ -0,0 +1,3 @@
+import type { ParseSkillResult } from "./types.js";
+export declare function parseSkillDocument(rawText: string): ParseSkillResult;
+//# sourceMappingURL=parseSkill.d.ts.map

package/dist/parseSkill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseSkill.d.ts","sourceRoot":"","sources":["../src/parseSkill.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAgB,MAAM,YAAY,CAAC;AAGjE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAwFpE"}

package/dist/parseSkill.js

@@ -0,0 +1,77 @@
+import { parse as parseYaml } from "yaml";
+import { getErrorMessage } from "./utils.js";
+export function parseSkillDocument(rawText) {
+    const warnings = [];
+    const text = rawText.replace(/^\uFEFF/, "");
+    if (!text.startsWith("---\n") && !text.startsWith("---\r\n")) {
+        warnings.push({
+            code: "missing_frontmatter",
+            message: "SKILL.md is missing YAML frontmatter delimiters.",
+        });
+        return {
+            meta: {},
+            content: text,
+            warnings,
+        };
+    }
+    const lines = text.split(/\r?\n/);
+    let closingIndex = -1;
+    for (let i = 1; i < lines.length; i += 1) {
+        if (lines[i] === "---") {
+            closingIndex = i;
+            break;
+        }
+    }
+    if (closingIndex === -1) {
+        warnings.push({
+            code: "missing_frontmatter",
+            message: "Frontmatter opening delimiter exists but closing delimiter is missing.",
+        });
+        return {
+            meta: {},
+            content: text,
+            warnings,
+        };
+    }
+    const frontmatterRaw = lines.slice(1, closingIndex).join("\n");
+    const body = lines.slice(closingIndex + 1).join("\n");
+    if (frontmatterRaw.trim() === "") {
+        return {
+            meta: {},
+            content: body,
+            warnings,
+        };
+    }
+    try {
+        const parsed = parseYaml(frontmatterRaw);
+        if (parsed === null ||
+            typeof parsed !== "object" ||
+            Array.isArray(parsed)) {
+            warnings.push({
+                code: "invalid_yaml_frontmatter",
+                message: "Frontmatter must parse to a YAML object.",
+            });
+            return {
+                meta: {},
+                content: body,
+                warnings,
+            };
+        }
+        return {
+            meta: parsed,
+            content: body,
+            warnings,
+        };
+    }
+    catch (error) {
+        warnings.push({
+            code: "invalid_yaml_frontmatter",
+            message: `Unable to parse YAML frontmatter: ${getErrorMessage(error)}`,
+        });
+        return {
+            meta: {},
+            content: body,
+            warnings,
+        };
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+export type SkillState = "valid" | "invalid";
+export type SkillScriptType = "javascript" | "typescript" | "python" | "shell" | "ruby" | "other";
+export type SkillWarningCode = "missing_frontmatter" | "invalid_yaml_frontmatter" | "missing_required_meta_name" | "missing_required_meta_description" | "invalid_meta_name" | "invalid_meta_description" | "skill_md_content_size_limit_exceeded" | "reference_large_without_toc" | "resource_read_error";
+export interface SkillWarning {
+    code: SkillWarningCode;
+    message: string;
+}
+export interface SkillScript {
+    path: string;
+    type: SkillScriptType;
+}
+export interface LoadedSkill {
+    meta: Record<string, unknown>;
+    content: string;
+    references: string[];
+    scripts: SkillScript[];
+    state: SkillState;
+    warnings: SkillWarning[];
+    skillPath: string;
+    skillFilePath: string;
+}
+export interface LoadSkillsConfig {
+    paths?: string[];
+    recursive?: boolean;
+    cwd?: string;
+}
+export type LoadSkillsPathError = "path_not_found" | "path_not_directory";
+export interface LoadSkillsPathReport {
+    inputPath: string;
+    resolvedPath: string;
+    count: number;
+    skillNames: string[];
+    error?: LoadSkillsPathError;
+}
+export interface IgnoredDuplicateSkill {
+    skillName: string;
+    normalizedSkillName: string;
+    ignoredSkillPath: string;
+    ignoredSkillFilePath: string;
+    ignoredFromInputPath: string;
+    keptSkillPath: string;
+    keptSkillFilePath: string;
+    keptFromInputPath: string;
+}
+export interface LoadSkillsReport {
+    paths: LoadSkillsPathReport[];
+    ignoredDuplicates: Record<string, IgnoredDuplicateSkill[]>;
+}
+export interface LoadSkillsResult {
+    skills: LoadedSkill[];
+    report: LoadSkillsReport;
+}
+export interface ParseSkillResult {
+    meta: Record<string, unknown>;
+    content: string;
+    warnings: SkillWarning[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;AAE7C,MAAM,MAAM,eAAe,GACvB,YAAY,GACZ,YAAY,GACZ,QAAQ,GACR,OAAO,GACP,MAAM,GACN,OAAO,CAAC;AAEZ,MAAM,MAAM,gBAAgB,GACxB,qBAAqB,GACrB,0BAA0B,GAC1B,4BAA4B,GAC5B,mCAAmC,GACnC,mBAAmB,GACnB,0BAA0B,GAC1B,sCAAsC,GACtC,6BAA6B,GAC7B,qBAAqB,CAAC;AAE1B,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,eAAe,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,KAAK,EAAE,UAAU,CAAC;IAClB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,GAAG,oBAAoB,CAAC;AAE1E,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,mBAAmB,CAAC;CAC7B;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,EAAE,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,3 @@
+export declare function pathExists(targetPath: string): Promise<boolean>;
+export declare function getErrorMessage(error: unknown): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAGA,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOrE;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMtD"}

package/dist/utils.js

@@ -0,0 +1,17 @@
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+export async function pathExists(targetPath) {
+    try {
+        await access(targetPath, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}

package/dist/validateSkill.d.ts

@@ -0,0 +1,8 @@
+import type { LoadedSkill, SkillWarning } from "./types.js";
+export declare function applyValidationRules(skill: LoadedSkill): LoadedSkill;
+export declare function validateLargeReferences(references: Array<{
+    path: string;
+    content: string;
+    lineCount: number;
+}>): SkillWarning[];
+//# sourceMappingURL=validateSkill.d.ts.map

package/dist/validateSkill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateSkill.d.ts","sourceRoot":"","sources":["../src/validateSkill.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAc5D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CA8CpE;AAED,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,GACtE,YAAY,EAAE,CAqBhB"}

package/dist/validateSkill.js

@@ -0,0 +1,83 @@
+const INVALID_WARNING_CODES = new Set([
+    "missing_frontmatter",
+    "invalid_yaml_frontmatter",
+    "missing_required_meta_name",
+    "missing_required_meta_description",
+    "invalid_meta_name",
+    "invalid_meta_description",
+    "skill_md_content_size_limit_exceeded",
+    "reference_large_without_toc",
+    "resource_read_error",
+]);
+export function applyValidationRules(skill) {
+    const warnings = [...skill.warnings];
+    const metaName = skill.meta.name;
+    const metaDescription = skill.meta.description;
+    if (typeof metaName !== "string" || metaName.trim() === "") {
+        warnings.push({
+            code: typeof metaName === "undefined"
+                ? "missing_required_meta_name"
+                : "invalid_meta_name",
+            message: "Frontmatter field `name` is required and must be a non-empty string.",
+        });
+    }
+    if (typeof metaDescription !== "string" || metaDescription.trim() === "") {
+        warnings.push({
+            code: typeof metaDescription === "undefined"
+                ? "missing_required_meta_description"
+                : "invalid_meta_description",
+            message: "Frontmatter field `description` is required and must be a non-empty string.",
+        });
+    }
+    const contentLineCount = getLineCount(skill.content);
+    if (contentLineCount > 500) {
+        warnings.push({
+            code: "skill_md_content_size_limit_exceeded",
+            message: `SKILL.md body exceeds the recommended 500-line limit (${contentLineCount} lines).`,
+        });
+    }
+    const state = warnings.some((warning) => INVALID_WARNING_CODES.has(warning.code))
+        ? "invalid"
+        : "valid";
+    return {
+        ...skill,
+        warnings: dedupeWarnings(warnings),
+        state,
+    };
+}
+export function validateLargeReferences(references) {
+    const warnings = [];
+    for (const reference of references) {
+        if (reference.lineCount <= 300) {
+            continue;
+        }
+        const normalized = reference.content.toLowerCase();
+        const hasTocMarker = normalized.includes("table of contents") || normalized.includes("[toc]");
+        if (!hasTocMarker) {
+            warnings.push({
+                code: "reference_large_without_toc",
+                message: `Large reference file is missing a table of contents hint: ${reference.path}`,
+            });
+        }
+    }
+    return warnings;
+}
+function dedupeWarnings(warnings) {
+    const keys = new Set();
+    const deduped = [];
+    for (const warning of warnings) {
+        const key = `${warning.code}:${warning.message}`;
+        if (keys.has(key)) {
+            continue;
+        }
+        keys.add(key);
+        deduped.push(warning);
+    }
+    return deduped;
+}
+function getLineCount(content) {
+    if (content.length === 0) {
+        return 0;
+    }
+    return content.split(/\r?\n/).length;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "load-skills",
+  "version": "0.1.0",
+  "description": "Load and validate agent skills from configurable paths.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "fmt": "prettier -w .",
+    "fmt:check": "prettier -c .",
+    "prepare": "husky",
+    "precommit:check": "bun run typecheck && bun run test && bun run fmt:check",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "skills",
+    "agent",
+    "loader",
+    "frontmatter"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "husky": "^9.1.7",
+    "prettier": "^3.6.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}