load-skills 0.1.0 → 0.2.0

package/README.md

@@ -26,12 +26,11 @@ const { skills, report } = await loadSkills({
 
 `skills` includes loaded skill payloads:
 
-- `meta`: parsed frontmatter object
+- shape: `Record<string, Skill>` (keyed by skill name)
+- `meta`: typed frontmatter object with required `name` and `description`
 - `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:
 
@@ -42,6 +41,7 @@ const { skills, report } = await loadSkills({
   - `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
+- `invalidSkills`: invalid skill entries moved out of `skills`; each item includes `warnings`
 
 ## Path Priority
 
@@ -49,6 +49,8 @@ const { skills, report } = await loadSkills({
 
 ## Warning codes
 
+These warnings appear on `report.invalidSkills[*].warnings`.
+
 - `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`.

package/dist/index.d.ts

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

package/dist/index.d.ts.map

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

package/dist/loadSkills.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"loadSkills.d.ts","sourceRoot":"","sources":["../src/loadSkills.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAGV,gBAAgB,EAChB,gBAAgB,EAKjB,MAAM,YAAY,CAAC;AAOpB,wBAAsB,UAAU,CAC9B,MAAM,CAAC,EAAE,gBAAgB,GACxB,OAAO,CAAC,gBAAgB,CAAC,CAgH3B"}

package/dist/loadSkills.js

@@ -8,7 +8,8 @@ import { applyValidationRules, validateLargeReferences, } from "./validateSkill.
 export async function loadSkills(config) {
     const resolvedConfig = config ?? {};
     const discovery = await discoverSkillFiles(resolvedConfig);
-    const results = [];
+    const skills = {};
+    const invalidSkills = [];
     const reportPaths = discovery.report.map((entry) => ({ ...entry }));
     const ignoredDuplicates = {};
     const includedByName = new Map();
@@ -23,63 +24,74 @@ export async function loadSkills(config) {
         skillWarnings.push(...resourceScan.warnings);
         const largeReferenceWarnings = validateLargeReferences(resourceScan.referenceContents);
         skillWarnings.push(...largeReferenceWarnings);
-        const skill = applyValidationRules({
+        const validated = 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,
+        if (!validated.isValid || !validated.meta) {
+            invalidSkills.push({
+                meta: parsed.meta,
+                content: parsed.content,
+                references: resourceScan.references,
+                scripts: resourceScan.scripts,
+                warnings: validated.warnings,
+                skillPath,
+                skillFilePath,
             });
+            continue;
+        }
+        const skill = {
+            meta: validated.meta,
+            content: parsed.content,
+            references: resourceScan.references,
+            scripts: resourceScan.scripts,
+            skillPath,
+            skillFilePath,
+        };
+        const normalizedName = skill.meta.name.trim().toLowerCase();
+        const existing = includedByName.get(normalizedName);
+        if (existing) {
+            const ignoredEntry = {
+                skillName: skill.meta.name,
+                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;
         }
-        results.push(skill);
-        reportItem.skillNames.push(resolvedName);
+        includedByName.set(normalizedName, {
+            skillName: skill.meta.name,
+            skillPath: skill.skillPath,
+            skillFilePath: skill.skillFilePath,
+            inputPath: discovered.inputPath,
+        });
+        skills[skill.meta.name] = skill;
+        reportItem.skillNames.push(skill.meta.name);
         reportItem.count += 1;
     }
     for (const reportItem of reportPaths) {
         reportItem.skillNames.sort((a, b) => a.localeCompare(b));
     }
     return {
-        skills: results,
+        skills,
         report: {
             paths: reportPaths,
             ignoredDuplicates,
+            invalidSkills,
         },
     };
 }

package/dist/types.d.ts

@@ -1,4 +1,3 @@
-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 {
@@ -9,12 +8,23 @@ export interface SkillScript {
     path: string;
     type: SkillScriptType;
 }
-export interface LoadedSkill {
+export type SkillMeta = Record<string, unknown> & {
+    name: string;
+    description: string;
+};
+export interface Skill {
+    meta: SkillMeta;
+    content: string;
+    references: string[];
+    scripts: SkillScript[];
+    skillPath: string;
+    skillFilePath: string;
+}
+export interface InvalidSkill {
     meta: Record<string, unknown>;
     content: string;
     references: string[];
     scripts: SkillScript[];
-    state: SkillState;
     warnings: SkillWarning[];
     skillPath: string;
     skillFilePath: string;
@@ -45,9 +55,10 @@ export interface IgnoredDuplicateSkill {
 export interface LoadSkillsReport {
     paths: LoadSkillsPathReport[];
     ignoredDuplicates: Record<string, IgnoredDuplicateSkill[]>;
+    invalidSkills: InvalidSkill[];
 }
 export interface LoadSkillsResult {
-    skills: LoadedSkill[];
+    skills: Record<string, Skill>;
     report: LoadSkillsReport;
 }
 export interface ParseSkillResult {

package/dist/types.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,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,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,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,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;IAC3D,aAAa,EAAE,YAAY,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC9B,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/validateSkill.d.ts

@@ -1,5 +1,13 @@
-import type { LoadedSkill, SkillWarning } from "./types.js";
-export declare function applyValidationRules(skill: LoadedSkill): LoadedSkill;
+import type { SkillMeta, SkillWarning } from "./types.js";
+export declare function applyValidationRules(input: {
+    meta: Record<string, unknown>;
+    content: string;
+    warnings: SkillWarning[];
+}): {
+    warnings: SkillWarning[];
+    isValid: boolean;
+    meta?: SkillMeta;
+};
 export declare function validateLargeReferences(references: Array<{
     path: string;
     content: string;

package/dist/validateSkill.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"validateSkill.d.ts","sourceRoot":"","sources":["../src/validateSkill.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAc1D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B,GAAG;IACF,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB,CAoDA;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

@@ -9,10 +9,10 @@ const INVALID_WARNING_CODES = new Set([
     "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;
+export function applyValidationRules(input) {
+    const warnings = [...input.warnings];
+    const metaName = input.meta.name;
+    const metaDescription = input.meta.description;
     if (typeof metaName !== "string" || metaName.trim() === "") {
         warnings.push({
             code: typeof metaName === "undefined"
@@ -29,20 +29,25 @@ export function applyValidationRules(skill) {
             message: "Frontmatter field `description` is required and must be a non-empty string.",
         });
     }
-    const contentLineCount = getLineCount(skill.content);
+    const contentLineCount = getLineCount(input.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";
+    const dedupedWarnings = dedupeWarnings(warnings);
+    const isValid = !dedupedWarnings.some((warning) => INVALID_WARNING_CODES.has(warning.code));
+    if (isValid) {
+        return {
+            warnings: dedupedWarnings,
+            isValid: true,
+            meta: input.meta,
+        };
+    }
     return {
-        ...skill,
-        warnings: dedupeWarnings(warnings),
-        state,
+        warnings: dedupedWarnings,
+        isValid: false,
     };
 }
 export function validateLargeReferences(references) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "load-skills",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Load and validate agent skills from configurable paths.",
   "type": "module",
   "main": "./dist/index.js",