@elizaos/skills 2.0.0-alpha.22 → 2.0.0-alpha.223

package/README.md

@@ -62,6 +62,10 @@ 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):

package/dist/frontmatter.d.ts

@@ -1,4 +1,4 @@
-import type { SkillFrontmatter, SkillInvocationPolicy, SkillMetadata } from "./types.js";
+import type { SkillFrontmatter, SkillInvocationPolicy, SkillMetadata, SkillProvenance } from "./types.js";
 /**
  * Result of parsing frontmatter from a file
  */
@@ -36,4 +36,16 @@ export declare function resolveSkillMetadata(frontmatter: SkillFrontmatter): Ski
  * @returns Invocation policy
  */
 export declare function resolveSkillInvocationPolicy(frontmatter: SkillFrontmatter): SkillInvocationPolicy;
+/**
+ * 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 resolveSkillProvenance(frontmatter: SkillFrontmatter): SkillProvenance | undefined;
+/**
+ * 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 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;;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;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,gBAAgB,GAC5B,eAAe,GAAG,SAAS,CAwC7B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,gBAAgB,EAC7B,IAAI,EAAE,MAAM,GACX,MAAM,CAIR"}

package/dist/frontmatter.js

@@ -1,4 +1,4 @@
-import { parse } from "yaml";
+import { parse, stringify } from "yaml";
 /**
  * Normalize line endings to Unix-style LF
  */
@@ -103,3 +103,53 @@ export function resolveSkillInvocationPolicy(frontmatter) {
     }
     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 (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return undefined;
+    }
+    const record = raw;
+    const source = record.source;
+    if (source !== "human" &&
+        source !== "agent-generated" &&
+        source !== "agent-refined") {
+        return undefined;
+    }
+    const createdAt = typeof record.createdAt === "string" ? record.createdAt : undefined;
+    if (!createdAt) {
+        return undefined;
+    }
+    const refinedCountRaw = record.refinedCount;
+    const refinedCount = typeof refinedCountRaw === "number" && Number.isFinite(refinedCountRaw)
+        ? Math.max(0, Math.floor(refinedCountRaw))
+        : 0;
+    const provenance = {
+        source,
+        createdAt,
+        refinedCount,
+    };
+    if (typeof record.derivedFromTrajectory === "string") {
+        provenance.derivedFromTrajectory = record.derivedFromTrajectory;
+    }
+    if (typeof record.lastEvalScore === "number" &&
+        Number.isFinite(record.lastEvalScore)) {
+        const score = record.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;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,sBAAsB,EACtB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE9E,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,YAAY,GACb,MAAM,eAAe,CAAC;AAEvB,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

@@ -24,8 +24,8 @@
 // Prompt formatting
 export { buildSkillCommandSpecs, formatSkillEntriesForPrompt, formatSkillSummary, formatSkillsForPrompt, formatSkillsList, } from "./formatter.js";
 // Frontmatter parsing
-export { parseFrontmatter, resolveSkillInvocationPolicy, resolveSkillMetadata, stripFrontmatter, } from "./frontmatter.js";
+export { parseFrontmatter, resolveSkillInvocationPolicy, resolveSkillMetadata, resolveSkillProvenance, serializeSkillFile, stripFrontmatter, } from "./frontmatter.js";
 // Skill loading
 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.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":"AAgBA,OAAO,KAAK,EACV,wBAAwB,EACxB,iBAAiB,EACjB,gBAAgB,EAGhB,UAAU,EAEX,MAAM,YAAY,CAAC;AAqMpB;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,wBAAwB,GAChC,gBAAgB,CAGlB;AA8CD;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAiI5E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,iBAAsB,GAC9B,UAAU,EAAE,CAuBd"}

package/dist/loader.js

@@ -1,8 +1,8 @@
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync, } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
-import { parseFrontmatter, resolveSkillInvocationPolicy, resolveSkillMetadata, } from "./frontmatter.js";
-import { getSkillsDir } from "./resolver.js";
+import { parseFrontmatter, resolveSkillInvocationPolicy, resolveSkillMetadata, resolveSkillProvenance, } from "./frontmatter.js";
+import { getCuratedActiveDir, getSkillsDir } from "./resolver.js";
 /** Maximum skill name length per Agent Skills spec */
 const MAX_NAME_LENGTH = 64;
 /** Maximum description length per Agent Skills spec */
