@elizaos/skills 2.0.0-alpha.98 → 2.0.3-beta.2

package/README.md

@@ -14,7 +14,7 @@ Skills are markdown files that provide specialized instructions for AI agents to
 ```bash
 npm install @elizaos/skills
 # or
-pnpm add @elizaos/skills
+bun add @elizaos/skills
 ```
 
 ## Usage
@@ -49,7 +49,7 @@ const result = loadSkillsFromDir({
 import { formatSkillsForPrompt } from "@elizaos/skills";
 
 const prompt = formatSkillsForPrompt(skills);
-// Returns XML-formatted skills section for system prompt
+// Returns a compact structured skills section for system prompt
 ```
 
 ### Build Command Specs
@@ -62,14 +62,19 @@ const commands = buildSkillCommandSpecs(entries);
 // Returns array of command specs for chat interfaces
 ```
 
+## Bundled documentation skills
+
+Alongside community-oriented skills, this package ships **`elizaos`**, **`eliza-cloud`**, and **`eliza-app-development`** — concise references for elizaOS runtime concepts, Eliza Cloud as a backend, and building elizaOS-based applications (including the Eliza app repository layout).
+
 ## Skill Discovery
 
 Skills are loaded from multiple locations in precedence order (later overrides earlier):
 
 1. **Bundled skills** - Included in this package (`skills/`)
-2. **Managed skills** - User-installed skills (`~/.elizaos/skills/`)
-3. **Project skills** - Project-local skills (`<cwd>/.elizaos/skills/`)
-4. **Explicit paths** - Via `skillPaths` option
+2. **Managed skills** - User-installed skills (`<stateDir>/skills/`)
+3. **Curated/active** - Human- or agent-promoted skills (`<stateDir>/skills/curated/active/`)
+4. **Project skills** - Project-local skills (`<cwd>/.elizaos/skills/`)
+5. **Explicit paths** - Via `skillPaths` option
 
 ## Skill Format
 
@@ -94,7 +99,7 @@ Detailed instructions for the AI agent...
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `name` | string | Skill name (should match directory name) |
+| `name` | string | Skill name (must match directory name) |
 | `description` | string | Human-readable description (required) |
 | `disable-model-invocation` | boolean | If true, skill won't appear in prompts |
 | `user-invocable` | boolean | If false, can't be invoked via commands |
@@ -102,6 +107,8 @@ Detailed instructions for the AI agent...
 | `required-os` | string[] | Required operating systems |
 | `required-bins` | string[] | Required binaries in PATH |
 | `required-env` | string[] | Required environment variables |
+| `command-dispatch` | string | Set to `tool` to enable tool-dispatch in `buildSkillCommandSpecs` |
+| `command-tool` | string | Tool name used when `command-dispatch: tool` |
 
 ## API Reference
 
@@ -110,17 +117,39 @@ Detailed instructions for the AI agent...
 - `Skill` - Loaded skill with metadata
 - `SkillFrontmatter` - Parsed frontmatter
 - `SkillEntry` - Full skill entry with all metadata
+- `SkillMetadata` - Resolved metadata (env, bins, os)
+- `SkillInvocationPolicy` - Resolved invocation flags
+- `SkillCommandSpec` - Command spec for chat interfaces
+- `SkillProvenance` - Provenance tracking for the learning loop
 - `LoadSkillsResult` - Result from loading skills
 
-### Functions
+### Discovery / Resolution
 
 - `getSkillsDir()` - Get bundled skills path
+- `clearSkillsDirCache()` - Reset bundled-dir resolution cache
+- `getCuratedActiveDir()` - `<stateDir>/skills/curated/active/`
+- `getProposedSkillsDir()` - `<stateDir>/skills/curated/proposed/`
+- `promoteSkill(name)` - Move a proposed skill to active atomically
+
+### Loading
+
 - `loadSkills(options?)` - Load from all locations
 - `loadSkillsFromDir(options)` - Load from single directory
-- `loadSkillEntries(options?)` - Load with full metadata
-- `formatSkillsForPrompt(skills)` - Format for LLM prompt
-- `buildSkillCommandSpecs(entries)` - Build command specs
+- `loadSkillEntries(options?)` - Load with full metadata parsed into `SkillEntry[]`
+
+### Formatting
+
+- `formatSkillsForPrompt(skills)` - Format `Skill[]` for system prompt
+- `formatSkillEntriesForPrompt(entries)` - Same but from `SkillEntry[]` (respects invocation policy)
+- `formatSkillSummary(skill)` - Single `"name: description"` string
+- `formatSkillsList(skills)` - Newline-joined list
+- `buildSkillCommandSpecs(entries, reservedNames?)` - Build command specs
 
-## License
+### Frontmatter
 
-MIT
+- `parseFrontmatter(content)` - Parse YAML frontmatter from markdown string
+- `stripFrontmatter(content)` - Return body without frontmatter
+- `serializeSkillFile(frontmatter, body)` - Re-serialize frontmatter + body (learning loop)
+- `resolveSkillMetadata(frontmatter)` - Resolve `SkillMetadata` from frontmatter
+- `resolveSkillInvocationPolicy(frontmatter)` - Resolve `SkillInvocationPolicy`
+- `resolveSkillProvenance(frontmatter)` - Resolve `SkillProvenance` (returns `undefined` if missing/malformed)

package/dist/formatter.d.ts

@@ -1,8 +1,7 @@
 import type { Skill, SkillCommandSpec, SkillEntry } from "./types.js";
 /**
  * Format skills for inclusion in a system prompt.
- * Uses XML format per Agent Skills standard.
- * See: https://agentskills.io/integrate-skills
+ * Uses compact structured text.
  *
  * Skills with disableModelInvocation=true are excluded from the prompt
  * (they can only be invoked explicitly via /skill:name commands).
@@ -11,12 +10,6 @@ import type { Skill, SkillCommandSpec, SkillEntry } from "./types.js";
  * @returns Formatted skills prompt section
  */
 export declare function formatSkillsForPrompt(skills: Skill[]): string;
-/**
- * Format skill entries for prompt (filters by invocation policy)
- *
- * @param entries - Skill entries to format
- * @returns Formatted skills prompt section
- */
 export declare function formatSkillEntriesForPrompt(entries: SkillEntry[]): string;
 /**
  * Build command specifications from skill entries.
@@ -27,18 +20,6 @@ export declare function formatSkillEntriesForPrompt(entries: SkillEntry[]): stri
  * @returns Array of skill command specifications
  */
 export declare function buildSkillCommandSpecs(entries: SkillEntry[], reservedNames?: Set<string>): SkillCommandSpec[];
-/**
- * Format a single skill for display (minimal format)
- *
- * @param skill - Skill to format
- * @returns Formatted skill string
- */
 export declare function formatSkillSummary(skill: Skill): string;
-/**
- * Format skills as a simple list
- *
- * @param skills - Skills to format
- * @returns Newline-separated list of skills
- */
 export declare function formatSkillsList(skills: Skill[]): string;
 //# sourceMappingURL=formatter.d.ts.map

package/dist/formatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../src/formatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAiBtE;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CA8B7D;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAMzE;AAyDD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,UAAU,EAAE,EACrB,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAC1B,gBAAgB,EAAE,CAgEpB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAExD"}
+{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../src/formatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAMtE;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAwB7D;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAMzE;AAsCD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,UAAU,EAAE,EACrB,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAC1B,gBAAgB,EAAE,CA8DpB;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAEvD;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAExD"}

package/dist/formatter.js

@@ -1,21 +1,9 @@
-/**
- * Escape special XML characters
- *
- * @param str - String to escape
- * @returns XML-escaped string
- */
-function escapeXml(str) {
-    return str
-        .replace(/&/g, "&")
-        .replace(/</g, "&lt;")
-        .replace(/>/g, "&gt;")
-        .replace(/"/g, "&quot;")
-        .replace(/'/g, "&apos;");
+function compactPromptField(str) {
+    return str.replace(/\s+/g, " ").trim();
 }
 /**
  * Format skills for inclusion in a system prompt.
- * Uses XML format per Agent Skills standard.
- * See: https://agentskills.io/integrate-skills
+ * Uses compact structured text.
  *
  * Skills with disableModelInvocation=true are excluded from the prompt
  * (they can only be invoked explicitly via /skill:name commands).
@@ -33,47 +21,29 @@ export function formatSkillsForPrompt(skills) {
         "Use the read tool to load a skill's file when the task matches its description.",
         "When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.",
         "",
-        "<available_skills>",
+        "available_skills:",
     ];
     for (const skill of visibleSkills) {
-        lines.push("  <skill>");
-        lines.push(`    <name>${escapeXml(skill.name)}</name>`);
-        lines.push(`    <description>${escapeXml(skill.description)}</description>`);
+        lines.push(`- name: ${compactPromptField(skill.name)}`);
+        lines.push(`  description: ${compactPromptField(skill.description)}`);
         if (skill.filePath) {
-            lines.push(`    <location>${escapeXml(skill.filePath)}</location>`);
+            lines.push(`  location: ${compactPromptField(skill.filePath)}`);
         }
-        lines.push("  </skill>");
     }
-    lines.push("</available_skills>");
     return lines.join("\n");
 }
-/**
- * Format skill entries for prompt (filters by invocation policy)
- *
- * @param entries - Skill entries to format
- * @returns Formatted skills prompt section
- */
 export function formatSkillEntriesForPrompt(entries) {
     const visibleSkills = entries
         .filter((entry) => entry.invocation?.disableModelInvocation !== true)
         .map((entry) => entry.skill);
     return formatSkillsForPrompt(visibleSkills);
 }
-/** Maximum length for skill command names */
 const SKILL_COMMAND_MAX_LENGTH = 32;
-/** Fallback command name if sanitization produces empty string */
 const SKILL_COMMAND_FALLBACK = "skill";
-/** Maximum length for command descriptions (Discord limit) */
 const SKILL_COMMAND_DESCRIPTION_MAX_LENGTH = 100;
-/**
- * Sanitize a skill name for use as a command name.
- * Converts to lowercase, replaces invalid characters with underscores.
- *
- * @param raw - Raw skill name
- * @returns Sanitized command name
- */
 function sanitizeSkillCommandName(raw) {
-    const normalized = raw
+    const clamped = raw.length > 1024 ? raw.slice(0, 1024) : raw;
+    const normalized = clamped
         .toLowerCase()
         .replace(/[^a-z0-9_]+/g, "_")
         .replace(/_+/g, "_")
@@ -81,19 +51,11 @@ function sanitizeSkillCommandName(raw) {
     const trimmed = normalized.slice(0, SKILL_COMMAND_MAX_LENGTH);
     return trimmed || SKILL_COMMAND_FALLBACK;
 }
-/**
- * Resolve a unique command name by appending a numeric suffix if needed.
- *
- * @param base - Base command name
- * @param used - Set of already-used command names (lowercase)
- * @returns Unique command name
- */
 function resolveUniqueSkillCommandName(base, used) {
-    const normalizedBase = base.toLowerCase();
-    if (!used.has(normalizedBase)) {
-        return base;
-    }
-    for (let index = 2; index < 1000; index += 1) {
+    for (let index = 1;; index += 1) {
+        if (index === 1 && !used.has(base.toLowerCase())) {
+            return base;
+        }
         const suffix = `_${index}`;
         const maxBaseLength = Math.max(1, SKILL_COMMAND_MAX_LENGTH - suffix.length);
         const trimmedBase = base.slice(0, maxBaseLength);
@@ -103,8 +65,6 @@ function resolveUniqueSkillCommandName(base, used) {
             return candidate;
         }
     }
-    const fallback = `${base.slice(0, Math.max(1, SKILL_COMMAND_MAX_LENGTH - 2))}_x`;
-    return fallback;
 }
 /**
  * Build command specifications from skill entries.
@@ -115,7 +75,6 @@ function resolveUniqueSkillCommandName(base, used) {
  * @returns Array of skill command specifications
  */
 export function buildSkillCommandSpecs(entries, reservedNames) {
-    // Filter to user-invocable skills
     const userInvocable = entries.filter((entry) => entry.invocation?.userInvocable !== false);
     const used = new Set();
     for (const reserved of reservedNames ?? []) {
@@ -131,7 +90,6 @@ export function buildSkillCommandSpecs(entries, reservedNames) {
         const description = rawDescription.length > SKILL_COMMAND_DESCRIPTION_MAX_LENGTH
             ? `${rawDescription.slice(0, SKILL_COMMAND_DESCRIPTION_MAX_LENGTH - 1)}…`
             : rawDescription;
-        // Parse dispatch configuration from frontmatter
         const dispatch = (() => {
             const kindRaw = (entry.frontmatter?.["command-dispatch"] ??
                 entry.frontmatter?.command_dispatch ??
@@ -161,21 +119,9 @@ export function buildSkillCommandSpecs(entries, reservedNames) {
     }
     return specs;
 }
-/**
- * Format a single skill for display (minimal format)
- *
- * @param skill - Skill to format
- * @returns Formatted skill string
- */
 export function formatSkillSummary(skill) {
     return `${skill.name}: ${skill.description}`;
 }
-/**
- * Format skills as a simple list
- *
- * @param skills - Skills to format
- * @returns Newline-separated list of skills
- */
 export function formatSkillsList(skills) {
     return skills.map(formatSkillSummary).join("\n");
 }

package/dist/frontmatter.d.ts

@@ -1,39 +1,22 @@
-import type { SkillFrontmatter, SkillInvocationPolicy, SkillMetadata } from "./types.js";
-/**
- * Result of parsing frontmatter from a file
- */
+import type { SkillFrontmatter, SkillInvocationPolicy, SkillMetadata, SkillProvenance } from "./types.js";
 export interface ParsedFrontmatter<T extends Record<string, unknown>> {
-    /** Parsed frontmatter object */
     frontmatter: T;
-    /** Remaining body content after frontmatter */
     body: string;
 }
-/**
- * Parse YAML frontmatter from markdown content
- *
- * @param content - Raw file content with optional YAML frontmatter
- * @returns Parsed frontmatter object and remaining body
- */
 export declare function parseFrontmatter<T extends Record<string, unknown> = Record<string, unknown>>(content: string): ParsedFrontmatter<T>;
-/**
- * Strip frontmatter from content and return only the body
- *
- * @param content - Raw file content with optional YAML frontmatter
- * @returns Content without frontmatter
- */
 export declare function stripFrontmatter(content: string): string;
+export declare function resolveSkillMetadata(frontmatter: SkillFrontmatter): SkillMetadata;
+export declare function resolveSkillInvocationPolicy(frontmatter: SkillFrontmatter): SkillInvocationPolicy;
 /**
- * Resolve Otto-specific metadata from skill frontmatter
- *
- * @param frontmatter - Parsed skill frontmatter
- * @returns Normalized metadata object
+ * Best-effort provenance parsing from a frontmatter block. Returns `undefined`
+ * when the block is missing or malformed (we do not fail loading on bad
+ * provenance — it is informational metadata).
  */
-export declare function resolveSkillMetadata(frontmatter: SkillFrontmatter): SkillMetadata;
+export declare function resolveSkillProvenance(frontmatter: SkillFrontmatter): SkillProvenance | undefined;
 /**
- * Resolve skill invocation policy from frontmatter
- *
- * @param frontmatter - Parsed skill frontmatter
- * @returns Invocation policy
+ * Serialize a SKILL.md file with updated frontmatter, preserving body content.
+ * Used by the closed learning loop to rewrite provenance after refinement and
+ * scoring.
  */
-export declare function resolveSkillInvocationPolicy(frontmatter: SkillFrontmatter): SkillInvocationPolicy;
+export declare function serializeSkillFile(frontmatter: SkillFrontmatter, body: string): string;
 //# sourceMappingURL=frontmatter.d.ts.map

package/dist/frontmatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACrB,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAClE,gCAAgC;IAChC,WAAW,EAAE,CAAC,CAAC;IACf,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;CACd;AAkCD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAOvC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,gBAAgB,GAC5B,aAAa,CAmCf;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,gBAAgB,GAC5B,qBAAqB,CAmBvB"}
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACrB,aAAa,EACb,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAClE,WAAW,EAAE,CAAC,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAkDD,wBAAgB,gBAAgB,CAC9B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAOvC;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,gBAAgB,GAC5B,aAAa,CAqCf;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,gBAAgB,GAC5B,qBAAqB,CAsBvB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,gBAAgB,GAC5B,eAAe,GAAG,SAAS,CAuC7B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,gBAAgB,EAC7B,IAAI,EAAE,MAAM,GACX,MAAM,CAIR"}

package/dist/frontmatter.js

@@ -1,14 +1,23 @@
-import { parse } from "yaml";
-/**
- * Normalize line endings to Unix-style LF
- */
+import { parse, stringify } from "yaml";
 function normalizeNewlines(value) {
     return value.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
 }
-/**
- * Extract YAML frontmatter block from content
- * Frontmatter must start with --- on the first line and end with --- on its own line
- */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function frontmatterValue(frontmatter, kebabKey, snakeKey) {
+    return frontmatter[kebabKey] ?? frontmatter[snakeKey];
+}
+function stringList(value, transform) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const out = value
+        .filter((item) => typeof item === "string")
+        .map(transform)
+        .filter((item) => item.length > 0);
+    return out.length > 0 ? out : undefined;
+}
 function extractFrontmatter(content) {
     const normalized = normalizeNewlines(content);
     if (!normalized.startsWith("---")) {
@@ -23,12 +32,6 @@ function extractFrontmatter(content) {
         body: normalized.slice(endIndex + 4).trim(),
     };
 }
-/**
- * Parse YAML frontmatter from markdown content
- *
- * @param content - Raw file content with optional YAML frontmatter
- * @returns Parsed frontmatter object and remaining body
- */
 export function parseFrontmatter(content) {
     const { yamlString, body } = extractFrontmatter(content);
     if (!yamlString) {
@@ -37,69 +40,87 @@ export function parseFrontmatter(content) {
     const parsed = parse(yamlString);
     return { frontmatter: (parsed ?? {}), body };
 }
-/**
- * Strip frontmatter from content and return only the body
- *
- * @param content - Raw file content with optional YAML frontmatter
- * @returns Content without frontmatter
- */
 export function stripFrontmatter(content) {
     return parseFrontmatter(content).body;
 }
-/**
- * Resolve Otto-specific metadata from skill frontmatter
- *
- * @param frontmatter - Parsed skill frontmatter
- * @returns Normalized metadata object
- */
 export function resolveSkillMetadata(frontmatter) {
     const metadata = {};
-    // Primary environment
-    const primaryEnv = frontmatter["primary-env"] ?? frontmatter.primary_env;
+    const primaryEnv = frontmatterValue(frontmatter, "primary-env", "primary_env");
     if (typeof primaryEnv === "string" && primaryEnv.trim()) {
         metadata.primaryEnv = primaryEnv.trim();
     }
-    // Required operating systems
-    const requiredOs = frontmatter["required-os"] ?? frontmatter.required_os;
-    if (Array.isArray(requiredOs)) {
-        metadata.requiredOs = requiredOs
-            .filter((os) => typeof os === "string")
-            .map((os) => os.trim().toLowerCase());
+    const requiredOs = stringList(frontmatterValue(frontmatter, "required-os", "required_os"), (os) => os.trim().toLowerCase());
+    if (requiredOs) {
+        metadata.requiredOs = requiredOs;
     }
-    // Required binaries
-    const requiredBins = frontmatter["required-bins"] ?? frontmatter.required_bins;
-    if (Array.isArray(requiredBins)) {
-        metadata.requiredBins = requiredBins
-            .filter((bin) => typeof bin === "string")
-            .map((bin) => bin.trim());
+    const requiredBins = stringList(frontmatterValue(frontmatter, "required-bins", "required_bins"), (bin) => bin.trim());
+    if (requiredBins) {
+        metadata.requiredBins = requiredBins;
     }
-    // Required environment variables
-    const requiredEnv = frontmatter["required-env"] ?? frontmatter.required_env;
-    if (Array.isArray(requiredEnv)) {
-        metadata.requiredEnv = requiredEnv
-            .filter((env) => typeof env === "string")
-            .map((env) => env.trim());
+    const requiredEnv = stringList(frontmatterValue(frontmatter, "required-env", "required_env"), (env) => env.trim());
+    if (requiredEnv) {
+        metadata.requiredEnv = requiredEnv;
     }
     return metadata;
 }
-/**
- * Resolve skill invocation policy from frontmatter
- *
- * @param frontmatter - Parsed skill frontmatter
- * @returns Invocation policy
- */
 export function resolveSkillInvocationPolicy(frontmatter) {
     const policy = {};
-    // Disable model invocation (snake_case and kebab-case)
-    const disableModelInvocation = frontmatter["disable-model-invocation"] ??
-        frontmatter.disable_model_invocation;
+    const disableModelInvocation = frontmatterValue(frontmatter, "disable-model-invocation", "disable_model_invocation");
     if (disableModelInvocation === true) {
         policy.disableModelInvocation = true;
     }
-    // User invocable (snake_case and kebab-case)
-    const userInvocable = frontmatter["user-invocable"] ?? frontmatter.user_invocable;
+    const userInvocable = frontmatterValue(frontmatter, "user-invocable", "user_invocable");
     if (userInvocable === false) {
         policy.userInvocable = false;
     }
     return policy;
 }
+/**
+ * Best-effort provenance parsing from a frontmatter block. Returns `undefined`
+ * when the block is missing or malformed (we do not fail loading on bad
+ * provenance — it is informational metadata).
+ */
+export function resolveSkillProvenance(frontmatter) {
+    const raw = frontmatter.provenance;
+    if (!isRecord(raw)) {
+        return undefined;
+    }
+    const source = raw.source;
+    if (source !== "human" &&
+        source !== "agent-generated" &&
+        source !== "agent-refined") {
+        return undefined;
+    }
+    const createdAt = typeof raw.createdAt === "string" ? raw.createdAt : undefined;
+    if (!createdAt) {
+        return undefined;
+    }
+    const refinedCountRaw = raw.refinedCount;
+    const refinedCount = typeof refinedCountRaw === "number" && Number.isFinite(refinedCountRaw)
+        ? Math.max(0, Math.floor(refinedCountRaw))
+        : 0;
+    const provenance = {
+        source,
+        createdAt,
+        refinedCount,
+    };
+    if (typeof raw.derivedFromTrajectory === "string") {
+        provenance.derivedFromTrajectory = raw.derivedFromTrajectory;
+    }
+    if (typeof raw.lastEvalScore === "number" &&
+        Number.isFinite(raw.lastEvalScore)) {
+        const score = raw.lastEvalScore;
+        provenance.lastEvalScore = Math.max(0, Math.min(1, score));
+    }
+    return provenance;
+}
+/**
+ * Serialize a SKILL.md file with updated frontmatter, preserving body content.
+ * Used by the closed learning loop to rewrite provenance after refinement and
+ * scoring.
+ */
+export function serializeSkillFile(frontmatter, body) {
+    const yaml = stringify(frontmatter).trimEnd();
+    const trimmedBody = body.replace(/^\n+/, "");
+    return `---\n${yaml}\n---\n\n${trimmedBody}`;
+}

package/dist/index.d.ts

@@ -22,8 +22,8 @@
  * ```
  */
 export { buildSkillCommandSpecs, formatSkillEntriesForPrompt, formatSkillSummary, formatSkillsForPrompt, formatSkillsList, } from "./formatter.js";
-export { type ParsedFrontmatter, parseFrontmatter, resolveSkillInvocationPolicy, resolveSkillMetadata, stripFrontmatter, } from "./frontmatter.js";
+export { type ParsedFrontmatter, parseFrontmatter, resolveSkillInvocationPolicy, resolveSkillMetadata, resolveSkillProvenance, serializeSkillFile, stripFrontmatter, } from "./frontmatter.js";
 export { loadSkillEntries, loadSkills, loadSkillsFromDir } from "./loader.js";
-export { clearSkillsDirCache, getSkillsDir } from "./resolver.js";
-export type { LoadSkillsFromDirOptions, LoadSkillsOptions, LoadSkillsResult, Skill, SkillActionDefinition, SkillCommandSpec, SkillDiagnostic, SkillEntry, SkillFrontmatter, SkillInvocationPolicy, SkillMetadata, SkillProviderDefinition, SkillToolDefinition, } from "./types.js";
+export { clearSkillsDirCache, getCuratedActiveDir, getProposedSkillsDir, getSkillsDir, promoteSkill, } from "./resolver.js";
+export type { LoadSkillsFromDirOptions, LoadSkillsOptions, LoadSkillsResult, Skill, SkillActionDefinition, SkillCommandSpec, SkillDiagnostic, SkillEntry, SkillFrontmatter, SkillInvocationPolicy, SkillMetadata, SkillProvenance, SkillProviderDefinition, SkillToolDefinition, } 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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,4BAA4B,EAC5B,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE9E,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElE,YAAY,EACV,wBAAwB,EACxB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,EACL,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,gBAAgB,EAChB,qBAAqB,EACrB,aAAa,EACb,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,4BAA4B,EAC5B,oBAAoB,EACpB,sBAAsB,EACtB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,wBAAwB,EACxB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,EACL,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,gBAAgB,EAChB,qBAAqB,EACrB,aAAa,EACb,eAAe,EACf,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -21,11 +21,7 @@
  * const prompt = formatSkillsForPrompt(skills);
  * ```
  */
-// Prompt formatting
 export { buildSkillCommandSpecs, formatSkillEntriesForPrompt, formatSkillSummary, formatSkillsForPrompt, formatSkillsList, } from "./formatter.js";
-// Frontmatter parsing
-export { parseFrontmatter, resolveSkillInvocationPolicy, resolveSkillMetadata, stripFrontmatter, } from "./frontmatter.js";
-// Skill loading
+export { parseFrontmatter, resolveSkillInvocationPolicy, resolveSkillMetadata, resolveSkillProvenance, serializeSkillFile, stripFrontmatter, } from "./frontmatter.js";
 export { loadSkillEntries, loadSkills, loadSkillsFromDir } from "./loader.js";
-// Path resolution
-export { clearSkillsDirCache, getSkillsDir } from "./resolver.js";
+export { clearSkillsDirCache, getCuratedActiveDir, getProposedSkillsDir, getSkillsDir, promoteSkill, } from "./resolver.js";

package/dist/loader.d.ts

@@ -15,7 +15,7 @@ export declare function loadSkillsFromDir(options: LoadSkillsFromDirOptions): Lo
  *
  * Sources are loaded in precedence order (later sources override earlier):
  * 1. Bundled skills (from this package)
- * 2. User/managed skills (~/.elizaos/skills)
+ * 2. User/managed skills (<stateDir>/skills)
  * 3. Project skills (<cwd>/.elizaos/skills)
  * 4. Explicit skill paths
  *

package/dist/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EACV,wBAAwB,EACxB,iBAAiB,EACjB,gBAAgB,EAGhB,UAAU,EAEX,MAAM,YAAY,CAAC;AAkMpB;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,wBAAwB,GAChC,gBAAgB,CAGlB;AA8CD;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CA0H5E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,iBAAsB,GAC9B,UAAU,EAAE,CAuBd"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EACV,wBAAwB,EACxB,iBAAiB,EACjB,gBAAgB,EAGhB,UAAU,EAEX,MAAM,YAAY,CAAC;AA0JpB;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,wBAAwB,GAChC,gBAAgB,CAGlB;AA0BD;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAkH5E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,iBAAsB,GAC9B,UAAU,EAAE,CAkBd"}