@prismer/runtime 2.0.8 → 2.2.55

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

@@ -1,124 +1,134 @@
 ---
 name: skill-authoring
-description: Generate Prismer-compliant skill drafts from user intent, documentation URLs, existing code, or service endpoints. Use whenever the user says "make this a skill", "package this workflow", "create a skill for X", or wants to capture a repeatable workflow into a reusable artifact. Outputs a multi-file manifest (SKILL.md + skill.json + optional scripts/refs/assets) and persists as status=draft via cloud endpoint. Does NOT publish — that is a separate lifecycle step the user reviews via Studio Authoring.
+scope: common
+description: Low-level helper for the DRAFT-GATED (review) tier of skill authoring — it is NOT the entry point for creating skills. To make/build/author a skill, use `skill-creator` (the single canonical skill author). This page only documents skill-creator's draft tier — generating a `status=draft` skill via `POST /api/im/skills/draft` (`cloud skill draft create`) for human review in Studio Authoring, plus the skill.json + sampleTasks/acceptanceCriteria test contract. Do NOT route here when the user wants to create a skill — route to skill-creator and add `--draft` only when human review is required.
 license: MIT
 compatibility:
   - prismer-sdk
   - hermes
-  - openclaw
   - claude-code
   - codex
 ---
 
-# Skill Authoring (Prismer)
-
-You generate Prismer-standard skill drafts. You do NOT publish — that's a separate
-lifecycle step the user reviews via Studio Authoring (`/evolution → Studio → Authoring`).
-
-## Pipeline
-
-1. **Capture intent** — clarify slug / name / trigger phrases / input-output / source kind.
-   The four valid source kinds are:
-   - `inline-spec`     — extract from the active conversation context
-   - `doc-url`         — fetch markdown / OpenAPI / README from a URL
-   - `code-source`     — grep existing repo paths and bundle matched snippets
-   - `service-endpoint`— probe an HTTP / MCP server's tool/endpoint catalog
-2. **Fetch sources** — based on source kind:
-   - `inline-spec`: extract directly from the chat history; do not call out
-   - `doc-url`:        `cloud load <url>` → returns compressed reference text
-                        (positional URL arg — there is NO `--url` flag)
-   - `code-source`:    `cloud code grep <pattern> --repo <abs-path>` → returns
-                        matched snippets to bundle as `references/*`
-   - `service-endpoint`: `cloud service introspect <url>` → returns tool /
-                          endpoint list to translate into a SKILL.md workflow
-3. **Compose manifest v1** — write:
-   - `SKILL.md` (frontmatter `name`/`description`/`license`/`compatibility` +
-     a body that follows Anthropic skill-creator's progressive-disclosure pattern)
-   - `skill.json` (structured `SkillPackageSpec` — see release201/07 §2.6)
-   - Optional `scripts/`, `references/`, `assets/`
-4. **Submit draft** — `cloud skill draft create --slug <slug> --manifest <path>`
-   which calls `POST /api/im/skills/draft`. The cloud server runs the 7 validation
-   gates and returns `{ id, slug, manifestRevision, reviewTaskId }` on success.
-5. **Report draft id** — surface the draft id back to the user; do NOT auto-publish.
-
-## Scenario 1 — API doc / URL → skill + callable script + auto tests
-
-This is the canonical, quantifiable path (release201/24). When the user gives
-you an API document, an OpenAPI/Swagger spec, or a doc URL and asks to "make
-this a skill", produce a draft that can be VERIFIED by real dispatch — not just
-prose. Generate ALL of:
-
-1. **`SKILL.md`** — workflow describing when/how to call the API, with the
-   concrete endpoints, auth, and the script entrypoint.
-2. **`scripts/call-api.*`** — a real, runnable script (Node `.ts`/`.mjs`, or
-   `.sh` using curl) that performs the API call. Read inputs from argv / env;
-   print the result to stdout. This is what the eval session actually exercises.
-3. **`skill.json`** — the `SkillPackageSpec` with:
-   - `runtime.kind = 'inline-script'` (or `'http-endpoint'`), `runtime.requires`
-     declaring `bins`/`env` the script needs (e.g. `env: ["EXAMPLE_API_KEY"]`).
-   - `inputs` / `outputs` describing the call contract.
-   - **`sampleTasks[]`** — at least 2 concrete tasks. EACH MUST have
-     `acceptanceCriteria[]` written as substrings/regex that the dispatch
-     OUTPUT must contain (e.g. `"\"status\":\\s*200"`, `"results"`). These ARE
-     the auto-generated mock tests — the daemon scorer matches them against the
-     real dispatch output (release201/24 §2.1). A sampleTask with no
-     acceptanceCriteria is scored `inconclusive` (NOT a pass), so always write
-     them.
-4. **`references/<api>.md`** — the compressed `cloud load <url>` /
-   `cloud service introspect <url>` output, so the workflow is grounded.
-
-Quantifiable acceptance: the skill is "good" when its eval run pass-rate (real
-dispatch of each sampleTask, scored against acceptanceCriteria) meets the
-lifecycle threshold. Write criteria that are tight enough to catch a broken
-call but not so tight they depend on volatile data.
+# Skill Authoring — the draft-gated tier of `skill-creator`
 
-> Derive acceptanceCriteria from the spec: required response fields, status
-> codes, schema keys. If the spec lacks examples, add a criterion asserting the
-> script exits 0 and emits non-empty JSON, plus a field-presence check.
+> **Not an authoring entry point.** Creating or editing a skill is the job of
+> **`skill-creator`** — the single canonical skill author. This page only
+> documents one of skill-creator's two publish trust tiers (**draft-gated**),
+> for the case where a skill must be reviewed by a human before it goes live.
+> If the user says "make this a skill" / "create a skill for X", **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):
 