@@ -83,6 +83,7 @@ function loadSkillFromFile(filePath, source) {
     if (!frontmatter.description || frontmatter.description.trim() === "") {
         return { skill: null, diagnostics };
     }
+    const provenance = resolveSkillProvenance(frontmatter);
     return {
         skill: {
             name,
@@ -91,6 +92,7 @@ function loadSkillFromFile(filePath, source) {
             baseDir: skillDir,
             source,
             disableModelInvocation: frontmatter["disable-model-invocation"] === true,
+            ...(provenance ? { provenance } : {}),
         },
         diagnostics,
     };
@@ -276,11 +278,16 @@ export function loadSkills(options = {}) {
         }
     }
     if (includeDefaults) {
-        // Load in precedence order: bundled < managed < project
+        // Load in precedence order: bundled < managed < curated < project.
+        // The curated namespace holds agent-derived skills that were promoted to
+        // "active" by the closed learning loop or the user. Skills under the
+        // sibling "proposed" directory are intentionally NOT scanned here — they
+        // are pending human review and only surfaced via the curated-skills API.
         if (resolvedBundledDir) {
             addSkills(loadSkillsFromDirInternal(resolvedBundledDir, "bundled", true));
         }
         addSkills(loadSkillsFromDirInternal(resolvedManagedDir, "managed", true));
+        addSkills(loadSkillsFromDirInternal(getCuratedActiveDir(), "curated", true));
         addSkills(loadSkillsFromDirInternal(projectSkillsDir, "project", true));
     }
     // Determine source for explicit paths

package/dist/resolver.d.ts

@@ -15,4 +15,21 @@ export declare function getSkillsDir(): string;
  * Useful for testing or when the directory may have changed.
  */
 export declare function clearSkillsDirCache(): void;
+/**
+ * Absolute path to the curated **active** skills directory. Skills here are
+ * loaded into the runtime alongside bundled and managed skills.
+ */
+export declare function getCuratedActiveDir(): string;
+/**
+ * Absolute path to the curated **proposed** skills directory. Skills here are
+ * NEVER loaded into the runtime — they are staged for human review via the
+ * Settings → Learned Skills UI.
+ */
+export declare function getProposedSkillsDir(): string;
+/**
+ * Promote a proposed skill to active by moving its directory atomically.
+ * Returns the destination path. Throws if the source does not exist or the
+ * destination already exists.
+ */
+export declare function promoteSkill(name: string): string;
 //# sourceMappingURL=resolver.d.ts.map

package/dist/resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../src/resolver.ts"],"names":[],"mappings":"AAwCA;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,IAAI,MAAM,CA6CrC;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C"}
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../src/resolver.ts"],"names":[],"mappings":"AA+CA;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,IAAI,MAAM,CA6CrC;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAiBD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoBjD"}

package/dist/resolver.js

@@ -1,6 +1,7 @@
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, renameSync, statSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { resolveStateDir } from "@elizaos/core";
 /**
  * Cached skills directory path
  */
@@ -88,3 +89,55 @@ export function getSkillsDir() {
 export function clearSkillsDirCache() {
     cachedSkillsDir = undefined;
 }
+/**
+ * Default base directory for the curated learning loop. Lives alongside the
+ * Milady state dir (`~/.milady/`) and holds two sibling namespaces:
+ *
+ *   curated/active/    — auto-promoted or human-promoted skills (loaded)
+ *   curated/proposed/  — staged drafts awaiting human review (NOT loaded)
+ *
+ * Honors `MILADY_STATE_DIR` and `ELIZA_STATE_DIR` (in that order); falls back
+ * to `~/.milady`.
+ */
+function resolveCuratedBaseDir() {
+    return join(resolveStateDir(), "skills", "curated");
+}
+/**
+ * Absolute path to the curated **active** skills directory. Skills here are
+ * loaded into the runtime alongside bundled and managed skills.
+ */
+export function getCuratedActiveDir() {
+    return join(resolveCuratedBaseDir(), "active");
+}
+/**
+ * Absolute path to the curated **proposed** skills directory. Skills here are
+ * NEVER loaded into the runtime — they are staged for human review via the
+ * Settings → Learned Skills UI.
+ */
+export function getProposedSkillsDir() {
+    return join(resolveCuratedBaseDir(), "proposed");
+}
+/**
+ * Promote a proposed skill to active by moving its directory atomically.
+ * Returns the destination path. Throws if the source does not exist or the
+ * destination already exists.
+ */
+export function promoteSkill(name) {
+    if (!/^[a-z0-9-]+$/.test(name)) {
+        throw new Error(`Invalid skill name "${name}" — must be lowercase a-z, 0-9, hyphens only`);
+    }
+    const proposedDir = join(getProposedSkillsDir(), name);
+    if (!existsSync(proposedDir) || !statSync(proposedDir).isDirectory()) {
+        throw new Error(`Proposed skill "${name}" not found at ${proposedDir}`);
+    }
+    const activeRoot = getCuratedActiveDir();
+    if (!existsSync(activeRoot)) {
+        mkdirSync(activeRoot, { recursive: true });
+    }
+    const activeDir = join(activeRoot, name);
+    if (existsSync(activeDir)) {
+        throw new Error(`Active skill "${name}" already exists at ${activeDir}`);
+    }
+    renameSync(proposedDir, activeDir);
+    return activeDir;
+}

package/dist/types.d.ts

@@ -1,3 +1,32 @@
+/**
+ * Provenance of a skill — distinguishes human-authored from agent-derived
+ * skills, and tracks self-improvement signal across the closed learning loop.
+ */
+export interface SkillProvenance {
+    /** Whether the skill was authored by a human or derived by the agent. */
+    source: "human" | "agent-generated" | "agent-refined";
+    /** Trajectory that produced or last refined the skill, if any. */
+    derivedFromTrajectory?: string;
+    /** ISO8601 timestamp when this provenance entry was recorded. */
+    createdAt: string;
+    /** Number of times the agent has automatically refined this skill. */
+    refinedCount: number;
+    /** Most recent eval score from the scoring cron, in [0, 1]. */
+    lastEvalScore?: number;
+    /**
+     * Audit trail for native-optimizer-driven skill refinements.
+     *
+     * Populated by the gradient-mode branch of `skillRefinementEvaluator` —
+     * after the LLM-diff auto-budget is exhausted, the evaluator switches to
+     * the native `prompt-evolution` optimizer and appends one entry per run.
+     */
+    optimizationLineage?: Array<{
+        optimizer: "instruction-search" | "prompt-evolution" | "bootstrap-fewshot";
+        score: number;
+        datasetSize: number;
+        generatedAt: string;
+    }>;
+}
 /**
  * Skill frontmatter parsed from SKILL.md YAML header
  */
@@ -28,6 +57,8 @@ export interface SkillFrontmatter {
     "command-arg-mode"?: string;
     /** Whether skill can be invoked by users via commands */
     "user-invocable"?: boolean;
+    /** Provenance metadata — present on agent-derived/curated skills. */
+    provenance?: SkillProvenance;
     /** Additional arbitrary metadata */
     [key: string]: unknown;
 }
@@ -46,10 +77,16 @@ export interface Skill {
     filePath?: string;
     /** Absolute path to the skill's base directory (optional for inline skills) */
     baseDir?: string;
-    /** Source identifier (e.g., "bundled", "workspace", "managed", "inline") */
+    /** Source identifier (e.g., "bundled", "workspace", "managed", "inline", "curated") */
     source?: string;
     /** If true, skill won't be included in model prompts */
     disableModelInvocation?: boolean;
+    /**
+     * Provenance metadata when the skill was derived from a trajectory or
+     * user-authored as a "curated" skill. Optional for backward compatibility:
+     * existing on-disk skills with no provenance block are treated as `human`.
+     */
+    provenance?: SkillProvenance;
     /** Unique slug identifier for the skill */
     slug?: string;
     /** Skill version */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,55 +1,59 @@
 {
-	"name": "@elizaos/skills",
-	"version": "2.0.0-alpha.22",
-	"description": "Bundled skills and skill loading utilities for elizaOS agents",
-	"type": "module",
-	"main": "dist/index.js",
-	"types": "dist/index.d.ts",
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js"
-		},
-		"./skills": "./skills/",
-		"./package.json": "./package.json"
-	},
-	"scripts": {
-		"clean": "rm -rf dist",
-		"build": "tsc -p tsconfig.build.json",
-		"dev": "tsgo -p tsconfig.build.json --watch --preserveWatchOutput",
-		"test": "node --test --import tsx test/*.test.ts",
-		"prepublishOnly": "npm run clean && npm run build",
-		"lint": "bunx @biomejs/biome check --write ./src",
-		"lint:check": "bunx @biomejs/biome check ./src"
-	},
-	"files": [
-		"dist/**/*",
-		"skills/**/*",
-		"README.md"
-	],
-	"keywords": [
-		"elizaos",
-		"skills",
-		"agent",
-		"ai",
-		"llm",
-		"automation"
-	],
-	"author": "elizaOS",
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/elizaos/eliza.git",
-		"directory": "packages/skills"
-	},
-	"engines": {
-		"node": ">=22.0.0"
-	},
-	"dependencies": {
-		"yaml": "^2.8.2"
-	},
-	"publishConfig": {
-		"access": "public"
-	},
-	"gitHead": "56caa0e2d9f193f75091154d639df4a48065d80f"
+  "name": "@elizaos/skills",
+  "version": "2.0.0-alpha.223",
+  "description": "Bundled skills and skill loading utilities for elizaOS agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./skills": "./skills/",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsgo -p tsconfig.build.json --watch --preserveWatchOutput",
+    "test": "bun test ./test",
+    "prepublishOnly": "bun run clean && bun run build",
+    "lint": "bunx @biomejs/biome check --write ./src",
+    "lint:check": "bunx @biomejs/biome check ./src"
+  },
+  "files": [
+    "dist/**/*",
+    "skills/**/*",
+    "README.md"
+  ],
+  "keywords": [
+    "elizaos",
+    "skills",
+    "agent",
+    "ai",
+    "llm",
+    "automation"
+  ],
+  "author": "elizaOS",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elizaos/eliza.git",
+    "directory": "packages/skills"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@elizaos/core": "2.0.0-alpha.223",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "a15bf080b2db209356eed76b5752ed1967aa96c1"
 }

