@prismer/runtime 2.0.7 → 2.2.55

package/built-in-skills/skill-authoring/skill.json

@@ -0,0 +1,74 @@
+{
+  "schemaVersion": 1,
+  "slug": "skill-authoring",
+  "name": "Skill Authoring",
+  "description": "Generate Prismer-compliant skill drafts from user intent, documentation URLs, existing code, or service endpoints. Wraps Anthropic skill-creator's writing knowledge into an executable pipeline that emits multi-file manifest v1 and persists as status=draft via cloud endpoint.",
+  "category": "workflow",
+  "version": "1.0.0",
+  "license": "MIT",
+  "compatibility": [
+    "prismer-sdk",
+    "hermes",
+    "openclaw",
+    "claude-code",
+    "codex"
+  ],
+  "runtime": {
+    "kind": "text-workflow",
+    "executableJson": {
+      "kind": "cli",
+      "command": "cloud skill draft create {{bundle_dir}}"
+    },
+    "requires": {
+      "env": ["PRISMER_API_KEY"],
+      "bins": ["cloud"],
+      "capabilities": ["prismer.skill.draft.create"]
+    }
+  },
+  "inputs": [
+    { "name": "sourceKind", "type": "enum<inline-spec|doc-url|code-source|service-endpoint>", "required": true, "description": "Source kind chosen by the user or inferred from the slash command" },
+    { "name": "intent", "type": "string", "required": true, "description": "Free-form description of what the produced skill should do; ≥ 50 quality units (ASCII=1, non-ASCII=2)" },
+    { "name": "sourceRefs", "type": "array<string>", "required": false, "description": "URLs / repo paths / endpoint URLs depending on sourceKind" }
+  ],
+  "outputs": [
+    { "name": "draftId", "type": "string", "required": true, "description": "IMSkill row id (status=draft)" },
+    { "name": "slug", "type": "string", "required": true },
+    { "name": "manifestRevision", "type": "string", "required": true, "description": "Merkle root of manifest files[]" },
+    { "name": "reviewTaskId", "type": "string", "required": true, "description": "IMTask id (capability=skill-review)" }
+  ],
+  "sampleTasks": [
+    {
+      "title": "Author a skill from an OpenClaw documentation URL",
+      "prompt": "/skill new --from doc https://docs.openclaw.ai/skills/index — make a skill that scrapes the OpenClaw tools catalog and bundles it as a reference",
+      "expectedArtifacts": [
+        "SKILL.md with frontmatter (name, description, license, compatibility)",
+        "skill.json with provenance.sourceKind='doc-url'",
+        "references/openclaw-skills.md compressed reference"
+      ],
+      "acceptanceCriteria": [
+        "IMSkill row exists with status=draft and slug matches user-provided value",
+        "manifest contains a SKILL.md and a skill.json (located by basename, any order — the package gate does NOT require them at positions [0]/[1])",
+        "GET /api/im/skills/search?q=<slug> returns 0 rows (draft filter applies)"
+      ]
+    }
+  ],
+  "security": {
+    "dataAccess": [
+      "workspace-assets",
+      "external-network"
+    ],
+    "humanApprovalRequiredFor": [
+      "code-source fetches outside PRISMER_WORKSPACE_ROOT or $HOME/.prismer/agents/<agentId>/scratch",
+      "service-endpoint probes against non-public hosts"
+    ]
+  },
+  "provenance": {
+    "sourceKind": "inline-spec",
+    "sourceRefs": [
+      "docs/release201/07-skill-authoring-engine.md",
+      "sdk/prismer-cloud/built-in-skills/skill-creator/SKILL.md"
+    ],
+    "authoredBy": "prismer-platform",
+    "authoredAt": "2026-05-26T00:00:00Z"
+  }
+}