-## Boundaries
+- **Direct create (default)** — `cloud skill create ./<dir>` → `status=active`,
+  `publishScope=workspace` (**private**, installable — NOT the public marketplace).
+  Putting it in the marketplace is a separate `cloud skill publish`. Under `skill-builder`.
+- **Draft-gated (explicit, this page)** — `cloud skill draft create` →
+  `status=draft`, Studio Authoring reviews and promotes it. Opt into this **only
+  when human review is required** — the default is direct publish (decision 4,
+  locked 2026-06-24).
 
-- DO NOT call `POST /api/im/skills` directly — it bypasses draft state
-- DO NOT modify existing non-draft skills (use `skill-creator` reference if the
-  user asks "edit existing skill")
-- DO NOT trigger publish / share — the user reviews drafts in Studio Authoring
-- Reference Anthropic skill-creator at `/built-in-skills/skill-creator/SKILL.md`
-  for "how to write a good SKILL.md" patterns (progressive disclosure, allowed
-  tool surface, etc.). Treat it as documentation, not as an executor.
+Both tiers are reached from inside `skill-creator`; this is a publish-verb
+choice, not a separate skill to author in.
 
-## Quality gates (self-check before submit)
+## Draft submission (the review-gated path)
 
-The cloud server runs the 7 gates below at `createDraft` time and rejects with
-HTTP 400 on any blocking failure. Run the same checks locally before POSTing:
+When the workflow requires human review before a skill is live, submit a draft
+instead of publishing directly:
+
+```bash
+cloud skill draft create ./<bundle-dir>   # optional: --workspace-id <id> --json
+# → POST /api/im/skills/draft. Cloud reads the directory, runs the 7 validation
+#   gates, and returns { id, slug, status: draft }. Does NOT publish.
+```
+
+> ⚠️ **`<bundle-dir>` is a directory** holding `SKILL.md` + `skill.json` (+ an
+> optional `scripts/`). The CLI reads and packages the directory on every run, so
+> edits on disk take effect immediately — there is no separate manifest to
+> regenerate. There is **no** `--slug` / `--manifest` flag; the slug is taken from
+> the SKILL.md frontmatter `name`.
+
+The draft lands in `status=draft`; the workspace owner reviews and promotes it
+via Studio Authoring (`/evolution → Studio → Authoring`). Do **not** auto-publish
+or chain into install — promotion is the owner's call.
+
+> Do NOT call `POST /api/im/skills` (direct publish) when the intent is review-gated —
+> that bypasses the draft state. Use `--draft` deliberately.
+
+## `skill.json` — where security + the test contract live
+
+**Read this first — it is the #1 draft-tier gotcha.** The bundle must contain a
+`skill.json` alongside `SKILL.md` (cloud locates each file by name, so a
+`scripts/` dir sorted in between is fine). Cloud reads `security` and the test
+contract from **`skill.json`**, and **NEVER** from the `SKILL.md` YAML
+frontmatter. If you put `security:` / `dataAccess:` in the
+SKILL.md frontmatter, gate 5 still fails with "security.dataAccess must be
+non-empty" no matter how you format the YAML — it is reading a different file.
+
+### `security` (blocking — gate 5)
+
+```json
+{
+  "schemaVersion": 1,
+  "slug": "<slug>",
+  "security": {
+    "dataAccess": ["workspace-assets"],
+    "humanApprovalRequiredFor": []
+  }
+}
+```
+
+- **`security.dataAccess`** — non-empty array. Scopes: `workspace-assets` |
+  `memory` | `external-network` | `secrets` | `filesystem`.
+- **`security.humanApprovalRequiredFor`** — **required non-empty IF** `dataAccess`
+  contains a **sensitive** scope (`external-network`, `secrets`, `filesystem`).
+  List the actions needing human approval (e.g. `["filesystem-write"]`).
+- **Least privilege:** if the skill only reads env + prints (no arbitrary user
+  files), declare `["memory"]` — a non-sensitive scope — and
+  `humanApprovalRequiredFor` may stay empty. Only reach for `filesystem` when the
+  skill genuinely reads/writes user files, and then you must also declare
+  approval.
+
+### test contract (drives `cloud skill test`)
+
+The same `skill.json` also carries the VERIFICATION contract exercised by
+`cloud skill test --agent` in lifecycle step ③:
+
+- `runtime.kind` = `'inline-script'` (or `'http-endpoint'`), `runtime.requires`
+  declaring `bins`/`env` the script needs.
+- `inputs` / `outputs` describing the call contract.
+- **`sampleTasks[]`** — at least 2 concrete tasks. EACH MUST have
+  `acceptanceCriteria[]` written as substrings/regex the dispatch OUTPUT must
+  contain (e.g. `"\"status\":\\s*200"`, `"results"`). These are the auto-scored
+  tests: `cloud skill test` dispatches each sampleTask to a real agent and
+  matches its output against the criteria. A sampleTask with no
+  acceptanceCriteria scores `inconclusive` (NOT a pass), so always write them.
+
+> Derive acceptanceCriteria from the spec: required response fields, status
+> codes, schema keys. Tight enough to catch a broken call, not so tight they
+> depend on volatile data.
+
+## Draft validation gates (self-check before submit)
+
+The cloud server runs these at `createDraft` time and rejects with HTTP 400 on a
+blocking failure. Run the same checks locally first (or just `cloud skill validate ./<dir>`):
 
 | Gate           | Check                                                            | Blocking |
 |----------------|------------------------------------------------------------------|----------|
 | `manifest`     | files[] complete; merkle root reproducible                       | yes      |