package/skills/eliza-app-development/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: eliza-app-development
+description: "Use when building or changing an elizaOS-based application in this repository. Covers eliza app architecture, monorepo layout, local versus remote versus cloud routing, where to edit features, and non-negotiable runtime constraints. Eliza is the product name of this particular eliza app checkout."
+---
+
+# eliza app development
+
+This repository is an **elizaOS application**: a local-first assistant with CLI, dashboard, Electrobun desktop shell, connectors, and Eliza Cloud integration. **Eliza** is this app’s product and CLI name—not a separate platform from elizaOS.
+
+## Read These References First
+
+- `references/repo-map.md` for layout, edit targets, and common commands
+- `references/runtime-and-cloud.md` for runtime flow, onboarding, service routing, skills, and Eliza Cloud behavior
+
+## Editing Heuristics
+
+- Prefer `packages/app-core/` for app shell behavior (API, CLI, onboarding, config).
+- Prefer `packages/agent/` for agent providers, services, and runtime glue around elizaOS.
+- Prefer `apps/app/` for UI and Electrobun work.
+- Treat `eliza/cloud/` as the Eliza Cloud product and backend surface.
+- Treat `eliza/` as upstream elizaOS. Edit it only when the bug or feature is genuinely upstream.
+
+## Hard Constraints
+
+- Do not remove `NODE_PATH` setup.
+- Do not remove the Bun exports patch.
+- Do not remove Electrobun startup error guards.
+- Keep Node and Bun paths working.
+
+## Repo Workflow
+
+```bash
+bun install
+bun run verify
+bun run test
+```
+
+Narrower commands when useful:
+
+```bash
+bun run eliza ...
+bun run dev
+bun run dev:desktop
+bun run test:e2e
+```
+
+## Where to Look First
+
+- Product and runtime behavior: `packages/app-core/src/`
+- Prompt, provider, and skill plumbing: `packages/agent/src/`
+- Onboarding and routing: `packages/app-core/src/onboarding/` and `packages/app-core/src/runtime/`
+- Shipped default skills: bundled in `@elizaos/skills`, seeded into the state-dir skills folder by `scripts/ensure-skills.mjs`
+- Eliza Cloud backend or monetization: `eliza/cloud/` and the shipped `eliza-cloud` skill
+
+## Cloud Default
+
+If the task involves building an app and Eliza Cloud is enabled, linked, or explicitly requested, treat Cloud as the default managed backend before inventing custom auth, billing, analytics, or hosting. Use the `eliza-cloud` skill for app, monetization, and container details.
+
+## Related Skills
+
+- `elizaos` — core runtime abstractions and upstream plugin patterns
+- `eliza-cloud` — apps, billing, monetization, auth, containers