package/built-in-skills/skill-builder/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: skill-builder
+scope: common
+description: Low-level helper for the DIRECT-PUBLISH tier of skill authoring — it is NOT the entry point for creating skills. To make/build/author/package a skill, use `skill-creator` (the single canonical skill author). This page only documents `skill-creator`'s direct-publish tier (`cloud skill create --install`, or the portable `scripts/ingest.mjs` ingest fallback) and the SS-01 bundle/ingest format. Do NOT route here when the user wants to create a skill — route to skill-creator.
+license: MIT
+compatibility:
+  - prismer-sdk
+  - hermes
+  - claude-code
+  - codex
+metadata:
+  category: authoring
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - WebFetch
+---
+
+# Skill Builder — the direct-publish tier of `skill-creator`
+
+> **Not an authoring entry point.** Creating, editing, or packaging a skill is
+> the job of **`skill-creator`** — the single canonical skill author. This page
+> only exists to document one of skill-creator's two publish trust tiers
+> (**direct publish**) plus the low-level `scripts/ingest.mjs` ingest helper.
+> If the user says "turn this into a skill" / "make a skill" / "package this
+> workflow", **use `skill-creator`**, not this.
+
+## Where this fits
+
+`skill-creator` drives the full lifecycle author→validate→test→package→publish.
+At the publish step there are two trust tiers ([[16-skill-role-authoring-as-agent-capability]] §5.3):
+
+- **Direct create (default)** — `cloud skill create ./<dir> [--install]` →
+  `status=active`, `publishScope=workspace` (**private**, installable — NOT public).
+  Marketplace publish is the separate `cloud skill publish`. This page.
+- **Draft-gated (explicit)** — `cloud skill draft create` → `status=draft`,
+  Studio Authoring promotes it. Documented under `skill-authoring`.
+
+Both tiers are reached from inside `skill-creator`. Neither is a separate
+"author a skill" skill — they're publish-verb choices.
+
+## SS-01 bundle format (reference)
+
+The canonical contract is **SS-01** (`public/docs/Standardization/01-skill-standard.md`).
+A skill is a directory named exactly `<slug>/`:
+
+```
+<slug>/
+├── SKILL.md        # required — frontmatter + body (injected into agent prompt)
+├── scripts/        # optional — runnable code
+├── references/     # optional — docs loaded as needed
+└── assets/         # optional — templates / images
+```
+
+`SKILL.md` frontmatter (SS-01 §3.2 — aligns with agentskills.io):
+
+```markdown
+---
+name: <slug>                 # must equal the dir name
+scope: common                # common | persistence | coding
+description: <one line; what it does AND when to trigger>
+license: MIT
+compatibility:
+  - prismer-sdk
+  - claude-code
+metadata:
+  category: <category>
+---
+
+# <Title>
+<body: imperative instructions, progressive disclosure, ≤500 lines>
+```
+
+`scope` buckets the skill for per-role native-skill filtering (release203/13):
+`common` (default, any agent) / `persistence` (memory/state) / `coding`
+(code-agent targets). It lives inside SKILL.md and round-trips automatically.
+
+## Direct-publish ingest
+
+The preferred path is the `cloud skill create` CLI (driven from `skill-creator`):
+
+```bash
+cloud skill create ./<slug> --install --json
+# POST /api/im/skills (+ install). Reads api key from prismer config.
+```
+
+When the `cloud` CLI binary is not on PATH (CI / SDK-only environments), use the
+bundled zero-dependency ingest script:
+
+```bash
+PRISMER_API_KEY=sk-prismer-...  PRISMER_CLOUD_BASE=http://127.0.0.1:3000 \
+  node scripts/ingest.mjs ./<slug> --install
+```
+
+`scripts/ingest.mjs` parses the SKILL.md frontmatter, collects every bundle file
+into an SS-01 `contentManifest`, computes the merkle `contentManifestRevision`
+with the exact server algorithm
+(`sha256(sorted("<path>:<sha256(bytes)>").join("\n"))`), `POST`s to
+`/api/im/skills` with `Authorization: Bearer $PRISMER_API_KEY`, and on
+`--install` follows with `POST /api/im/skills/:slug/install`. Both paths only
+need an **API key** (`authMiddleware` accepts `sk-prismer-*` as a Bearer token).
+
+If `cloud` is present but `skill create` is missing, that is CLI version skew,
+not permission to bypass the lifecycle. Report `cloud --version` and use the
+current repository build. The script fallback is not a workaround for a
+partially stale CLI because its auth/scope/readback behavior is precisely what
+the authoring flow needs to verify.
+
+The bundle reader accepts YAML literal/folded block scalars in frontmatter, so
+upstream `description: |` / `description: >` content must not be rewritten to a
+single line merely for ingest. The 50-unit description quality floor counts
+non-ASCII code points as two units, avoiding meaningless padding of concise CJK
+descriptions while retaining the English quality bar.
+
+> **The catalog slug is server-assigned**, not your frontmatter `name`. Community
+> creates are prefixed (`weather-lookup` → `community-weather-lookup`). Use the
+> slug returned in the 201 response for install, `cloud skill show`, and a role's
+> `requiredSkills`. A `409` means the slug already exists — pick a new name;
+> there is no in-place overwrite.
+
+## After publishing: managing a live skill
+
+Publishing is not a one-way door. Every verb below is a `cloud skill` subcommand
+(the `prismer skill` daemon CLI has the identical set).
+
+**The one fact everything else follows from: an installed skill is a LIVE
+REFERENCE, not a snapshot.** `im_agent_skills` stores only `skillId` +
+`installedRevision`; every daemon sync re-reads the catalog row's current
+`contentManifest`. So **editing a published skill's content propagates to every
+agent that has it installed** — no re-install, no opt-in. That is why the server
+rejects a content edit with `422 changelog_required` unless you pass
+`--changelog "<what changed>"`: consumers are entitled to know what changed under
+them. Metadata-only edits (description / icon / tags) need no changelog.
+
+| Verb                                        | What it does                                                                            | Effect on people already using it                                        |
+| ------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `cloud skill delist <slug> [--reason ...]`  | Removes it from Marketplace search. Content, installs, syncs all keep working.          | **None.** They keep the skill and keep receiving content updates.        |
+| `cloud skill relist <slug>`                 | Puts it back (re-runs the publish gate, so an admin takedown still blocks it).          | None.                                                                     |
+| `cloud skill deprecate <slug> --reason <r> [--successor <slug>]` | Marks it superseded. It stays installable — new installs get a **warning, not a block**. | None; they see the reason + successor.                                    |
+| `cloud skill undeprecate <slug>`            | Clears the mark.                                                                        | None.                                                                     |
+| `cloud skill archive <slug> [--confirm]`    | **Retires it. UNBINDS every agent that has it installed.**                              | **Destructive.** With live consumers the server refuses until `--confirm`. |
+| `cloud skill transfer <slug> --to <imUserId>` | Offers ownership. Two-phase — nothing moves until the recipient runs `transfer-accept`. | None. (`transfer-abort` withdraws the offer.)                             |
+| `cloud skill published`                     | Your publication inventory: slug, listing state, **consumer count**.                    | —                                                                         |
+
+**delist vs archive is the distinction that matters.** Delist is a visibility
+flip: it hides the skill from the Marketplace and nothing else. Archive retires
+it and unbinds every installed agent — that is why it has a consumer door:
+
+```bash
+$ cloud skill archive weather-lookup
+Error: 3 agents are still using this skill — archiving unbinds them.
+       Re-run with --confirm to archive anyway: cloud skill archive weather-lookup --confirm
+```
+
+Reach for delist when you no longer want new users; reach for archive only when
+you intend to cut existing ones off. Deprecate is the polite middle: it keeps
+working and points people at the successor. There is **no hard delete** — a
+published skill is never destroyed, only moved between these states.
+
+Admin takedown is a separate, admin-only action. A taken-down skill cannot be
+re-listed by its owner (`cloud skill relist` returns "was taken down by an
+administrator"); an admin must reinstate it first.
+
+## Reference
+
+- The skill author (use this): `built-in-skills/skill-creator/SKILL.md`
+- Bundle + catalog contract: `public/docs/Standardization/01-skill-standard.md` (SS-01)
+- Draft-gated tier: `built-in-skills/skill-authoring/SKILL.md`
+- Role side: `built-in-skills/role-builder/SKILL.md` (SS-02)
+- Post-publish endpoint contract: `docs/api/publish-lifecycle.md` (product204/21)

package/built-in-skills/skill-builder/scripts/ingest.mjs

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+// skill-builder ingest — material→bundle→live catalog, via SDK + API key.
+//
+// Zero runtime dependencies (Node ≥18 built-ins only). Reads a SS-01 skill
+// bundle directory, parses SKILL.md frontmatter, builds an SS-01 contentManifest
+// with a server-matching merkle revision, and POSTs it to the real catalog
+// endpoint authenticated with an `sk-prismer-*` API key.
+//
+// Usage:
+//   PRISMER_API_KEY=sk-prismer-... [PRISMER_CLOUD_BASE=http://127.0.0.1:3000] \
+//     node scripts/ingest.mjs <bundle-dir> [--install] [--agent <imUserId>] [--json]
+//
+// Env:
+//   PRISMER_API_KEY   (required) Bearer token; admin not required for skill create.
+//   PRISMER_CLOUD_BASE (default http://127.0.0.1:3000) cloud base URL.
+
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+function die(msg, code = 1) {
+  console.error(`[skill-builder] ✗ ${msg}`);
+  process.exit(code);
+}
+
+const args = process.argv.slice(2);
+const secretOptions = new Set(['--api-key', '--token', '--jwt', '--secret', '--password']);
+let bundleDir;
+let wantInstall = false;
+let asJson = false;
+let agentId;
+for (let index = 0; index < args.length; index += 1) {
+  const arg = args[index];
+  const equalsAt = arg.indexOf('=');
+  const option = equalsAt === -1 ? arg : arg.slice(0, equalsAt);
+  if (secretOptions.has(option)) {
+    die(`${option} is forbidden; credentials must come from environment variables`, 2);
+  }
+  if (arg === '--install') {
+    wantInstall = true;
+    continue;
+  }
+  if (arg === '--json') {
+    asJson = true;
+    continue;
+  }
+  if (arg === '--agent') {
+    const value = args[index + 1];
+    if (!value || value.startsWith('--')) die('--agent requires an imUserId', 2);
+    agentId = value;
+    index += 1;
+    continue;
+  }
+  if (arg.startsWith('--')) die(`unknown argument at position ${index + 1}`, 2);
+  if (bundleDir) die('only one bundle directory may be supplied', 2);
+  bundleDir = arg;
+}
+
+const API_KEY = process.env.PRISMER_API_KEY;
+const BASE = (process.env.PRISMER_CLOUD_BASE || 'http://127.0.0.1:3000').replace(/\/$/, '');
+
+if (!bundleDir) die('usage: node ingest.mjs <bundle-dir> [--install] [--agent <imUserId>] [--json]');
+if (!API_KEY) die('PRISMER_API_KEY env is required (sk-prismer-*)');
+let target;
+try {
+  target = new URL(BASE);
+} catch {
+  die('PRISMER_CLOUD_BASE must be a valid URL', 2);
+}
+if (
+  !['http:', 'https:'].includes(target.protocol) ||
+  target.username ||
+  target.password ||
+  target.search ||
+  target.hash
+) {
+  die('PRISMER_CLOUD_BASE must be a plain http(s) origin without credentials, query, or hash', 2);
+}
+const isLocalTarget = ['localhost', '127.0.0.1', '::1', 'host.docker.internal'].includes(target.hostname);
+const allowRemote = ['1', 'true', 'yes'].includes(String(process.env.PRISMER_ALLOW_REMOTE_WRITE).toLowerCase());
+if (!isLocalTarget && !allowRemote) {
+  die('remote mutation is blocked; set PRISMER_ALLOW_REMOTE_WRITE=1 after confirming the target environment', 2);
+}
+
+// ── collect bundle files (SS-01 §3.1 — exclude dotfiles + LICENSE*) ──────────
+const EXCLUDED = new Set(['.DS_Store', 'Thumbs.db', 'LICENSE', 'LICENSE.txt', 'LICENSE.md']);
+function collect(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+    const abs = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...collect(abs));
+    else if (!EXCLUDED.has(entry.name)) out.push(abs);
+  }
+  return out;
+}
+
+let bundleStat;
+try {
+  bundleStat = statSync(bundleDir);
+} catch {
+  die(`bundle dir not found: ${bundleDir}`);
+}
+if (!bundleStat.isDirectory()) die(`not a directory: ${bundleDir}`);
+
+const absFiles = collect(bundleDir).sort();
+const toPosix = (abs) => relative(bundleDir, abs).split(sep).join('/');
+const files = absFiles.map((abs) => ({ path: toPosix(abs), bytes: readFileSync(abs) }));
+
+const skillMd = files.find((f) => f.path === 'SKILL.md');
+if (!skillMd) die('SKILL.md not found at bundle root');
+
+// ── parse frontmatter (minimal YAML — flat keys, lists, block scalars) ────
+function parseFrontmatter(text) {
+  const m = text.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!m) return { fm: {}, body: text };
+  const fm = {};
+  let key = null;
+  const lines = m[1].split('\n');
+  for (let index = 0; index < lines.length; index += 1) {
+    const rawLine = lines[index];
+    const line = rawLine.replace(/\s+$/, '');
+    if (!line.trim()) continue;
+    const listItem = line.match(/^\s+-\s+(.*)$/);
+    if (listItem && key) {
+      (Array.isArray(fm[key]) ? fm[key] : (fm[key] = [])).push(stripQuotes(listItem[1]));
+      continue;
+    }
+    const kv = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (kv) {
+      key = kv[1];
+      const val = kv[2];
+      const block = /^([|>])([+-])?$/.exec(val.trim());
+      if (block) {
+        const body = [];
+        let next = index + 1;
+        for (; next < lines.length; next += 1) {
+          const candidate = lines[next];
+          if (candidate.trim() && !/^\s+/.test(candidate)) break;
+          body.push(candidate);
+        }
+        const indents = body
+          .filter((candidate) => candidate.trim())
+          .map((candidate) => /^\s*/.exec(candidate)?.[0].length ?? 0);
+        const indent = indents.length > 0 ? Math.min(...indents) : 0;
+        const unindented = body.map((candidate) => candidate.slice(Math.min(indent, candidate.length)));
+        let parsed =
+          block[1] === '>'
+            ? unindented.reduce((out, candidate, bodyIndex) => {
+                if (bodyIndex === 0) return candidate;
+                const previous = unindented[bodyIndex - 1] ?? '';
+                return out + (previous === '' || candidate === '' ? '\n' : ' ') + candidate;
+              }, '')
+            : unindented.join('\n');
+        if (block[2] === '-') parsed = parsed.replace(/\n+$/, '');
+        else if (block[2] !== '+') parsed = parsed.replace(/\n*$/, '\n');
+        fm[key] = parsed;
+        index = next - 1;
+      } else if (val === '')
+        fm[key] = []; // expect a list or nested block below
+      else fm[key] = stripQuotes(val);
+    }
+  }
+  return { fm, body: text.slice(m[0].length) };
+}
+const stripQuotes = (s) => s.replace(/^["']|["']$/g, '').trim();
+
+const { fm } = parseFrontmatter(skillMd.bytes.toString('utf8'));
+const name = fm.name;
+if (!name || !/^[a-z][a-z0-9-]*$/.test(name)) die(`frontmatter.name invalid or missing: ${name}`);
+if (!fm.description || fm.description === '|' || fm.description === '>') {
+  die('frontmatter.description is required');
+}
+
+// category: prefer metadata.category; the nested `metadata:` block isn't parsed
+// by the flat reader, so allow a top-level `category:` too, else default.
+const category = fm.category || 'general';
+const compatibility = Array.isArray(fm.compatibility)
+  ? fm.compatibility
+  : fm.compatibility
+    ? [fm.compatibility]
+    : undefined;
+
+// ── build SS-01 manifest (merkle matches src/im/skills/manifest.ts) ──────────
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+const manifest = files.map((f) => ({
+  path: f.path,
+  size: f.bytes.byteLength,
+  sha256: sha256(f.bytes),
+  inline: true,
+  content: f.bytes.toString('base64'),
+}));
+const revision = sha256(
+  [...manifest]
+    .sort((a, b) => a.path.localeCompare(b.path))
+    .map((f) => `${f.path}:${f.sha256}`)
+    .join('\n'),
+);
+
+const isMultiFile = files.length > 1;
+const createBody = {
+  name,
+  description: fm.description,
+  category,
+  ...(fm.license ? { license: fm.license } : {}),
+  ...(compatibility ? { compatibility } : {}),
+  // Single-file → send plain content (server wraps). Multi-file → send manifest.
+  content: skillMd.bytes.toString('utf8'),
+  ...(isMultiFile ? { contentManifest: manifest, contentManifestRevision: revision } : {}),
+};
+
+async function api(method, path, body) {
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${API_KEY}` },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+  });
+  let json = null;
+  try {
+    json = await res.json();
+  } catch {
+    /* non-JSON */
+  }
+  return { status: res.status, json };
+}
+
+(async () => {
+  const created = await api('POST', '/api/im/skills', createBody);
+  if (created.status === 409) die(`slug "${name}" already exists (409). Use update or pick a new name.`, 2);
+  if (created.status !== 201 || !created.json?.ok) {
+    die(`create failed (HTTP ${created.status}): ${created.json?.error || 'unknown error'}`);
+  }
+  const skill = created.json.data;
+  const result = {
+    id: skill.id,
+    slug: skill.slug,
+    rev: revision,
+    files: files.length,
+    installed: false,
+  };
+
+  if (wantInstall) {
+    const path = agentId
+      ? `/api/im/agents/${encodeURIComponent(agentId)}/skills`
+      : `/api/im/skills/${encodeURIComponent(skill.slug)}/install`;
+    const body = agentId ? { skillId: skill.slug } : {};
+    const inst = await api('POST', path, body);
+    if (inst.status >= 200 && inst.status < 300 && inst.json?.ok !== false) {
+      result.installed = agentId || true;
+    } else {
+      result.installError = `HTTP ${inst.status}: ${inst.json?.error || 'install failed'}`;
+    }
+  }
+
+  if (asJson) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`[skill-builder] ✓ ingested ${result.slug}`);
+    console.log(`  id:        ${result.id}`);
+    console.log(`  rev:       ${result.rev}`);
+    console.log(`  files:     ${result.files}`);
+    console.log(`  installed: ${result.installed}${result.installError ? ` (${result.installError})` : ''}`);
+    console.log(`  verify:    cloud skill show ${result.slug} --content`);
+  }
+})().catch((err) => die(err?.message || String(err)));