-| `frontmatter`  | `name` matches `^[a-z][a-z0-9-]*$`; description ≥ 50 chars       | yes      |
-| `package`      | SKILL.md is files[0]; skill.json is files[1]                     | yes      |
+| `frontmatter`  | `name` matches `^[a-z][a-z0-9-]*$`; description ≥ 50 quality units (ASCII=1, non-ASCII=2); YAML `|`/`>` supported | yes      |
+| `package`      | bundle contains SKILL.md + skill.json (located by name)          | yes      |
 | `requires`     | runtime.requires declares env/bins/python/node explicitly        | warn     |
-| `security`     | security.dataAccess non-empty; sensitive scopes require approval | yes      |
+| `security`     | **skill.json** security.dataAccess non-empty; sensitive scopes (external-network/secrets/filesystem) require security.humanApprovalRequiredFor. NOT read from SKILL.md frontmatter. | yes      |
 | `sample`       | at least 1 sampleTask + 1 acceptance criterion                   | warn     |
 | `runtime`      | sandbox executes sample task                                     | deferred |
 
-- `name` matches `^[a-z][a-z0-9-]*$`
-- `description` ≥ 50 chars, contains trigger context ("Use when...")
-- SKILL.md body ≤ 500 lines (progressive disclosure)
-- All scripts/refs/assets paths exist in manifest files[] array
-- Merkle root computed correctly:
-  `sha256(join("\n", sorted(files, by=path).map(f => path + ":" + sha256)))`
-
-## Output contract
-
-After a successful submit, return to the user:
-
-```
-Draft submitted.
-  id:               <skill id>
-  slug:             <slug>
-  manifest revision <merkle>
-  review task:      <task id>  (capability=skill-review, assignee=workspace owner)
-  next step:        Open in Studio Authoring → review → promote to eval (release201/08)
-```
+## Reference
 
-Do NOT chain into install / publish; lifecycle is the workspace owner's call.
+- The skill author (use this): `built-in-skills/skill-creator/SKILL.md`
+- Direct-publish tier: `built-in-skills/skill-builder/SKILL.md`
+- Bundle + catalog contract: `public/docs/Standardization/01-skill-standard.md` (SS-01)

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

@@ -17,7 +17,7 @@
     "kind": "text-workflow",
     "executableJson": {
       "kind": "cli",
-      "command": "cloud skill draft create --slug {{slug}} --manifest {{manifest_path}}"
+      "command": "cloud skill draft create {{bundle_dir}}"
     },
     "requires": {
       "env": ["PRISMER_API_KEY"],
@@ -27,7 +27,7 @@
   },
   "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 chars" },
+    { "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": [
@@ -47,7 +47,7 @@
       ],
       "acceptanceCriteria": [
         "IMSkill row exists with status=draft and slug matches user-provided value",
-        "manifest files[0].path === 'SKILL.md' and files[1].path === 'skill.json'",
+        "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)"
       ]
     }

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)