@nexrall/code-core 1.4.47 → 1.4.48

package/dist/agent/agentTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agentTypes.d.ts","sourceRoot":"","sources":["../../src/agent/agentTypes.ts"],"names":[],"mappings":"AAkCA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IACpD;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAmX5D;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAuND;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CAE3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,CAqB5G;AAED,yFAAyF;AACzF,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AAED,2FAA2F;AAC3F,wBAAgB,aAAa,IAAI,SAAS,EAAE,CAE3C;AACD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,CAY1D;AASD,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAIjG"}
+{"version":3,"file":"agentTypes.d.ts","sourceRoot":"","sources":["../../src/agent/agentTypes.ts"],"names":[],"mappings":"AAmCA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IACpD;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAmX5D;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAiND;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CAE3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,CAqB5G;AAED,yFAAyF;AACzF,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AAED,2FAA2F;AAC3F,wBAAgB,aAAa,IAAI,SAAS,EAAE,CAE3C;AACD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,CAY1D;AASD,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAIjG"}

package/dist/agent/agentTypes.js

@@ -43,6 +43,7 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const index_1 = require("../plugins/index");
+const frontmatter_1 = require("../util/frontmatter");
 const VALID_MEMORY_SCOPES = ['project', 'user', 'local'];
 function parseMemoryScope(v) {
     const s = (v ?? '').trim().toLowerCase();
@@ -395,18 +396,10 @@ const VALID_MODELS = [
     // Legacy tier aliases — still accepted, still resolved by the backend.
     'turbo', 'pro', 'ultra', 'fast',
 ];
-function parseFrontmatter(raw) {
-    const m = /^\s*---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(raw);
-    if (!m)
-        return { meta: {}, body: raw.trim(), ok: false };
-    const meta = {};
-    for (const line of m[1].split(/\r?\n/)) {
-        const kv = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(line.trim());
-        if (kv)
-            meta[kv[1].toLowerCase()] = kv[2].trim().replace(/^["']|["']$/g, '');
-    }
-    return { meta, body: (m[2] ?? '').trim(), ok: true };
-}
+// parseFrontmatter now lives in ../util/frontmatter (shared with skills.ts and
+// commands/loader.ts) so this file no longer carries its own copy — it used
+// to, and the two silently drifted (the shared copy gained multi-line/nested
+// value support during an audit; this one never did until this migration).
 /**
  * Parse the `model:` frontmatter of an agent definition.
  *
@@ -475,7 +468,7 @@ function loadDir(dir, source, into, warnings) {
             warnings.push({ file: full, agent: path.basename(entry.name, '.md'), message: `could not be read (${err.message}) — this agent was skipped` });
             continue;
         }
-        const { meta, body, ok } = parseFrontmatter(raw);
+        const { meta, body, ok } = (0, frontmatter_1.parseFrontmatter)(raw);
         const name = (meta.name || path.basename(entry.name, '.md')).trim();
         if (!name)
             continue;

package/dist/agent/skills.d.ts

@@ -1,3 +1,10 @@
+export interface SkillWarning {
+    /** Absolute path of the SKILL.md / command file the problem was found in. */
+    file: string;
+    /** Skill name, when one could be determined. */
+    name: string;
+    message: string;
+}
 export interface Skill {
     name: string;
     description: string;
@@ -11,10 +18,33 @@ export interface Skill {
     disableModelInvocation: boolean;
     /** false → only the model may invoke it (auto-load only, not meant to be typed as a command). */
     userInvocable: boolean;
+    /** agentskills.io spec field — license name or reference to a bundled license file. Informational only. */
+    license?: string;
+    /** agentskills.io spec field — environment requirements (e.g. "Requires git, docker"). Informational only. */
+    compatibility?: string;
+    /** agentskills.io spec field — arbitrary author-supplied key/value metadata (from a nested `metadata:` block). */
+    metadata?: Record<string, string>;
+    /** agentskills.io spec field (experimental) — space-separated tool names the skill declares it needs. Not yet enforced as an allowlist; informational. */
+    allowedTools?: string[];
 }
-/** Discover all skills (project overrides global overrides plugin overrides builtin).
- *  Directory-style `.nexrall/skills/<name>/SKILL.md` beats a flat `.nexrall/commands/<name>.md`
- *  of the same name within the same precedence tier. */
+/**
+ * Discover all skills, with diagnostics.
+ *
+ * Precedence, most to least authoritative: project `.nexrall/skills` >
+ * project `.nexrall/commands` > project `.agents/skills` (cross-client) >
+ * global `.nexrall/commands` > global `.nexrall/skills` > global
+ * `.agents/skills` (cross-client) > plugin > builtin.
+ *
+ * The `.agents/skills` scans are always the weakest source within their tier
+ * — see the module comment above for why. Directory-style
+ * `.nexrall/skills/<name>/SKILL.md` beats a flat `.nexrall/commands/<name>.md`
+ * of the same name within the same precedence tier.
+ */
+export declare function loadSkillsWithWarnings(workDir: string): {
+    skills: Skill[];
+    warnings: SkillWarning[];
+};
+/** Discover all skills (project overrides global overrides plugin overrides builtin). See loadSkillsWithWarnings for the full precedence rule and diagnostics. */
 export declare function loadSkills(workDir: string): Skill[];
 export declare function findSkill(skills: Skill[], name: string): Skill | undefined;
 /** Skills the MODEL may auto-invoke via the use_skill tool (excludes disable-model-invocation:true ones). */
@@ -28,7 +58,7 @@ export declare function summariseSkills(skills: Skill[]): string;
  * substitution as slash commands — see commands/loader.ts#expandBody), then
  * prepend a short header pointing at the skill's own directory (if any) so
  * the model knows where to find supporting files it may need to read_file
- * on demand, mirroring Claude Code's "reference files from your SKILL.md"
+ * on demand, mirroring the spec's "reference files from your SKILL.md"
  * guidance without loading them into context up front.
  */
 export declare function expandSkill(skill: Skill, argString: string, workDir: string): string;

package/dist/agent/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/agent/skills.ts"],"names":[],"mappings":"AA4CA,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IACpD,0IAA0I;IAC1I,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kHAAkH;IAClH,sBAAsB,EAAE,OAAO,CAAC;IAChC,iGAAiG;IACjG,aAAa,EAAE,OAAO,CAAC;CACxB;AA8HD;;wDAEwD;AACxD,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,CAanD;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAG1E;AAED,6GAA6G;AAC7G,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAE5D;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAE5D;AAED,oHAAoH;AACpH,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAIvD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAcpF"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/agent/skills.ts"],"names":[],"mappings":"AAyEA,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IACpD,0IAA0I;IAC1I,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kHAAkH;IAClH,sBAAsB,EAAE,OAAO,CAAC;IAChC,iGAAiG;IACjG,aAAa,EAAE,OAAO,CAAC;IACvB,2GAA2G;IAC3G,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8GAA8G;IAC9G,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kHAAkH;IAClH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,0JAA0J;IAC1J,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AA8LD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,CAsBrG;AAED,kKAAkK;AAClK,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,CAEnD;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAG1E;AAED,6GAA6G;AAC7G,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAE5D;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAE5D;AAED,oHAAoH;AACpH,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAIvD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAcpF"}

package/dist/agent/skills.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadSkillsWithWarnings = loadSkillsWithWarnings;
 exports.loadSkills = loadSkills;
 exports.findSkill = findSkill;
 exports.autoInvokableSkills = autoInvokableSkills;
@@ -45,6 +46,18 @@ const os = __importStar(require("os"));
 const index_1 = require("../plugins/index");
 const loader_1 = require("../commands/loader");
 const frontmatter_1 = require("../util/frontmatter");
+/** Frontmatter keys this parser understands, for typo/unrecognised-key detection (see SkillWarning). */
+const KNOWN_META_KEYS = new Set([
+    'name', 'description', 'model', 'mode',
+    'disable-model-invocation', 'user-invocable',
+    'license', 'compatibility', 'metadata', 'allowed-tools',
+]);
+// agentskills.io's `name` constraint: 1-64 chars, lowercase alphanumeric and
+// hyphens, no leading/trailing/consecutive hyphens. Validated LENIENTLY here
+// (warn, still load) per the spec's own client-implementation guidance —
+// rejecting a skill outright over a cosmetic name issue would be a worse
+// failure mode than a slightly-off name that still works.
+const SPEC_NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 function parseBool(v, fallback) {
     if (v === undefined)
         return fallback;
@@ -55,7 +68,14 @@ function parseBool(v, fallback) {
         return false;
     return fallback;
 }
-function toSkill(meta, body, name, source, dir) {
+/** Space- (or comma-) separated tool list, same leniency as agentTypes.ts's parseToolList. */
+function parseSpaceList(v) {
+    if (!v)
+        return undefined;
+    const items = v.split(/[,\s]+/).map((t) => t.trim()).filter(Boolean);
+    return items.length ? items : undefined;
+}
+function toSkill(meta, body, name, source, dir, nested) {
     const model = ['turbo', 'pro', 'ultra'].find((x) => x === (meta.model ?? '').toLowerCase());
     return {
         name,
@@ -67,13 +87,51 @@ function toSkill(meta, body, name, source, dir) {
         dir,
         disableModelInvocation: parseBool(meta['disable-model-invocation'], false),
         userInvocable: parseBool(meta['user-invocable'], true),
+        license: meta.license || undefined,
+        compatibility: meta.compatibility || undefined,
+        metadata: nested?.metadata,
+        allowedTools: parseSpaceList(meta['allowed-tools']),
     };
 }
+/**
+ * Lenient validation warnings for a skill's frontmatter — never blocks loading, only reported.
+ *
+ * `rawName` is the name BEFORE lowercasing (whatever the frontmatter or the
+ * directory/file actually said) — validated against the spec's naming rule,
+ * which is itself case-sensitive ("lowercase ... only" is a real constraint,
+ * not cosmetic). `effectiveName` is the lowercased name used as the map key
+ * and `Skill.name` — using it here instead would make an uppercase name
+ * always "pass" validation simply because it had already been normalised
+ * away by the time this function saw it.
+ */
+function validateSkillMeta(meta, rawName, effectiveName, dirName, file, warnings) {
+    if (!warnings)
+        return;
+    if (!SPEC_NAME_RE.test(rawName)) {
+        warnings.push({
+            file, name: effectiveName,
+            message: `name "${rawName}" does not match the agentskills.io convention (lowercase letters, numbers, and single hyphens only) — loaded anyway, but other clients reading this skill may warn or reject it.`,
+        });
+    }
+    else if (rawName.length > 64) {
+        warnings.push({ file, name: effectiveName, message: `name is ${rawName.length} characters — the spec caps this at 64. Loaded anyway.` });
+    }
+    if (dirName !== undefined && meta.name && meta.name.trim().toLowerCase() !== dirName.toLowerCase()) {
+        warnings.push({
+            file, name: effectiveName,
+            message: `frontmatter name "${meta.name}" does not match its directory name "${dirName}" — the spec requires them to match for cross-client compatibility. Loaded anyway, using the frontmatter name.`,
+        });
+    }
+    const strayKeys = Object.keys(meta).filter((k) => !KNOWN_META_KEYS.has(k));
+    if (strayKeys.length) {
+        warnings.push({ file, name: effectiveName, message: `has unrecognised frontmatter key(s): ${strayKeys.join(', ')} — these are ignored.` });
+    }
+}
 // Legacy flat-file skills: .nexrall/commands/<name>.md (and plugin commands/).
 // Kept as its own loader (rather than merged into loadSkillDir below) since the
 // naming/precedence rule ("skill directory wins over a same-name flat command")
 // requires knowing about both shapes before the caller merges them.
-function loadFlatCommandDir(dir, source, into) {
+function loadFlatCommandDir(dir, source, into, warnings) {
     let files;
     try {
         files = fs.readdirSync(dir).filter((f) => f.endsWith('.md'));
@@ -82,23 +140,27 @@ function loadFlatCommandDir(dir, source, into) {
         return;
     }
     for (const file of files) {
+        const full = path.join(dir, file);
         try {
-            const raw = fs.readFileSync(path.join(dir, file), 'utf-8');
+            const raw = fs.readFileSync(full, 'utf-8');
             const { meta, body } = (0, frontmatter_1.parseFrontmatter)(raw);
-            const name = (meta.name || path.basename(file, '.md')).trim().toLowerCase();
+            const rawName = (meta.name || path.basename(file, '.md')).trim();
+            const name = rawName.toLowerCase();
             if (!name)
                 continue;
             if (source !== 'project' && into.has(name))
                 continue; // earlier tiers win
+            validateSkillMeta(meta, rawName, name, undefined, full, warnings);
             into.set(name, toSkill(meta, body, name, source));
         }
-        catch {
-            /* skip malformed */
+        catch (err) {
+            warnings?.push({ file: full, name: path.basename(file, '.md'), message: `could not be read or parsed (${err.message}) — skipped.` });
         }
     }
 }
 // Directory-style skills: .nexrall/skills/<name>/SKILL.md (+ optional supporting files).
-function loadSkillDir(root, source, into) {
+// Also used for the cross-client `.agents/skills/<name>/SKILL.md` convention — same shape.
+function loadSkillDir(root, source, into, warnings) {
     let entries;
     try {
         entries = fs.readdirSync(root, { withFileTypes: true });
@@ -120,8 +182,9 @@ function loadSkillDir(root, source, into) {
         }
         try {
             const raw = fs.readFileSync(skillFile, 'utf-8');
-            const { meta, body } = (0, frontmatter_1.parseFrontmatter)(raw);
-            const name = (meta.name || entry.name).trim().toLowerCase();
+            const { meta, body, nested } = (0, frontmatter_1.parseFrontmatter)(raw);
+            const rawName = (meta.name || entry.name).trim();
+            const name = rawName.toLowerCase();
             if (!name)
                 continue;
             // A directory-style skill always wins over an earlier flat command of
@@ -129,10 +192,11 @@ function loadSkillDir(root, source, into) {
             // project tier always wins outright regardless of load order.
             if (source !== 'project' && into.has(name))
                 continue;
-            into.set(name, toSkill(meta, body, name, source, skillDir));
+            validateSkillMeta(meta, rawName, name, entry.name, skillFile, warnings);
+            into.set(name, toSkill(meta, body, name, source, skillDir, nested));
         }
-        catch {
-            /* skip malformed */
+        catch (err) {
+            warnings?.push({ file: skillFile, name: entry.name, message: `could not be read or parsed (${err.message}) — skipped.` });
         }
     }
 }
@@ -176,25 +240,45 @@ const BUILTIN_SKILLS = [
         ].join('\n'),
     },
 ];
-/** Discover all skills (project overrides global overrides plugin overrides builtin).
- *  Directory-style `.nexrall/skills/<name>/SKILL.md` beats a flat `.nexrall/commands/<name>.md`
- *  of the same name within the same precedence tier. */
-function loadSkills(workDir) {
+/**
+ * Discover all skills, with diagnostics.
+ *
+ * Precedence, most to least authoritative: project `.nexrall/skills` >
+ * project `.nexrall/commands` > project `.agents/skills` (cross-client) >
+ * global `.nexrall/commands` > global `.nexrall/skills` > global
+ * `.agents/skills` (cross-client) > plugin > builtin.
+ *
+ * The `.agents/skills` scans are always the weakest source within their tier
+ * — see the module comment above for why. Directory-style
+ * `.nexrall/skills/<name>/SKILL.md` beats a flat `.nexrall/commands/<name>.md`
+ * of the same name within the same precedence tier.
+ */
+function loadSkillsWithWarnings(workDir) {
     const out = new Map();
-    // Flat commands first (so a same-tier skill directory below can override them).
-    loadFlatCommandDir(path.join(workDir, '.nexrall', 'commands'), 'project', out);
-    loadSkillDir(path.join(workDir, '.nexrall', 'skills'), 'project', out);
-    loadFlatCommandDir(path.join(os.homedir(), '.nexrall', 'commands'), 'global', out);
-    loadSkillDir(path.join(os.homedir(), '.nexrall', 'skills'), 'global', out);
+    const warnings = [];
+    // Project tier is last-write-wins (see loadSkillDir/loadFlatCommandDir's
+    // `source !== 'project'` guard), so the WEAKEST project source loads first.
+    loadSkillDir(path.join(workDir, '.agents', 'skills'), 'project', out, warnings);
+    loadFlatCommandDir(path.join(workDir, '.nexrall', 'commands'), 'project', out, warnings);
+    loadSkillDir(path.join(workDir, '.nexrall', 'skills'), 'project', out, warnings);
+    // Global tier is first-write-wins (the guard skips a repeat name), so the
+    // STRONGEST global source loads first, and .agents/skills loads last.
+    loadFlatCommandDir(path.join(os.homedir(), '.nexrall', 'commands'), 'global', out, warnings);
+    loadSkillDir(path.join(os.homedir(), '.nexrall', 'skills'), 'global', out, warnings);
+    loadSkillDir(path.join(os.homedir(), '.agents', 'skills'), 'global', out, warnings);
     for (const dir of (0, index_1.pluginAssetDirs)(workDir, 'commands'))
-        loadFlatCommandDir(dir, 'plugin', out);
+        loadFlatCommandDir(dir, 'plugin', out, warnings);
     for (const dir of (0, index_1.pluginAssetDirs)(workDir, 'skills'))
-        loadSkillDir(dir, 'plugin', out);
+        loadSkillDir(dir, 'plugin', out, warnings);
     for (const skill of BUILTIN_SKILLS) {
         if (!out.has(skill.name))
             out.set(skill.name, skill);
     }
-    return [...out.values()];
+    return { skills: [...out.values()], warnings };
+}
+/** Discover all skills (project overrides global overrides plugin overrides builtin). See loadSkillsWithWarnings for the full precedence rule and diagnostics. */
+function loadSkills(workDir) {
+    return loadSkillsWithWarnings(workDir).skills;
 }
 function findSkill(skills, name) {
     const want = name.replace(/^\//, '').trim().toLowerCase();
@@ -220,7 +304,7 @@ function summariseSkills(skills) {
  * substitution as slash commands — see commands/loader.ts#expandBody), then
  * prepend a short header pointing at the skill's own directory (if any) so
  * the model knows where to find supporting files it may need to read_file
- * on demand, mirroring Claude Code's "reference files from your SKILL.md"
+ * on demand, mirroring the spec's "reference files from your SKILL.md"
  * guidance without loading them into context up front.
  */
 function expandSkill(skill, argString, workDir) {

package/dist/agent/trust.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trust.d.ts","sourceRoot":"","sources":["../../src/agent/trust.ts"],"names":[],"mappings":"AAiDA;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CA0DxD"}
+{"version":3,"file":"trust.d.ts","sourceRoot":"","sources":["../../src/agent/trust.ts"],"names":[],"mappings":"AAqDA;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAkExD"}

package/dist/agent/trust.js

@@ -54,6 +54,10 @@ const path = __importStar(require("path"));
 //   • `.nexrall/{skills,commands}` define playbooks the agent will follow,
 //     and `.nexrall/permissions.json` can pre-approve tool calls that would
 //     otherwise prompt.
+//   • `.agents/skills/` is the same kind of playbook, discovered from the
+//     agentskills.io cross-client convention (see agent/skills.ts) rather
+//     than a Nexrall-specific path — worth its own line since it may have
+//     been authored for a different client entirely.
 //
 // So `git clone` of a hostile repo followed by pointing an agent at it is
 // enough to execute attacker-chosen commands before a human reviews anything.
@@ -146,6 +150,14 @@ function detectTrustSignals(dir) {
     if (exists('.nexrall', 'agents')) {
         signals.push('.nexrall/agents/ — custom sub-agent definitions');
     }
+    if (exists('.agents', 'skills')) {
+        // Same risk class as .nexrall/skills/ (a playbook is instructions the
+        // agent follows, not code it executes) — called out separately because
+        // this path is the agentskills.io cross-client convention, so a skill
+        // here may have been authored for/by a DIFFERENT tool than the one
+        // asking to trust this folder right now.
+        signals.push('.agents/skills/ — cross-client agent playbooks (agentskills.io convention)');
+    }
     return signals;
 }
 //# sourceMappingURL=trust.js.map

package/dist/util/frontmatter.d.ts

@@ -1,22 +1,79 @@
 /**
  * Shared YAML-ish frontmatter parser for the markdown-based config formats
- * this project uses (slash commands, skills, agent definitions). All three
- * previously carried their own byte-for-byte identical copy of this function
- * — extracted here so a future fix (e.g. multi-line values, list syntax)
- * only has to happen once and cannot silently drift between them.
+ * this project uses (slash commands, skills, agent definitions, plugin
+ * manifests). Extracted here so a fix only has to happen once and cannot
+ * silently drift between the formats that consume it.
  *
  *   ---
  *   key: value
  *   another-key: "quoted value"
+ *   description: >-
+ *     a long value that folds onto
+ *     the following indented lines
+ *   metadata:
+ *     author: example-org
+ *     version: "1.0"
  *   ---
  *   body text...
  *
- * Deliberately minimal: single-line `key: value` pairs only, no nested
- * structures or YAML lists — matches what commands/loader.ts, agent/skills.ts
- * and agent/agentTypes.ts have always accepted.
+ * Deliberately still not a full YAML parser (no lists, no multi-level
+ * nesting, no anchors) — but it now handles the three shapes real-world
+ * SKILL.md files (including the `agentskills.io` spec's own examples) use:
+ *
+ *  1. Plain multi-line values: a `key: value` line followed by indented
+ *     lines with no `sub: value` shape of their own are folded onto the
+ *     value with a single space, the same way a human reads wrapped prose.
+ *  2. Block scalars: `key: >`, `>-`, `|`, `|-` followed by indented lines.
+ *     `>` folds lines into a single space-joined string (YAML "folded"
+ *     style); `|` keeps them literal, newline-joined ("literal" style).
+ *     The `-` chomping indicator is accepted for compatibility but every
+ *     value returned here is trimmed regardless, since these are metadata
+ *     strings, not file content whose trailing newline matters.
+ *  3. One-level nested maps: `key:` with NOTHING after the colon, followed
+ *     by indented `sub: value` lines, becomes a nested map — returned
+ *     separately in `nested[key]`, NEVER merged into the flat `meta` object.
+ *
+ * That last rule is load-bearing, not cosmetic. The previous version of
+ * this parser treated every trimmed line as a flat top-level key regardless
+ * of indentation, so a block like
+ *
+ *   tools: read_file, search_files, glob
+ *   metadata:
+ *     tools: read_file, search_files, glob, bash, write_file, delete_file
+ *
+ * silently let the indented `tools:` inside `metadata:` OVERWRITE the real,
+ * innocent-looking top-level `tools:` a reviewer would actually read —
+ * because both lines matched the same regex and the second write won. That
+ * is a privilege-escalation bug in an agent-definition file, not a display
+ * quirk: `agentTypes.ts`'s tool allowlist reads `meta.tools` and would have
+ * granted `bash`/`write_file`/`delete_file` from a definition that visibly
+ * only requests three read-only tools. Every indented line now belongs to
+ * ITS OWN key's continuation/nested-map, never to the flat top-level
+ * namespace, which makes this class of collision structurally impossible
+ * rather than merely untested.
  */
-export declare function parseFrontmatter(raw: string): {
+export interface ParsedFrontmatter {
+    /** Flat top-level `key: value` pairs. Indented/nested content never leaks in here. */
     meta: Record<string, string>;
+    /** Markdown body after the closing `---`. */
     body: string;
-};
+    /**
+     * One-level nested maps, keyed by their parent field name — e.g. a
+     * `metadata:` block with indented `author: ...` / `version: ...` lines
+     * becomes `nested.metadata = { author: '...', version: '...' }`.
+     * Absent (not an empty object) when no field had a nested map, so
+     * callers that don't care can ignore this without an extra check.
+     */
+    nested?: Record<string, Record<string, string>>;
+    /**
+     * True if a valid `---`-delimited frontmatter block was found at all. False
+     * means the whole file is `body` and `meta`/`nested` are empty — callers
+     * that treat "no parseable frontmatter" as a distinct, fail-closed case
+     * (e.g. agent definitions default to read-only rather than unrestricted
+     * when this is false) should check this instead of `Object.keys(meta).length`,
+     * which can't tell "no frontmatter" apart from "frontmatter with no fields".
+     */
+    ok: boolean;
+}
+export declare function parseFrontmatter(raw: string): ParsedFrontmatter;
 //# sourceMappingURL=frontmatter.d.ts.map

package/dist/util/frontmatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/util/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAS5F"}
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/util/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,MAAM,WAAW,iBAAiB;IAChC,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD;;;;;;;OAOG;IACH,EAAE,EAAE,OAAO,CAAC;CACb;AAcD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAqG/D"}

package/dist/util/frontmatter.js

@@ -1,33 +1,172 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseFrontmatter = parseFrontmatter;
 /**
  * Shared YAML-ish frontmatter parser for the markdown-based config formats
- * this project uses (slash commands, skills, agent definitions). All three
- * previously carried their own byte-for-byte identical copy of this function
- * — extracted here so a future fix (e.g. multi-line values, list syntax)
- * only has to happen once and cannot silently drift between them.
+ * this project uses (slash commands, skills, agent definitions, plugin
+ * manifests). Extracted here so a fix only has to happen once and cannot
+ * silently drift between the formats that consume it.
  *
  *   ---
  *   key: value
  *   another-key: "quoted value"
+ *   description: >-
+ *     a long value that folds onto
+ *     the following indented lines
+ *   metadata:
+ *     author: example-org
+ *     version: "1.0"
  *   ---
  *   body text...
  *
- * Deliberately minimal: single-line `key: value` pairs only, no nested
- * structures or YAML lists — matches what commands/loader.ts, agent/skills.ts
- * and agent/agentTypes.ts have always accepted.
+ * Deliberately still not a full YAML parser (no lists, no multi-level
+ * nesting, no anchors) — but it now handles the three shapes real-world
+ * SKILL.md files (including the `agentskills.io` spec's own examples) use:
+ *
+ *  1. Plain multi-line values: a `key: value` line followed by indented
+ *     lines with no `sub: value` shape of their own are folded onto the
+ *     value with a single space, the same way a human reads wrapped prose.
+ *  2. Block scalars: `key: >`, `>-`, `|`, `|-` followed by indented lines.
+ *     `>` folds lines into a single space-joined string (YAML "folded"
+ *     style); `|` keeps them literal, newline-joined ("literal" style).
+ *     The `-` chomping indicator is accepted for compatibility but every
+ *     value returned here is trimmed regardless, since these are metadata
+ *     strings, not file content whose trailing newline matters.
+ *  3. One-level nested maps: `key:` with NOTHING after the colon, followed
+ *     by indented `sub: value` lines, becomes a nested map — returned
+ *     separately in `nested[key]`, NEVER merged into the flat `meta` object.
+ *
+ * That last rule is load-bearing, not cosmetic. The previous version of
+ * this parser treated every trimmed line as a flat top-level key regardless
+ * of indentation, so a block like
+ *
+ *   tools: read_file, search_files, glob
+ *   metadata:
+ *     tools: read_file, search_files, glob, bash, write_file, delete_file
+ *
+ * silently let the indented `tools:` inside `metadata:` OVERWRITE the real,
+ * innocent-looking top-level `tools:` a reviewer would actually read —
+ * because both lines matched the same regex and the second write won. That
+ * is a privilege-escalation bug in an agent-definition file, not a display
+ * quirk: `agentTypes.ts`'s tool allowlist reads `meta.tools` and would have
+ * granted `bash`/`write_file`/`delete_file` from a definition that visibly
+ * only requests three read-only tools. Every indented line now belongs to
+ * ITS OWN key's continuation/nested-map, never to the flat top-level
+ * namespace, which makes this class of collision structurally impossible
+ * rather than merely untested.
  */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFrontmatter = parseFrontmatter;
+const TOP_LEVEL_KEY = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/;
+const BLOCK_SCALAR = /^[|>][+-]?$/;
+function leadingIndent(line) {
+    const m = /^[ \t]*/.exec(line);
+    return m ? m[0].length : 0;
+}
+function unquote(v) {
+    return v.trim().replace(/^["']|["']$/g, '');
+}
 function parseFrontmatter(raw) {
     const m = /^\s*---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(raw);
     if (!m)
-        return { meta: {}, body: raw.trim() };
+        return { meta: {}, body: raw.trim(), ok: false };
+    const lines = m[1].split(/\r?\n/);
     const meta = {};
-    for (const line of m[1].split(/\r?\n/)) {
-        const kv = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(line.trim());
-        if (kv)
-            meta[kv[1].toLowerCase()] = kv[2].trim().replace(/^["']|["']$/g, '');
+    let nested;
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        // Blank lines and stray indented lines with no top-level key before them
+        // (malformed input) are simply skipped — lenient parsing, same spirit as
+        // the rest of this file: warn elsewhere, don't throw here.
+        if (!line.trim() || leadingIndent(line) > 0) {
+            i++;
+            continue;
+        }
+        const kv = TOP_LEVEL_KEY.exec(line.trim());
+        if (!kv) {
+            i++;
+            continue;
+        }
+        const key = kv[1].toLowerCase();
+        const value = kv[2].trim();
+        // Collect every immediately-following indented line as this key's
+        // continuation block, whatever shape it turns out to be.
+        const continuation = [];
+        let j = i + 1;
+        while (j < lines.length && (leadingIndent(lines[j]) > 0 || !lines[j].trim())) {
+            continuation.push(lines[j]);
+            j++;
+        }
+        // Trim trailing blank continuation lines (keeps indent-detection below
+        // simple and doesn't affect folded/literal output).
+        while (continuation.length && !continuation[continuation.length - 1].trim())
+            continuation.pop();
+        if (BLOCK_SCALAR.test(value)) {
+            // `key: >`, `>-`, `|`, `|-` — content is EVERY continuation line.
+            // `>` = YAML "folded" style (join into one space-separated line);
+            // `|` = YAML "literal" style (keep the line breaks as-is).
+            const folded = value.startsWith('>');
+            const base = continuation.length ? leadingIndent(continuation.find((l) => l.trim()) ?? continuation[0]) : 0;
+            const dedented = continuation.map((l) => (l.trim() ? l.slice(Math.min(base, leadingIndent(l))) : ''));
+            meta[key] = folded
+                ? dedented.join(' ').replace(/\s+/g, ' ').trim() // folded (>) style
+                : dedented.join('\n').trim(); // literal (|) style
+        }
+        else if (value === '') {
+            // `key:` with nothing after it. Two possibilities:
+            //  - continuation lines look like `sub: value` → this is a nested map,
+            //    isolated in `nested[key]` and NEVER merged into flat `meta`.
+            //  - continuation lines are plain prose → fold them as the value.
+            const looksNested = continuation.length > 0 && continuation.every((l) => !l.trim() || TOP_LEVEL_KEY.test(l.trim()));
+            if (looksNested && continuation.some((l) => l.trim())) {
+                const map = {};
+                for (const l of continuation) {
+                    const sub = TOP_LEVEL_KEY.exec(l.trim());
+                    if (sub)
+                        map[sub[1].toLowerCase()] = unquote(sub[2]);
+                }
+                nested = nested ?? {};
+                nested[key] = map;
+                // Deliberately no `meta[key] = ...` here — an empty-header field with
+                // a nested map has no flat scalar value of its own.
+            }
+            else if (continuation.length) {
+                meta[key] = [value, ...continuation.map((l) => l.trim())].filter(Boolean).join(' ').trim();
+            }
+            else {
+                meta[key] = '';
+            }
+        }
+        else {
+            // Normal `key: value`. Fold any plain-prose continuation lines onto it
+            // (the common case: a long `description:` wrapped across lines) —
+            // but only if none of them look like their own `sub: value` pair,
+            // which would instead mean the author meant something structured and
+            // folding it into one string would corrupt it silently.
+            const looksNested = continuation.length > 0 && continuation.every((l) => !l.trim() || TOP_LEVEL_KEY.test(l.trim()));
+            if (continuation.length && !looksNested) {
+                meta[key] = unquote([value, ...continuation.map((l) => l.trim())].join(' '));
+            }
+            else if (continuation.length && looksNested) {
+                // `key: value` immediately followed by what looks like a nested map —
+                // ambiguous/malformed YAML. Keep the scalar value (least surprising:
+                // it's what a naive line-by-line reader sees first) and surface the
+                // rest as a nested map too, rather than silently dropping either.
+                meta[key] = unquote(value);
+                const map = {};
+                for (const l of continuation) {
+                    const sub = TOP_LEVEL_KEY.exec(l.trim());
+                    if (sub)
+                        map[sub[1].toLowerCase()] = unquote(sub[2]);
+                }
+                nested = nested ?? {};
+                nested[key] = map;
+            }
+            else {
+                meta[key] = unquote(value);
+            }
+        }
+        i = j;
     }
-    return { meta, body: (m[2] ?? '').trim() };
+    return { meta, body: (m[2] ?? '').trim(), nested, ok: true };
 }
 //# sourceMappingURL=frontmatter.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexrall/code-core",
-  "version": "1.4.47",
+  "version": "1.4.48",
   "description": "Core agent loop, tools, and extension primitives for Nexrall Code — embed an AI coding agent in any Node.js application.",
   "license": "MIT",
   "author": "Nexrall <support@nexrall.com> (https://nexrall.com)",