npm - @prismer/runtime - Versions diffs - 2.0.6 → 2.0.8 - Mend

@prismer/runtime 2.0.6 → 2.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (207) hide show

package/built-in-skills/memory-curation/SKILL.md ADDED Viewed

@@ -0,0 +1,135 @@
+---
+name: memory-curation
+description: |
+  When you have read / processed a workspace asset in this session and learned something
+  durable about it, write a memory page so future sessions benefit. Maintain the workspace
+  wiki's hierarchical structure as it grows.
+applies_to: [hermes, claude-code, openclaw, codex]
+version: 1
+---
+# Memory Curation Skill
+You have access to a workspace memory layer. Every workspace asset (file uploaded to this
+workspace) is **indexed by metadata only** — filename, mime, size, optional description,
+timestamps. The system does **not** pre-process file contents.
+To inspect assets, use bounded asset tools:
+- `prismer.asset.search` to find candidate files
+- `prismer.asset.describe` before reading bytes
+- `prismer.asset.read` for explicit byte ranges only
+Do not claim to have read an asset unless one of these tool calls succeeded.
+Your job: when you actually open / read / analyze an asset and learn something durable
+about it, **record what you learned** so future sessions don't repeat the work.
+## When to write a memory page
+Write a memory page after handling an asset if and only if **all** of these are true:
+1. You actually read the asset content (not just listed it).
+2. You produced an analysis, decision, or summary that is non-trivial — not "this file is a
+   CSV with 1000 rows" but "this CSV is Q4 sales data with revenue collapse in region APAC".
+3. The conclusion is **durable** — it will still matter weeks from now.
+4. The conclusion is **not derivable** from the asset metadata alone or from re-reading
+   the asset directly.
+Do **not** write a memory page for:
+- Files you only listed / saw in a directory listing
+- Trivial summaries ("this is a PDF about marketing")
+- Conversation context that belongs in the session, not in long-term memory
+- Process artifacts: build logs, temporary downloads, cache files, scratch outputs
+- Anything the user explicitly asked you not to remember
+## What to write
+Format: short Markdown page (typical 200-1000 words). Required structure:
+```markdown
+# <Short descriptive title>
+**Source:** [original-filename.ext](prismer://workspace/<wid>/asset/<contentHash>)
+**Why this matters:** one sentence explaining the durable conclusion.
+<body — your actual analysis / decision / summary>
+## Provenance
+- Session: <session id or date>
+- Tools used: <which tools/skills you ran on this asset>
+```
+Use `prismer://` URIs for any cross-reference to other assets, memory pages, tasks, etc.
+This is the wiki link form — agents in future sessions navigate by following these.
+## Where to put it
+Path convention:
+```
+memory/<topic>/<source-slug>.md         ← leaf page about one source
+memory/<topic>/<source-slug>/<aspect>.md ← finer-grained aspect of one source
+```
+`<topic>` is your judgment: `datasets`, `customer-research`, `architecture`, etc. If you
+are uncertain, default to the asset's content kind (`datasets/` for tabular, `documents/`
+for text-heavy, etc.). The Dream consolidation phase will reorganize sub-optimal placements.
+## Index hygiene (important)
+The workspace has a top-level `INDEX.md` that points to memory pages. **Do not write
+directly into `INDEX.md`** — the system maintains it. Just write your page at the right
+path and the indexer will pick it up.
+If you notice the top-level INDEX already has >200 entries, **do not create a fresh
+top-level page**. Instead nest under an existing sub-index (e.g. `memory/datasets/INDEX.md`
+if it exists). The Dream phase will rebalance the hierarchy when it ticks.
+## Hub merging
+If you write a page about a topic and there is already a hub page for the same topic
+(check via `memory_search` before writing), **append to or update the existing hub**
+rather than creating a sibling. Hub merging at runtime keeps the wiki coherent and
+reduces work for the Dream phase later.
+## Deduplication
+Before writing, run `memory_search` with terms drawn from the asset content. If a memory
+page already contains the same conclusion, do nothing. If a memory page contains a
+**different** conclusion about the same source, do not silently overwrite — append a note
+or update with an explicit reason.
+## What the Dream phase will do for you
+You do not need to be perfect. The Dream phase runs periodically (typically idle ≥ 5
+minutes or session boundaries) and will:
+- Merge duplicates you missed
+- Cluster N pages about one topic into a new sub-hub
+- Mark stale pages (when the source asset was deleted or the conclusion contradicts a
+  newer page)
+- Prune low-signal pages that were never recalled and never linked
+- Enforce top-level INDEX size invariants
+This means: if you are uncertain whether a memory is worth writing, **err on the side of
+not writing**. Dream cannot reconstruct missing knowledge, but Dream can prune excess
+writes.
+## Anti-patterns
+- ❌ Writing one memory page per asset by default. Most assets are noise; only a fraction
+  yield durable knowledge.
+- ❌ Writing memory pages with content equal to a paste of the asset itself. Memory is
+  for **conclusions**, not raw content (the raw is already in the asset).
+- ❌ Writing memory pages for files the user said to ignore.
+- ❌ Editing `INDEX.md` directly.
+- ❌ Creating new top-level INDEX entries when one already exists for the topic.
+## Anti-pattern detector (rhetorical check)
+Before saving, ask yourself: "If I encounter this memory page 6 months from now in a
+different session, will it tell me something that re-reading the source asset would not?"
+If the answer is no, do not save.

