@elizaos/skills 2.0.0-alpha.53 → 2.0.0-alpha.533

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/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;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;AA0DD;;;;;;;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"}

package/dist/formatter.js

@@ -73,7 +73,8 @@ const SKILL_COMMAND_DESCRIPTION_MAX_LENGTH = 100;
  * @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, "_")

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;AAgBD;;;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
+ * Eliza state dir (`~/.eliza/`) and holds two sibling namespaces:
+ *
+ *   curated/active/    — auto-promoted or human-promoted skills (loaded)
+ *   curated/proposed/  — staged drafts awaiting human review (NOT loaded)
+ *
+ * Honors `ELIZA_STATE_DIR` and `ELIZA_STATE_DIR` (in that order); falls back
+ * to `~/.eliza`.
+ */
+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.53",
-	"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": "8402160dd2dfee0e3cdbd9dc6fb40408f995b094"
+  "name": "@elizaos/skills",
+  "version": "2.0.0-alpha.533",
+  "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.533",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "05dabeb45ed8d069d15ca63082c42c315d1540e7"
 }

package/skills/build-monetized-app/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: build-monetized-app
+description: "Use when the task is building a new app on Eliza Cloud that earns money — chat apps, agent apps, MCP-backed tools, anything that calls the cloud's chat/messages/inference endpoints on behalf of users. Covers app registration, container deploy, markup configuration, affiliate header, and the survival-economics loop where earnings auto-fund the agent's own hosting. Pairs with the `eliza-cloud` skill (which covers Cloud as a backend in general) by focusing specifically on the build-and-monetize flow."
+---
+
+# Build a monetized app on Eliza Cloud
+
+Use this skill when you need to build an app that takes a markup on every chat or inference call and credits the earnings back to your owner. Eliza Cloud already supports app registration, per-app API keys, container deploys, the `appId`-based auth and redirect flow, the affiliate-header revenue path, and creator-monetization plumbing — you do not need to invent any of these.
+
+Read `references/sdk-flow.md` for the 6-step build flow with a self-contained code example. External references (all public):
+
+- **Working chat-app**: [`elizaOS/cloud-mini-apps/apps/edad-chat`](https://github.com/elizaOS/cloud-mini-apps/tree/main/apps/edad-chat) — copyable end-to-end implementation. Read its `server.ts` and `api/proxy.ts` for the canonical chat-forwarder shape using `@elizaos/cloud-sdk`.
+- **SDK reference**: [`@elizaos/cloud-sdk` README](https://github.com/elizaOS/cloud/tree/develop/packages/sdk) — typed methods + helpers + auth.
+- **Human-readable recipe**: [`docs/building-a-monetized-app.md`](https://github.com/elizaOS/cloud/blob/develop/docs/building-a-monetized-app.md) — same loop, narrative form, with the schema fields explained.
+
+## The survival-economics loop
+
+A Eliza-style agent running in an Eliza Cloud container costs ~$0.67/day at the default tier (256 MB CPU + 512 MB RAM). When the org's credit balance and the owner's redeemable earnings both hit zero, the container is stopped after a 48-hour grace window. The container-billing cron pulls earnings before credits, so an app that earns more than its hosting costs keeps the agent alive indefinitely. See `references/survival-economics.md` for the exact accounting (`redeemable_earnings_ledger`, `credit_transactions`, the cron at `app/api/cron/container-billing/route.ts`).
+
+This is why the skill exists: making money is how the agent stays online.
+
+## Default flow
+
+```ts
+import { ElizaCloudClient } from "@elizaos/cloud-sdk";
+
+const cloud = new ElizaCloudClient({ apiKey: process.env.ELIZAOS_CLOUD_API_KEY });
+
+// 1. register the app
+const { app, apiKey } = await cloud.routes.postApiV1Apps({
+  json: { name, app_url: "https://placeholder.invalid", skipGitHubRepo: true },
+});
+
+// 2. build + push container image
+// 3. deploy container
+// 4. set markup %
+// 5. patch app_url + allowed_origins to the container URL
+// 6. report URLs to the human
+```
+
+Full code in `references/sdk-flow.md`. The skill assumes you have:
+
+- `ELIZAOS_CLOUD_API_KEY` in env (Eliza packages this for you)
+- `@elizaos/cloud-sdk` available (already a runtime dependency)
+- A goal and a name (make the name up if not given; collisions retry once with a 6-char suffix)
+
+## Auth + monetization headers
+
+Every cloud-SDK call your deployed app makes on behalf of a user MUST carry:
+
+- `Authorization: Bearer <user_jwt>` — the JWT from the app-auth OAuth redirect
+- `x-affiliate-code: <your_affiliate_code>` — the owner's affiliate code; this is what credits earnings
+
+This pattern is shared with the [`eliza-cloud`](../eliza-cloud/SKILL.md) skill; see that skill for the auth flow itself. This skill assumes you've already read it.
+
+## Read these references in order
+
+1. `references/sdk-flow.md` — the 6-step deploy + monetize flow with full code
+2. `references/survival-economics.md` — why this matters; how earnings flow into hosting
+3. `references/failure-modes.md` — recovery table for the failures you'll actually hit (name collision, container deploy failure, auth blocker, etc.)
+
+## What this skill is NOT
+
+- **It is not the app's product code.** The skill is the deploy + monetize + survive surface. What the app DOES is up to you given the task.
+- **It is not a retry loop.** Each SDK call is idempotent; if step 5 fails, restart from there.
+- **It does not configure affiliate codes.** Affiliate codes belong to the owner, not the app, and live across all of an owner's apps. The skill inherits whatever is configured.
+- **It does not assume always-on billing.** The org may have set `pay_as_you_go_from_earnings = false`, in which case hosting comes purely from credits and earnings stay on the redemption ledger. The skill works either way; the org's owner controls the toggle.

package/skills/build-monetized-app/references/failure-modes.md

@@ -0,0 +1,69 @@
+# Failure modes and recovery
+
+The recovery table for the failures you'll actually encounter when running the SDK flow. Each row is a real failure shape, what causes it, and what you do.
+
+## Registration failures (step 1)
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| `409 name_collision` from `postApiV1Apps` | Another app on the org or globally already uses this name | Append a 6-char random base36 suffix (`Math.random().toString(36).slice(2, 8)`) and retry once. If the retry also collides, surface to the human — that's a naming conflict the agent shouldn't auto-resolve a second time. |
+| `400 invalid_app_url` | The placeholder URL doesn't match the cloud's URL-format check | Use `https://placeholder.invalid` (the canonical placeholder); RFC-2606 reserves `.invalid` so it always parses but never resolves. |
+| `403 quota_exceeded` on app creation | Org has hit its `apps_per_org` limit | Tell the human; they need to retire an old app or upgrade the tier. Do not silently delete an existing app. |
+
+## Image build / push failures (step 2)
+
+The agent's job, not the SDK's. Common shapes:
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| `denied: requested access to the resource is denied` on push | Registry credentials missing or wrong scope | Ask the human to fix registry creds; pause until resolved. |
+| `manifest unknown` / `403` from registry | The image tag doesn't exist (build silently failed) | Re-run the build with `--quiet=false` to see the actual error; surface that to the human if it's a Dockerfile issue. |
+| Image pushes fine but container deploy fails health-check | Image's server doesn't bind to `$PORT`, or binds to `127.0.0.1` instead of `0.0.0.0` | Read `cloud.routes.getApiV1ContainersByIdLogs(id)`, find the bind line, fix the Dockerfile or server.ts. |
+
+## Container deploy failures (step 3)
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| `402 insufficient_balance` from `postApiV1Containers` | Org has zero credits AND zero earnings | Tell the human to top up at `/dashboard/billing`. There's no auto-recovery here — an agent that can't pay can't deploy. |
+| Container starts but `status` stays `pending` for >5 min | Image pull is slow (large image) or scheduler is congested | Wait up to 10 min before declaring failure. Past that, pull container logs and surface. |
+| Container hits `crash_loop` immediately | Image runs but exits non-zero on startup | Pull `getApiV1ContainersByIdLogs(id)`, surface the stderr to the human, pause. Common causes: missing env var, server bind issue, missing dependency in the image. |
+| `403 quota_exceeded` on container deploy | Org has hit `containers_per_org` | Tell the human; they need to remove a container or upgrade. |
+
+## Markup configuration (step 4)
+
+Generally bulletproof since `inference_markup_percentage` is just a number on the apps table. Rare:
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| `400 markup_out_of_range` | Markup outside the allowed bound (typically 0–50%) | Cap your value at the bound and retry. |
+
+## Patch app_url + origins (step 5)
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| `400 invalid_origin` | Container's `load_balancer_url` is nil because container isn't ready yet | Re-poll `getApiV1ContainersById` until `status === "running"` and `load_balancer_url` is populated, then patch. |
+
+## Custom domain (post-skill, optional)
+
+If the human asks for a custom domain after deploy:
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| `verified: false` on the domain after add | DNS hasn't propagated | Tell the human; verification is async and depends on their DNS provider. The skill's job is done after step 6 — domain verification is not part of the skill. |
+
+## Auth flow failures (during user signup)
+
+These hit AFTER the skill is complete, when users actually try to sign in to the deployed app. Not the skill's responsibility, but worth knowing:
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| OAuth redirect lands on `404` at `/api/v1/app-auth/connect` | Cloud hasn't deployed the steward-sync path yet | Out of scope for this skill — it's an upstream cloud deploy issue. |
+| User completes OAuth but chat returns `401 invalid_jwt` | The user's JWT shape changed between signup and request | Have the user re-sign-in. If it persists, the issue is upstream. |
+
+## What you don't recover from
+
+If the agent can't deploy at all (zero credits AND zero earnings) the loop has bottomed out. There's no programmatic recovery — only the human can top up. Tell them clearly:
+
+> "I can't deploy a new app — both org credits and your redeemable earnings are zero. Top up at https://www.elizacloud.ai/dashboard/billing or earn enough on existing apps to cover the next deploy."
+
+This is a survival-economics terminal state, not a code bug.