package/skills/eliza-app-development/references/repo-map.md

@@ -0,0 +1,70 @@
+# eliza app repo map
+
+## What this repository is
+
+This checkout is an **elizaOS application**: runtime, UI, connectors, and Cloud hooks bundled as the **Eliza** product (CLI `eliza`, user-facing name Eliza). Same stack patterns apply to other eliza apps; this repo is one concrete implementation.
+
+It combines:
+
+- a local-first runtime and CLI
+- a web dashboard
+- an Electrobun desktop shell
+- connector integrations
+- Eliza Cloud routing, provisioning, and billing hooks
+
+## Main edit targets
+
+### `packages/app-core/`
+
+Primary app-shell logic.
+
+- `src/runtime/` for runtime bootstrap, env shaping, provider routing, and process behavior
+- `src/cli/` for CLI wiring
+- `src/api/` for app HTTP routes
+- `src/config/` for config schemas and canonical routing/storage fields
+- `src/connectors/` for platform integrations
+- `src/providers/` for prompt/state context builders
+
+### `packages/agent/`
+
+Agent layer on elizaOS: providers, skill discovery and catalog plumbing, runtime compatibility layers, training and testing helpers.
+
+### `apps/app/`
+
+Main React UI and desktop shell: web UI, onboarding, settings, Electrobun native process under `apps/app/electrobun/`.
+
+### `eliza/cloud/`
+
+Eliza Cloud product code (git submodule nested under `eliza/`): apps, billing, earnings, auth, containers, domains, cloud-side agent runtime and plugins.
+
+### `eliza/`
+
+Repo-local upstream elizaOS checkout for linked development. Change this only when the issue is genuinely upstream or the user asks for upstream work.
+
+## Commands
+
+```bash
+bun install
+bun run verify
+bun run test
+```
+
+Useful narrower commands:
+
+```bash
+bun run dev
+bun run dev:desktop
+bun run eliza ...
+bun run test:e2e
+bun run test:coverage
+```
+
+## Non-negotiable runtime invariants
+
+- `NODE_PATH` setup is required for dynamic plugin imports.
+- The Bun exports patch is required for some published `@elizaos/*` packages.
+- Electrobun startup guards keep the desktop UI usable when the runtime fails.
+
+## Default skill seeding
+
+Shipped skills are bundled in `@elizaos/skills` and are seeded into the state-dir skills folder (e.g. `~/.eliza/skills` when `ELIZA_NAMESPACE=eliza`) by Eliza’s `scripts/ensure-skills.mjs`. They are default agent knowledge, not optional extras.