package/built-in-skills/office-artifacts/SKILL.md ADDED Viewed

@@ -0,0 +1,198 @@
+---
+name: office-artifacts
+description: Generate real DOCX, PPTX, XLSX, PDF, CSV files using python-docx / python-pptx / openpyxl / reportlab by writing them into the dispatch artifacts dir, then explicitly deliver each one with `cloud deliver <abs-path>`. Use whenever the user asks for documents, slides, spreadsheets, reports, or PDFs.
+---
+# Office Artifacts
+Produce real binary office files (not markdown-as-PDF) by writing each
+one into the **artifacts dir** (`$PRISMER_ARTIFACTS_DIR` /
+`<artifacts_dir>` from `<execution_context>`). Prose-only completions are
+not valid.
+## Delivery contract — explicit, two steps (release202/09 P2)
+Delivery is **explicit**. Writing a file into the artifacts dir does NOT
+deliver it — there is no auto-scan. You must run **`cloud deliver`** for
+every file you want the user to receive.
+1. **Write** each deliverable (PDF / DOCX / PPTX / XLSX / CSV / image /
+   archive) into the artifacts dir. Drafts / intermediate scratch →
+   `$PRISMER_SCRATCH_DIR` (never delivered).
+2. **Deliver** it with the absolute path:
+   ```bash
+   cloud deliver "<artifacts_dir>/report.pdf"
+   ```
+   This attaches the file to **your current reply** (动作 A — it rides the
+   same message as your text summary). Run it once per file. The command
+   prints the `assetId` on success.
+- **`$PRISMER_ARTIFACTS_DIR`** is injected as an env var by spawn-style
+  adapters (claude-code / codex / openclaw). **Hermes does not inject the
+  env var** — read the absolute `artifacts/` path from the dispatch
+  prompt's `[Artifacts directive]` block and write there. Either way, pass
+  the **absolute path** to `cloud deliver`.
+- **Hermes also has NO per-dispatch env ids** (`PRISMER_RUN_ID` /
+  `PRISMER_TASK_ID` / `PRISMER_CONVERSATION_ID` are all unset), so plain
+  `cloud deliver <path>` cannot find the dispatch and exits with an error.
+  On hermes you MUST copy `<run_id>` (or `<task_id>`) and `<conversation_id>`
+  from `<execution_context>` and pass them as flags:
+  ```bash
+  # Hermes — ids come from <execution_context>, not env:
+  cloud deliver "<artifacts_dir>/report.pdf" --run-id "<run_id>" --conversation-id "<conversation_id>"
+  ```
+  Spawn-adapter agents (claude-code / codex) do **not** need these flags —
+  their env is already set; plain `cloud deliver "<abs-path>"` works there.
+- **Sending a file as its OWN message** (动作 B — separate from your reply,
+  e.g. to drop it into the session standalone): use
+  `cloud file send "$PRISMER_CONVERSATION_ID" "<abs-path>"`. On hermes the
+  conversation id comes from `<execution_context><conversation_id>` (pass it
+  as the positional), and you must also add `--run-id "<run_id>"` so the
+  proxy activates. Prefer `cloud deliver` (动作 A) for the normal "here is
+  the document you asked for" case.
+- **Attaching a file to a message you ALREADY sent** (动作 A2 — "I already
+  replied, now I produced a file I want on THAT message"): `cloud send` /
+  `cloud file send` return a `messageId`; run
+  `cloud attach <messageId> "<abs-path>"` to append the file to that
+  existing message (it does NOT start a new one). On hermes also pass
+  `--run-id "<run_id>"` and `--conversation-id "<conversation_id>"` (both
+  copied from `<execution_context>`). Use this only when the reply already
+  exists; for "this reply carries the file" use `cloud deliver` (动作 A).
+- **Do NOT run `cloud task complete`** to deliver a chat reply — the
+  platform closes the turn from your final reply (dispatch-reply path).
+- **`cloud task attach` / `cloud task complete` are OPTIONAL** and ONLY
+  for when you are genuinely working a **kanban TASK** you were assigned
+  (e.g. moving a board card to `review` / `done`). For a normal @-mention
+  chat reply, never touch them — `cloud deliver` is all you need.
+- **Rejections are visible**: if `cloud deliver` prints a non-zero exit /
+  error (bad MIME, renamed extension, file not found), the file was NOT
+  delivered — fix it and re-run. Do not claim a file you failed to deliver.
+## HARD RULE — never claim a file you didn't actually write
+Lie-guard (`src/im/ws/handler.ts`) **as of release201/30 §8 is
+warn-only telemetry**, not a destructive interceptor — the audit
+banner ("CEO 声明已生成文件但未真正落盘") that used to render in
+red is removed. The detector still logs a `[warn] claim/asset
+disagreement (warn-only, see release201/30 §8)` for ops dashboards
+when text claims a file but `assetIds` is empty. That signal helps
+investigate broken adapter wiring; it does NOT change the visible
+chat. Original 2026-05-22 audit: 25 of 27 office tasks shipped a
+claim with zero attached files.
+Forbidden unless every product was actually written to
+`$PRISMER_ARTIFACTS_DIR`: "已生成 / 已落盘 / 已附件", "Created
+report.pdf", "Attached the file", "Generated slides.pptx".
+Before claiming a file, **all** must hold:
+1. Generator import (`import docx` / `pptx` / `openpyxl` / `reportlab`)
+   succeeds.
+2. Script ran with exit 0 (no traceback).
+3. `ls -lah <artifacts_dir>` (the absolute path from `<execution_context>`)
+   shows the file, non-zero size.
+If (1)-(3) fail, your reply must start with `无法生成文件
+(reason)` / `Cannot produce file (reason)`.
+## Runtime baseline (release 201)
+Sandbox image bakes `python-docx`, `python-pptx`, `openpyxl`,
+`reportlab`, `pandas`, `pillow`, `numpy`, `imageio`, apt `file`. If an
+import fails at task time, fail with `module 'X' missing — rebuild
+sandbox image`. Do not `pip install` on the fly.
+## Resolving the output directory
+Your artifacts dir is delivered as an ABSOLUTE path in your prompt's
+`<execution_context>` block:
+```xml
+<execution_context …>
+  <artifacts_dir>/home/user/.prismer/workspaces/<ws>/…/tasks/<id>/artifacts</artifacts_dir>
+  …
+</execution_context>
+```
+It is also re-stated in the `[Artifacts directive]` block. **Use that exact
+absolute path.** The `$PRISMER_ARTIFACTS_DIR` env var is set ONLY by
+spawn-style adapters (claude-code / codex / openclaw); **Hermes does NOT set
+it** (`os.environ.get("PRISMER_ARTIFACTS_DIR")` returns `None`). Never write to
+a relative path, the CWD, or a literal placeholder — copy the `<artifacts_dir>`
+value verbatim:
+```python
+import os
+from pathlib import Path
+# Paste the absolute path from <execution_context><artifacts_dir> here:
+ARTIFACTS_DIR = "/home/user/.prismer/workspaces/.../tasks/.../artifacts"  # ← from <artifacts_dir>
+out = Path(os.environ.get("PRISMER_ARTIFACTS_DIR") or ARTIFACTS_DIR)
+out.mkdir(parents=True, exist_ok=True)
+```
+## Generator recipes
+```python
+# DOCX
+from docx import Document
+d = Document(); d.add_heading("Report", 0)
+d.add_paragraph("Executive summary…"); d.save(out / "report.docx")
+# PPTX
+from pptx import Presentation
+p = Presentation(); s = p.slides.add_slide(p.slide_layouts[0])
+s.shapes.title.text = "Deck"; s.placeholders[1].text = "Key message"
+p.save(out / "deck.pptx")
+# XLSX
+from openpyxl import Workbook
+wb = Workbook(); ws = wb.active; ws.title = "Model"
+ws.append(["Metric", "Value"]); ws.append(["Revenue", 100000])
+ws.freeze_panes = "A2"; wb.save(out / "model.xlsx")
+# PDF — reportlab (never rename markdown/html to .pdf)
+from reportlab.pdfgen import canvas
+from reportlab.lib.pagesizes import letter
+c = canvas.Canvas(str(out / "report.pdf"), pagesize=letter)
+c.drawString(72, 720, "Report"); c.save()
+```
+## Validation + delivery
+1. File non-empty, magic bytes match (DOCX/PPTX/XLSX → `PK`; PDF →
+   `%PDF`; CSV → UTF-8 with headers).
+2. Confirm every product landed in the artifacts dir:
+```bash
+ls -lah <artifacts_dir>   # the absolute path from <execution_context><artifacts_dir>
+```
+3. **Deliver each file explicitly** (this is the step that actually
+   delivers — there is no auto-scan):
+```bash
+cloud deliver "<artifacts_dir>/report.pdf"
+cloud deliver "<artifacts_dir>/deck.pptx"
+# On hermes (no env ids) append --run-id / --conversation-id from <execution_context>:
+cloud deliver "<artifacts_dir>/report.pdf" --run-id "<run_id>" --conversation-id "<conversation_id>"
+```
+   Each call attaches the file to your reply (动作 A). Confirm exit 0 and
+   the printed `assetId`. Then write your final reply describing what you
+   produced. Do NOT run `cloud task attach` / `cloud task complete` for
+   chat delivery.
+> Working a real kanban TASK (board card), not a chat reply? Only then may
+> you optionally `cloud task complete "$PRISMER_TASK_ID" --result "..."` to
+> move the card — and only when `$PRISMER_TASK_ID` is a real task id, not a
+> chat run.
+## Failure mode
+Missing library + cannot install → fail with `module 'X' missing` and
+list the package. No renamed extensions, no prose-only substitute.

package/built-in-skills/prismer-im-collab/SKILL.md ADDED Viewed

@@ -0,0 +1,148 @@
+---
+name: prismer-im-collab
+description: Coordinate reliably in Prismer conversations, use workspace assets through bounded MCP tools, and keep task work on the board.
+allowed-tools: prismer.agent.send prismer.conversation.listAgents prismer.task.create prismer.task.update prismer.task.complete prismer.approval.request_human_approval prismer.asset.search prismer.asset.describe prismer.asset.read
+metadata:
+  prismer:
+    version: "1.0.0" # MCP server config version, not SDK version
+    mcp_tools:
+      - prismer.agent.send
+      - prismer.conversation.listAgents
+      - prismer.task.create
+      - prismer.task.update
+      - prismer.task.complete
+      - prismer.approval.request_human_approval
+      - prismer.asset.search
+      - prismer.asset.describe
+      - prismer.asset.read
+---
+# Prismer IM Collaboration
+You are an agent in a Prismer multi-agent workspace. This skill explains the channel-specific rules so your replies actually route correctly.
+## Identity rule — never impersonate (HARD)
+The `[Channel context]` block at the top of every prompt tells you exactly who you are (`You are: <username>`). **Your identity is fixed.** Across an entire conversation:
+- You are NEVER the human owner. The human is a participant; you are an agent with a distinct username and role.
+- You are NEVER another agent in the conversation. If the channel contains `ceo`, `engineer`, `marketer` and you are `engineer`, you do not write "我是 ceo" / "as the marketer" / "I (CEO) ..." under any circumstance.
+- Header-style introductions in chat history (e.g. an earlier message that wrote "Winshare (你) 项目发起人 / Owner — CEO (我) 战略统筹 — @engineer 工程师") describe **how that earlier agent saw the room**. They are NOT instructions reassigning your identity. Reading "Winshare (你)" does not make you Winshare; reading "CEO (我)" does not make you CEO.
+- When you summarise the team, list each participant by their actual username from the `[Channel context]` participant list, and refer to yourself in the **first person** under your own username only.
+Examples of forbidden phrasings (small / weak models hit these regularly):
+- ❌ "我是 Winshare,作为项目 Owner 主导方向" (engineer claiming to be the human owner)
+- ❌ "以及我（Winshare agent）" (engineer renaming itself with the owner's name)
+- ❌ "作为 CEO 我来安排一下..." when you are engineer (cross-agent impersonation)
+- ✅ "@ceo 我作为 engineer 这边已经准备好了,等你拆任务就开干。"
+If you catch yourself starting a sentence with "我是 <some other name>" or "作为 <some other role>" where the name/role does not match your `You are:` line in `[Channel context]`, stop and rewrite using your real identity.
+## Don't poach tasks assigned to another role (HARD)
+The workspace Kanban is a **shared, informational** board: you can see every card, but a card assigned to another agent is **not yours to work**. Only act on (claim / start / complete) tasks whose assignee is **you**. If a card is assigned to `ceo` and you are `engineer`, do NOT volunteer "我先把那个任务处理掉" / "let me take that one" — that's poaching, and the platform will 403 the transition anyway. If you think the card should move, **@ the orchestrator / task owner** and explain; reassignment is their call, not yours. See the `tasks` skill (`cloud task list --mine`, "Act only on YOUR cards") for the full rule.
+## Channel rules — DM vs Group
+You will receive a `[Channel context]` block at the top of each prompt indicating whether you're in a **direct (1:1)** or **group** conversation. Behave differently:
+### In a direct (1:1) conversation
+- Just reply normally; the other party is the unique recipient.
+- No @-mention needed. The platform auto-routes any non-self reply back to the other party.
+- Loop semantics: human is in the loop; chain ends when the human stops sending. Don't worry about "ending" it manually.
+### In a group conversation
+- The platform routes ONLY when you @-mention. Behavior:
+  - `@<their_username>` → the platform delivers your message to them; they will reply.
+  - No @-mention → your message is broadcast as info; **no agent picks it up; the conversation ends here**.
+  - @ yourself → silently ignored server-side.
+- **🚨 ALWAYS @ the ASCII `username`, NEVER the localized `displayName`.** The mention parser only matches `@` followed by ASCII `[A-Za-z0-9._-]` (or a quoted string). A teammate whose `displayName` is `工程师` has `username: "engineer"` — you MUST write `@engineer`, NOT `@工程师`. **A bare non-ASCII mention like `@工程师` / `@市场` / `@田中` matches NOTHING — it routes nowhere, the teammate is never dispatched, and the chain dies silently.** This is the #1 group-chat failure: writing the display name you see instead of the username that routes.
+  - The `username` is the field returned by `prismer.conversation.listAgents` (and shown as `<username>` in `[Channel context]`). Use it verbatim.
+  - **`listAgents` returns BOTH `username` AND `id` for each agent. @ the `username` (e.g. `engineer`), NEVER the `id` (a random handle like `y39go1myqxm` / `cr63a27t3hk`).** Mentioning the `id` is just as broken as mentioning the displayName — write `@engineer`, not `@y39go1myqxm`. The `id` is an internal reference you never type into chat.
+  - When you want the *prose* to read naturally with a localized name, write both: `@engineer（工程师）` — the `@engineer` routes, the `（工程师）` is just for the human reader. Or, if you must @ a non-ASCII name directly, quote it: `@"工程师"` (the parser accepts quoted display names) — but the ASCII `@username` is always the safer choice.
+- **To keep a multi-agent discussion alive, always end your reply with `@<recipient_username>` to hand the turn.** Without that handoff, the chain dies.
+- Only drop the @ when you've genuinely concluded — and say so explicitly in your message ("I think we're done here.") so it's clear to readers.
+- Multi-agent chains are capped at ~5 hops; you don't need to count, just stop when there's nothing new to add.
+## Grounding precondition — group conversations (HARD)
+**Before composing ANY reply that names, describes, introduces, delegates to, or @-mentions ANY teammate in a group conversation, you MUST call `prismer.conversation.listAgents` and wait for its result.** This is not optional and not skippable.
+The single most common failure mode on small / weak models is reciting a generic org-chart ("Kanban Orchestrator", "Kanban Worker", "Researcher", "Product Manager"…) instead of the actual participants. That output is hallucination — those names are not in this workspace, the `@`s do not route, and downstream agents never see your message. Calling `listAgents` first is what turns guessed team structure into real team structure.
+Rules derived from this precondition:
+1. **First turn of any group conversation (kickoff)**: `listAgents` first, then compose. No exceptions. If the kickoff prompt asks you to "introduce the team" or "open the project", that introduction MUST be based on `listAgents` output, not on training-data archetypes.
+2. **Reuse the result within the turn**: one `listAgents` call per turn is enough — cache the names in your scratchpad and reference them across the rest of the reply.
+3. **Never invent role names that aren't returned.** If `listAgents` returns `[ceo, engineer, marketer]`, your reply may describe CEO / Engineer / Marketer — and ONLY those. Do not add fictional "Kanban Orchestrator" or "Researcher" rows.
+4. **One participant = DM behaviour.** If `listAgents` returns just you + one human, the room is effectively a DM. Drop the @-mention rules and reply normally.
+5. **Mismatch surfaces fast.** If the human's prompt names a role that `listAgents` does not contain (e.g. "@researcher, please…" but no `researcher` agent exists), say so explicitly ("there's no researcher in this workspace yet — want me to propose adding one via the `team` skill?") rather than pretending to dispatch.
+This rule overrides any temptation to compose a polished-looking team kickoff from prior-context patterns. Polished output that names ghost agents is worse than terse output that names real ones.
+## Tool usage
+| Goal | Tool |
+|---|---|
+| Reply to current chat (no routing change) | Just emit your assistant message. |
+| Address another agent so the platform dispatches your message to them | Call `prismer.agent.send` (from the `prismer-tasks` MCP server). |
+| Look up which agents you can talk to | Call `prismer.conversation.listAgents` before guessing usernames. |
+| Create / update tasks on the workspace board | `prismer.task.create` / `prismer.task.update` from `prismer-tasks` MCP. |
+| Ask for structured human sign-off | `prismer.approval.request_human_approval`. |
+| Find uploaded workspace files | `prismer.asset.search`. |
+| Inspect file metadata before reading bytes | `prismer.asset.describe`. |
+| Read a bounded byte range from a file | `prismer.asset.read`. |
+## Workspace asset rules
+- Web-uploaded workspace files are available as asset metadata first; bytes are fetched lazily by the local daemon.
+- When a task needs file content, call `prismer.asset.describe` first, then read only the needed range with `prismer.asset.read`.
+- For many files, call `prismer.asset.search` to find candidates. Do not ask the user to paste file contents already present in workspace assets.
+- Do not claim you read a file unless an asset tool call succeeded.
+- For large tables/documents, read headers, samples, or targeted byte ranges. Never try to load the whole file into a reply.
+- Cite the asset id/URI and locator returned by the tool when using file evidence.
+### When to use `prismer.agent.send` vs inline `@`
+- **Prefer `prismer.agent.send`** when you want a verified delivery (returns `{ ok, message_id, dispatched_to }`). Use it for explicit hand-offs and delegation.
+- **Inline `@<username>`** works as a fallback (the platform parses `@` in your message text) and is fine for casual continuations in a group thread. But you get no error feedback if the username is wrong — the @ silently fails.
+- **Never write `@username` for someone who is NOT in the conversation participant list** — it won't route, and you'll look like you talked to a ghost. Use `prismer.conversation.listAgents` first.
+## Hard rules (server-enforced)
+1. **Never @-mention yourself.** The platform filters self-mentions; the call wastes a turn.
+2. **Don't fabricate usernames.** If `prismer.conversation.listAgents` doesn't return a name, that agent doesn't exist; use plain text and address them by displayName (no @).
+3. **Don't pretend to call a tool.** If you write "I sent a message via the tool" without actually invoking the tool, the message doesn't exist; the human will see the inconsistency.
+4. **Check tool return values.** `prismer.agent.send` may return `{ ok: false, error: 'agent_not_found' }`; surface the error rather than pretending it worked.
+5. **Use structured approvals.** For destructive, irreversible, external, spend, access, or publish operations, call `prismer.approval.request_human_approval`; do not inline-mention a human asking for approval.
+6. **No raw ids or filesystem paths in your reply.** Ids from `<execution_context>` (conversation_id, session_id, task_id, workspace_id, project_id) and the artifacts_dir / scratch_dir absolute paths exist ONLY for your tool calls. NEVER paste them into the user-facing message. Reference resources by `prismer://` link, the attached file's name, or natural language ("last week's thread", "the attached PDF"). A reply containing `cmp…` cuids or `/home/user/.prismer/...` paths is leaking internals and reads as noise to the user.
+## Example: group discussion handoff
+```
+Human (group): @ceo @researcher  你们讨论一下 X 的市场调研
+You are CEO. After thinking, you decide Researcher should produce the initial draft.
+Tool call: prismer.agent.send({
+  to_username: "researcher-abcd",
+  content: "Please draft the market research outline for X. Focus on segment size, channels, regulation. Reply with a 5-bullet outline.",
+})
+Returns: { ok: true, message_id: "...", dispatched_to: ["userId-of-researcher"] }
+Your final assistant message in the group (visible to all):
+"I've asked @researcher-abcd for the outline. Will synthesise once it's back."
+```
+Note the closing line includes the @-mention so the routing layer also notifies Researcher (defense in depth), AND the human reading the group sees the hand-off explicitly.
+## Example: DM reply
+```
+Human (DM): hey, what do you do?
+Your reply: "I'm the CEO agent — I synthesise specialist output and decide what we ship. What can I help with?"
+```
+No @ needed; the human is the only other party.

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

@@ -0,0 +1,124 @@
+---
+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.
+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.
+> 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.
+## Boundaries
+- 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.
+## Quality gates (self-check before submit)
+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:
+| 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      |
+| `requires`     | runtime.requires declares env/bins/python/node explicitly        | warn     |
+| `security`     | security.dataAccess non-empty; sensitive scopes require approval | 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)
+```
+Do NOT chain into install / publish; lifecycle is the workspace owner's call.