@openviking/dsh-memory-plugin 0.4.3 → 0.5.0

package/README.md

@@ -196,14 +196,15 @@ The patch can also carry plugin config:
 
 ## Behavior
 
-- `agent/session-start` injects the OpenViking profile and available-memory index through `agent.inject()`.
+- `agent/session-start` injects the OpenViking profile, the available-memory index, and the `<available-skills>` catalog through `agent.inject()`.
 - `agent/pre-step` retrieves with the current step input and appends a durable plugin message to that same step.
 - `session/event` captures user, assistant, and optionally tool-result messages without scraping a transcript.
 - `turn/end` checks the OpenViking pending-token threshold and commits when required.
 - `skipSubagentSessions: true` excludes sessions marked with `header.origin: subagent` from automatic profile, recall, capture, and commit; it defaults to `false`.
 - `syncTurns: false` stops every new write: no captured messages, no threshold or shutdown commit. Writes queued while the toggle was on are still replayed by the background drainer once the server recovers — they were captured with the toggle on. Profile injection and recall are unaffected; it defaults to `true`.
+- `skillCatalog` (default `true`) and `skillCatalogTokenBudget` (default `1200`; `0` also turns the catalog off) govern `<available-skills>`. The catalog comes from one `GET /api/v1/skills?node_limit=200` call: the user's own skills first, then those shared under `viking://agent/skills` minus any whose name the user also owns, each description cut to about 40 tokens. Its budget is separate from `profileTokenBudget`. When the descriptions do not fit, the catalog lists names only (with a `... +N more` tail if even the names do not all fit); when not even one name fits, it shrinks to a one-line count; with no skills, or a server without the endpoint, it is omitted.
 - Failed writes enter the shared OpenViking pending queue. A background drainer (default every 60s, `OPENVIKING_PENDING_DRAIN_INTERVAL_MS`) probes the server health and replays the queue in-process, so a transient write failure recovers without restarting dsh; it does not consume the session-start retry budget. Session-start replays keep consuming retries as before.
-- `tools/pre-execute` denies a DSH filesystem tool (`read`, `glob`, `grep`, `edit`, `write`, `str_replace_editor`) whose path argument is a `viking://` URI, pointing the model at the bridged `mcp__openviking__*` tools instead. A `grep` whose pattern is `viking://` text still runs.
+- `tools/pre-execute` denies a DSH filesystem tool (`read`, `glob`, `grep`, `edit`, `write`, `str_replace_editor`) whose path argument is a `viking://` URI, pointing the model at the bridged `mcp__openviking__*` tools instead. A `write` or `edit` under a skill directory (`viking://~/skills/...`, `viking://user/<id>/skills/...`, `viking://agent/skills/...`) points at `mcp__openviking__add_skill` instead, which creates or replaces a whole skill from its `SKILL.md` text. A `grep` whose pattern is `viking://` text still runs.
 - `tools/post-execute` lets a `bash` command that carries a `viking://` URI run unchanged and attaches a notice for the model: use the bridged tools if it meant OpenViking content, or ignore the notice when the URI is intentional data such as an `ov` argument or an HTTP payload.
 
 Each DSH session maps to `dsh-<session-id>` in OpenViking. Workspace-derived actor peers are resolved per session and sent on every session-specific request: the peer is the git identity of the session's workspace — the normalized `origin` URL (`git@github.com:volcengine/OpenViking.git` becomes `github.com-volcengine-openviking`), else the repository root path, that fallback keeping the older rule where every non-letter-or-digit character becomes `-`. Outside a git repository no peer is sent at all, and what is remembered there goes to the user-level space `viking://user/<you>/memories`. One repository therefore keeps one peer across subdirectories, worktrees, clones and machines, while a fork's different origin keeps it separate. DSH does not read workspace `.openviking/config.json` files, so a `peer.id` written there has no effect; pin a peer with `OPENVIKING_PEER_ID` instead. Memories written under the older path-derived peer stay reachable: the default `recallPeerScope: all` sweeps every peer under the user.
@@ -215,16 +216,18 @@ names — `mcp__openviking__search`, `mcp__openviking__read`,
 `mcp__openviking__list`, `mcp__openviking__tree`, `mcp__openviking__grep`,
 `mcp__openviking__glob`, `mcp__openviking__remember`,
 `mcp__openviking__write`, `mcp__openviking__edit`,
-`mcp__openviking__forget`, `mcp__openviking__add_resource`, and the rest of
-whatever the connected server advertises. The list re-syncs when the server
-announces a change, so a server upgrade adds tools without a bundle release.
+`mcp__openviking__forget`, `mcp__openviking__add_resource`,
+`mcp__openviking__add_skill`, and the rest of whatever the connected server
+advertises. The list re-syncs when the server announces a change, so a server
+upgrade adds tools without a bundle release.
 
 `mcp__openviking__forget` performs permanent deletion. The calling model should
 use it only when the user explicitly requests deletion.
 
-The bundle also serves the shared `openviking-memory` skill from `skills/`
-through its own isolated `ctx.skills` provider, so the model gets the same
-guidance on when to search, read, and write that the other integrations ship.
+The bundle also serves the shared `openviking-memory` and `openviking-skills`
+skills from `skills/` through its own isolated `ctx.skills` provider, so the
+model gets the same guidance the other integrations ship: when to search, read,
+and write, and how to find, use, create, share, and migrate OpenViking skills.
 
 ## Testing
 

package/config.mjs

@@ -1,7 +1,7 @@
 import { buildPluginConfig } from "./shared/plugin-config.mjs";
 import { loadCredentialFiles } from "./shared/credentials.mjs";
 
-export const PLUGIN_VERSION = "0.4.3";
+export const PLUGIN_VERSION = "0.5.0";
 
 /**
  * Namespace for the bridged OpenViking MCP tools. DSH publishes every MCP tool

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openviking/dsh-memory-plugin",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "OpenViking memory and context bundle for DeepSeek Harness",
   "type": "module",
   "main": "index.mjs",

package/runtime.mjs

@@ -102,6 +102,7 @@ export class OpenVikingRuntime {
       (path, init, options) => this.client.fetchJSON(path, init, options),
       state.config.profileTokenBudget,
       state.config.peerId,
+      state.config,
     );
     state.profileBlock = profile?.block
       ? [

package/shared/config-schema.mjs

@@ -98,7 +98,7 @@ export const KNOBS = [
   // off/client/server/auto through `normalizeRewriteMode`; Codex reads the same
   // key as on/off. Both spellings stay declared so neither harness's users are
   // told their config is a typo.
-  { name: "recallCompress", type: "string", default: "auto", env: "OPENVIKING_RECALL_COMPRESS", aliases: ["recallRewrite"], capability: "recall" },
+  { name: "recallCompress", type: "string", default: "off", harness: { claude_code: "auto", codex: "auto" }, env: "OPENVIKING_RECALL_COMPRESS", aliases: ["recallRewrite"], capability: "recall" },
   { name: "recallCompressModel", type: "string", default: "", env: "OPENVIKING_RECALL_COMPRESS_MODEL", capability: "recall" },
   { name: "recallCompressBaseUrl", type: "string", default: "", env: "OPENVIKING_RECALL_COMPRESS_BASE_URL", capability: "recall" },
   { name: "recallCompressThinking", type: "string", default: "", env: "OPENVIKING_RECALL_COMPRESS_THINKING", aliases: ["recallCompressReasoningEffort"], capability: "recall" },
@@ -152,6 +152,21 @@ export const KNOBS = [
   { name: "resumeArchiveMaxChars", type: "int", default: 6000, min: 1000, max: 200000, env: "OPENVIKING_RESUME_ARCHIVE_MAX_CHARS", capability: "session" },
   { name: "skillExperience", type: "bool", default: false, env: "OPENVIKING_SKILL_EXPERIENCE", capability: "session" },
   { name: "skillExperienceLimit", type: "int", default: 3, min: 1, max: 50, env: "OPENVIKING_SKILL_EXPERIENCE_LIMIT", capability: "session" },
+  { name: "skillCatalog", type: "bool", default: true, env: "OPENVIKING_SKILL_CATALOG", capability: "session" },
+  { name: "skillCatalogTokenBudget", type: "int", default: 1200, min: 0, max: 20000, env: "OPENVIKING_SKILL_CATALOG_TOKEN_BUDGET", capability: "session" },
+  // Claude Code saves hook context over 10,000 chars to a file and shows the
+  // model a 2 KB preview; Codex spills past ~10,000 bytes; ZCode drops stdout
+  // over 32 KB. 0 means no cap.
+  {
+    name: "sessionStartMaxBytes",
+    type: "int",
+    default: 0,
+    harness: { claude_code: 9500, codex: 9500, zcode: 20000 },
+    min: 0,
+    max: 1000000,
+    env: "OPENVIKING_SESSION_START_MAX_BYTES",
+    capability: "session",
+  },
   { name: "skipSubagentSessions", type: "bool", default: false, env: "OPENVIKING_SKIP_SUBAGENT_SESSIONS", capability: "session" },
   { name: "repoContext", type: "bool", default: true, capability: "session" },
   { name: "repoContextCacheTtlMs", type: "int", default: 60000, min: 1000, max: 3600000, capability: "session" },

package/shared/plugin-config.mjs

@@ -29,7 +29,7 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-import { HARNESS_KEYS, KNOBS, harnessKey, resolveKnobs } from "./config-schema.mjs";
+import { HARNESS_KEYS, KNOBS, harnessKey, knobDefault, resolveKnobs } from "./config-schema.mjs";
 import {
   buildUserAgent,
   loadCredentialFiles,
@@ -224,9 +224,15 @@ export function buildPluginConfig(harness, {
     env,
   });
 
+  const recallRewrite = normalizeRewriteMode(
+    env.OPENVIKING_RECALL_COMPRESS ?? env.OPENVIKING_RECALL_REWRITE ?? settings.recallCompress,
+    knobDefault(KNOBS.find((knob) => knob.name === "recallCompress"), harnessKey(name)),
+  );
   const config = {
     ...settings,
     harness: name,
+    recallCompress: recallRewrite,
+    recallRewrite,
     clientVersion,
     userAgent: buildUserAgent(name, clientVersion),
 

package/shared/profile-inject.mjs

@@ -2,10 +2,11 @@
 /**
  * Session-start profile injection helper.
  *
- * Builds a <user-profile> + <available-memories> block from
+ * Builds a <user-profile> + <available-memories> (+ <available-skills>) block from
  *   viking://user/<space>/memories/profile.md
  *   viking://user/<space>/memories/preferences/   (ls with abstracts)
  *   viking://user/<space>/memories/entities/      (ls with abstracts)
+ *   GET /api/v1/skills                            (own + account-shared skills)
  *
  * Budget enforced via the CJK-aware estimateTokens() below — codepoint >=
  * 0x3000 counts at 1.5 tokens, else chars/4. The estimator is exported so
@@ -17,6 +18,10 @@
  * alongside in a single context envelope.
  */
 
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
 const USER_RESERVED_DIRS = new Set(["memories"]);
 let _userSpaceCache = null;
 
@@ -185,7 +190,9 @@ function elideProfile(content, maxTokens) {
   return `${head}${ELLIPSIS}${lines.slice(tailStart).join("\n")}`;
 }
 
-function formatListing(headerUri, entries, budgetTokens) {
+const MEMORY_MORE_HINT = "use `memory_recall`";
+
+function formatListing(headerUri, entries, budgetTokens, moreHint = MEMORY_MORE_HINT) {
   if (entries.length === 0) return { lines: [], used: 0, dropped: 0 };
   // Header is the full directory URI; child lines are relative paths so the
   // agent can reconstruct each leaf's full URI by concatenation while the
@@ -194,10 +201,11 @@ function formatListing(headerUri, entries, budgetTokens) {
   const headerTokens = estimateTokens(header);
   // If the header alone busts the budget, emit just a one-line stub instead
   // of silently violating the cap (Copilot review point).
-  if (headerTokens > budgetTokens) {
-    const stub = `  ${headerUri}/  (${entries.length} entries, budget too tight; use \`memory_recall\`)`;
+  const stubListing = () => {
+    const stub = `  ${headerUri}/  (${entries.length} entries, budget too tight; ${moreHint})`;
     return { lines: [stub], used: estimateTokens(stub), dropped: entries.length };
-  }
+  };
+  if (headerTokens > budgetTokens) return stubListing();
   const lines = [header];
   let used = headerTokens;
   for (let i = 0; i < entries.length; i++) {
@@ -208,11 +216,18 @@ function formatListing(headerUri, entries, budgetTokens) {
     const line = `    - ${e.name}${desc}`;
     const tokens = estimateTokens(line);
     if (used + tokens > budgetTokens) {
-      const remaining = entries.length - i;
-      const tail = `    ... +${remaining} more, use \`memory_recall\``;
+      let remaining = entries.length - i;
+      const tailFor = (n) => `    ... +${n} more, ${moreHint}`;
+      // A listing that stops without the tail hides that anything was cut, so
+      // give entries back until it fits.
+      while (used + estimateTokens(tailFor(remaining)) > budgetTokens && lines.length > 1) {
+        used -= estimateTokens(lines.pop());
+        remaining++;
+      }
+      // A bare header would read as an empty directory.
+      if (lines.length === 1) return stubListing();
+      const tail = tailFor(remaining);
       const tailTokens = estimateTokens(tail);
-      // Only emit the tail if it fits; otherwise the listing closes silently
-      // rather than violating the cap to advertise its own truncation.
       if (used + tailTokens <= budgetTokens) {
         lines.push(tail);
         return { lines, used: used + tailTokens, dropped: remaining };
@@ -225,61 +240,196 @@ function formatListing(headerUri, entries, budgetTokens) {
   return { lines, used, dropped: 0 };
 }
 
+const AGENT_SKILLS_ROOT = "viking://agent/skills";
+// The server caps each skill root at node_limit, so the two roots together
+// can return twice this many; the token budget below decides what fits.
+const SKILL_CATALOG_NODE_LIMIT = 200;
+const SKILL_DESCRIPTION_TOKENS = 40;
+const SKILL_MORE_HINT = "search OpenViking skills to find the rest";
+const SKILL_USAGE_LINE =
+  "  OpenViking skills (stored in OpenViking, not local files). Before following one, read <dir>/<name>/SKILL.md with the OpenViking read tool.";
+// Skill descriptions are user-written, and the shared root is account-wide:
+// never let one close or open the envelope the catalog sits in.
+const ENVELOPE_TAG_RE = /<\/?(?:openviking-context|available-skills|available-memories|user-profile|memory)\b[^>]*>/gi;
+
+function sanitizeInline(text) {
+  return String(text || "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(ENVELOPE_TAG_RE, (tag) => tag.replace(/</g, "&lt;").replace(/>/g, "&gt;"));
+}
+
+function truncateToTokens(text, maxTokens) {
+  if (estimateTokens(text) <= maxTokens) return text;
+  return `${text.slice(0, Math.max(1, tokensToCharsBudget(text, maxTokens) - 1)).trimEnd()}…`;
+}
+
+/**
+ * Both skill roots from one GET /api/v1/skills, grouped by root with the
+ * user's own skills first. A shared skill whose name the user also has is
+ * dropped: the private one is the one the agent should load. Servers without
+ * the endpoint, or any failure, yield no catalog.
+ */
+async function fetchSkillCatalog(fetchJSON, actorPeerId = "") {
+  const res = await fetchJSON(
+    `/api/v1/skills?node_limit=${SKILL_CATALOG_NODE_LIMIT}`,
+    {},
+    { actorPeerId },
+  );
+  const skills = res.ok && Array.isArray(res.result?.skills) ? res.result.skills : [];
+  const own = [];
+  const shared = [];
+  for (const skill of skills) {
+    const name = typeof skill?.name === "string" ? skill.name.trim() : "";
+    const uri = typeof skill?.uri === "string" ? skill.uri.replace(/\/+$/, "") : "";
+    if (!name || !uri.includes("/")) continue;
+    const entry = {
+      name,
+      root: uri.slice(0, uri.lastIndexOf("/")),
+      abstract: truncateToTokens(sanitizeInline(skill.description), SKILL_DESCRIPTION_TOKENS),
+    };
+    (uri.startsWith(`${AGENT_SKILLS_ROOT}/`) ? shared : own).push(entry);
+  }
+  const ownNames = new Set(own.map((e) => e.name));
+  const byName = (a, b) => a.name.localeCompare(b.name);
+  return [
+    own.sort(byName),
+    shared.filter((e) => !ownNames.has(e.name)).sort(byName),
+  ].filter((group) => group.length > 0);
+}
+
+function renderSkillGroups(groups, budgetTokens, withDescriptions) {
+  const lists = groups.map((g) => (withDescriptions ? g : g.map((e) => ({ ...e, abstract: "" }))));
+  const fullCost = lists.map((entries) => formatListing(entries[0].root, entries, Infinity, SKILL_MORE_HINT).used);
+  const lines = [];
+  let used = 0;
+  let dropped = 0;
+  for (let i = 0; i < lists.length; i++) {
+    // A group takes its fair share, or everything the later groups leave
+    // when listed in full, whichever is larger.
+    const remaining = budgetTokens - used;
+    const laterCost = fullCost.slice(i + 1).reduce((a, b) => a + b, 0);
+    const share = Math.max(Math.floor(remaining / (lists.length - i)), remaining - laterCost);
+    const block = formatListing(lists[i][0].root, lists[i], share, SKILL_MORE_HINT);
+    lines.push(...block.lines);
+    used += block.used;
+    dropped += block.dropped;
+  }
+  return { lines, used, dropped };
+}
+
+/**
+ * <available-skills> within its own token budget: every entry with its
+ * description when that fits, otherwise names only (more skills stay
+ * visible, with a "+N more" tail), and a one-line count when not even one
+ * name fits.
+ */
+function formatSkillCatalog(groups, budgetTokens) {
+  const count = groups.reduce((n, g) => n + g.length, 0);
+  if (count === 0) return { lines: [], used: 0, dropped: 0, count };
+  const open = "<available-skills>";
+  const close = "</available-skills>";
+  const frameTokens = estimateTokens(open) + estimateTokens(SKILL_USAGE_LINE) + estimateTokens(close);
+  const listingBudget = Math.max(0, budgetTokens - frameTokens);
+  let body = renderSkillGroups(groups, listingBudget, true);
+  if (body.dropped > 0) body = renderSkillGroups(groups, listingBudget, false);
+  if (body.dropped >= count) {
+    const stub = `${open}${count} OpenViking skills; search OpenViking skills to find them.${close}`;
+    if (estimateTokens(stub) > budgetTokens) return { lines: [], used: 0, dropped: count, count };
+    return { lines: [stub], used: estimateTokens(stub), dropped: count, count };
+  }
+  return {
+    lines: [open, SKILL_USAGE_LINE, ...body.lines, close],
+    used: frameTokens + body.used,
+    dropped: body.dropped,
+    count,
+  };
+}
+
 /**
  * Build the profile injection block.
  *
- * Returns null when neither profile.md nor either listing has any content.
- * The returned `block` is just the inner <user-profile>/<available-memories>
- * payload — the caller wraps it in <openviking-context source="...">.
+ * Returns null when neither profile.md, either listing, nor the skill catalog
+ * has any content. The returned `block` is just the inner
+ * <user-profile>/<available-memories>/<available-skills> payload — the caller
+ * wraps it in <openviking-context source="...">.
  *
  * @param {Function} fetchJSON  ov-session.mjs:makeFetchJSON closure
- * @param {number} totalBudgetTokens  chars/4 budget, total for the whole block
+ * @param {number} totalBudgetTokens  budget for the profile and memory listings
+ * @param {string} [actorPeerId]
+ * @param {{ skillCatalog?: boolean, skillCatalogTokenBudget?: number, sessionStartMaxBytes?: number }} [options]
+ *   callers pass their resolved plugin config: its skillCatalog knob adds
+ *   <available-skills>, budgeted separately by skillCatalogTokenBudget.
+ *   Without it the block is unchanged.
  * @returns {Promise<null | {
  *   block: string, chars: number, tokens: number, profileUri: string,
  *   profileChars: number, prefCount: number, entCount: number,
  *   droppedPref: number, droppedEnt: number,
+ *   skillCount: number, droppedSkill: number, skillTokens: number,
  * }>}
  */
-export async function buildProfileBlock(fetchJSON, totalBudgetTokens, actorPeerId = "") {
+export async function buildProfileBlock(fetchJSON, totalBudgetTokens, actorPeerId = "", options = {}) {
+  const { skillCatalog = false, skillCatalogTokenBudget = 0, sessionStartMaxBytes = 0 } = options;
+  // Hosts that spill (Claude Code, Codex) or drop (ZCode) oversized hook output
+  // get a byte cap. An estimated token is about 4 UTF-8 bytes at most, so the
+  // token budgets shrink to fit under it.
+  const capTokens = sessionStartMaxBytes > 0
+    ? Math.max(0, Math.floor(sessionStartMaxBytes / 4) - 50)
+    : Infinity;
+  const skillBudget = Math.min(skillCatalogTokenBudget, Math.floor(capTokens / 4));
   const space = await resolveUserSpace(fetchJSON, actorPeerId);
   const profileUri = `viking://user/${space}/memories/profile.md`;
   const prefUri = `viking://user/${space}/memories/preferences`;
   const entUri = `viking://user/${space}/memories/entities`;
 
-  const [profile, prefs, ents] = await Promise.all([
+  const [profile, prefs, ents, skillGroups] = await Promise.all([
     readProfile(fetchJSON, profileUri, actorPeerId),
     lsDir(fetchJSON, prefUri, actorPeerId),
     lsDir(fetchJSON, entUri, actorPeerId),
+    skillCatalog && skillBudget > 0
+      ? fetchSkillCatalog(fetchJSON, actorPeerId)
+      : [],
   ]);
+  const skills = formatSkillCatalog(skillGroups, skillBudget);
 
-  if (!profile && prefs.length === 0 && ents.length === 0) return null;
+  if (!profile && prefs.length === 0 && ents.length === 0 && skills.lines.length === 0) {
+    return null;
+  }
 
+  const memoryBudget = Math.min(totalBudgetTokens, Math.max(0, capTokens - skills.used));
   // Profile gets up to half the total budget; listings split the rest.
   // Sub-cap protects against a runaway profile blowing the listing budget.
-  const profileBudget = Math.floor(totalBudgetTokens / 2);
+  const profileBudget = Math.floor(memoryBudget / 2);
   const profileTrunc = profile ? elideProfile(profile, profileBudget) : null;
   const profileTokens = estimateTokens(profileTrunc || "");
 
-  const listingBudget = Math.max(0, totalBudgetTokens - profileTokens);
+  const listingBudget = Math.max(0, memoryBudget - profileTokens);
   const halfListing = Math.floor(listingBudget / 2);
   const prefBlock = formatListing(prefUri, prefs, halfListing);
   const entBudget = Math.max(0, listingBudget - prefBlock.used);
   const entBlock = formatListing(entUri, ents, entBudget);
 
-  const lines = [];
-  if (profileTrunc) {
-    lines.push(`<user-profile uri="${profileUri}">`);
-    lines.push(profileTrunc);
-    lines.push(`</user-profile>`);
+  const profileLines = profileTrunc
+    ? [`<user-profile uri="${profileUri}">`, profileTrunc, `</user-profile>`]
+    : [];
+  let memoryLines = prefBlock.lines.length > 0 || entBlock.lines.length > 0
+    ? [`<available-memories>`, ...prefBlock.lines, ...entBlock.lines, `</available-memories>`]
+    : [];
+  let skillLines = skills.lines;
+  const render = () => [...profileLines, ...memoryLines, ...skillLines].join("\n");
+  let block = render();
+  // The estimate can still run over on multi-byte punctuation; the index goes
+  // first, then the catalog.
+  if (sessionStartMaxBytes > 0 && utf8Bytes(block) > sessionStartMaxBytes) {
+    memoryLines = [];
+    block = render();
   }
-  if (prefBlock.lines.length > 0 || entBlock.lines.length > 0) {
-    lines.push(`<available-memories>`);
-    lines.push(...prefBlock.lines);
-    lines.push(...entBlock.lines);
-    lines.push(`</available-memories>`);
+  if (sessionStartMaxBytes > 0 && utf8Bytes(block) > sessionStartMaxBytes) {
+    skillLines = [];
+    block = render();
   }
+  if (!block) return null;
 
-  const block = lines.join("\n");
   return {
     block,
     chars: block.length,
@@ -288,7 +438,58 @@ export async function buildProfileBlock(fetchJSON, totalBudgetTokens, actorPeerI
     profileChars: profile?.length ?? 0,
     prefCount: prefs.length,
     entCount: ents.length,
-    droppedPref: prefBlock.dropped,
-    droppedEnt: entBlock.dropped,
+    droppedPref: memoryLines.length ? prefBlock.dropped : prefs.length,
+    droppedEnt: memoryLines.length ? entBlock.dropped : ents.length,
+    skillCount: skills.count,
+    droppedSkill: skillLines.length ? skills.dropped : skills.count,
+    skillTokens: skillLines.length ? skills.used : 0,
   };
 }
+
+function utf8Bytes(text) {
+  return Buffer.byteLength(String(text || ""), "utf8");
+}
+
+/**
+ * Cut `text` to at most `maxBytes` UTF-8 bytes on a line boundary, marking the
+ * cut. A non-positive cap returns the text unchanged.
+ */
+export function truncateToBytes(text, maxBytes) {
+  const value = String(text || "");
+  if (!(maxBytes > 0) || utf8Bytes(value) <= maxBytes) return value;
+  const marker = "\n… [truncated]";
+  const lines = value.split("\n");
+  const kept = [];
+  let used = utf8Bytes(marker);
+  for (const line of lines) {
+    const cost = utf8Bytes(line) + 1;
+    if (used + cost > maxBytes) break;
+    kept.push(line);
+    used += cost;
+  }
+  return `${kept.join("\n")}${marker}`;
+}
+
+/**
+ * Whether `block` is what this session was last given, recording it either
+ * way. Resume reuses history that already holds the earlier injection, so an
+ * unchanged block need not be sent again.
+ */
+export function isRepeatInjection(statePath, sessionId, block) {
+  if (!statePath || !sessionId) return false;
+  const digest = createHash("sha256").update(String(block || "")).digest("hex");
+  let seen = {};
+  try {
+    seen = JSON.parse(readFileSync(statePath, "utf-8")) || {};
+  } catch { /* first injection */ }
+  const repeat = seen[sessionId] === digest;
+  delete seen[sessionId];
+  seen[sessionId] = digest;
+  const ids = Object.keys(seen);
+  for (const id of ids.slice(0, Math.max(0, ids.length - 200))) delete seen[id];
+  try {
+    mkdirSync(dirname(statePath), { recursive: true });
+    writeFileSync(statePath, JSON.stringify(seen));
+  } catch { /* best effort: a lost record only means one more injection */ }
+  return repeat;
+}

package/shared/recall-core.mjs

@@ -309,21 +309,46 @@ async function resolveTargetUri(fetchJSON, targetUri, actorPeerId = "") {
   return `viking://user/${space}/${parts.join("/")}`;
 }
 
-async function searchOneSource(fetchJSON, query, source, limit, actorPeerId = "") {
-  const resolvedUri = await resolveTargetUri(fetchJSON, source.uri, actorPeerId);
-  const body = { query, target_uri: resolvedUri, limit, score_threshold: 0 };
-  const res = await fetchJSON("/api/v1/search/find", {
-    method: "POST",
-    body: JSON.stringify(body),
-  }, { actorPeerId });
-  if (!res.ok) return [];
-  const items = res.result?.[source.bucket] || [];
-  return items.map((item) => ({ ...item, _sourceType: source.type }));
+async function searchOneSource(fetchJSON, cfg, query, source, limit, options) {
+  const actorPeerId = options.actorPeerId || "";
+  const home = await resolveTargetUri(fetchJSON, source.uri, actorPeerId);
+  const targets = [...new Set(cfg.user
+    ? [`viking://user/${cfg.user}/${source.bucket}`, home] : [home])];
+  const sessionId = String(options.sessionId || "").trim();
+  const search = async (target, session) => {
+    const body = { query, target_uri: target, limit, score_threshold: 0 };
+    if (session) body.session_id = session;
+    const init = { method: "POST", body: JSON.stringify(body) };
+    // Session-aware retrieval may decide no context is needed. Only after all
+    // targets are empty do we retry without the session. Old servers still
+    // support find; an unsupported search route can fall back to it.
+    let res = await fetchJSON(sessionId ? "/api/v1/search/search" : "/api/v1/search/find", init, { actorPeerId });
+    if (sessionId && !res.ok && (
+      !res.status || res.status === 404 || res.status === 405 || res.status >= 500
+      || ((res.status === 400 || res.status === 422) && looksLikeUnknownField(res))
+    )) {
+      const { session_id, ...findBody } = body;
+      res = await fetchJSON("/api/v1/search/find", { method: "POST", body: JSON.stringify(findBody) }, { actorPeerId });
+    }
+    const items = res.ok && Array.isArray(res.result?.[source.bucket]) ? res.result[source.bucket] : [];
+    return items.map((item) => ({ ...item, _sourceType: source.type }));
+  };
+  for (const target of targets) {
+    const items = await search(target, sessionId);
+    if (items.length) return items;
+  }
+  if (sessionId) {
+    for (const target of targets) {
+      const items = await search(target, "");
+      if (items.length) return items;
+    }
+  }
+  return [];
 }
 
-async function searchAllSources(fetchJSON, query, perSourceLimit, actorPeerId = "", log = () => {}) {
+async function searchAllSources(fetchJSON, cfg, query, perSourceLimit, options, log = () => {}) {
   const results = await Promise.all(
-    SOURCES.map((src) => searchOneSource(fetchJSON, query, src, perSourceLimit, actorPeerId)),
+    SOURCES.map((src) => searchOneSource(fetchJSON, cfg, query, src, perSourceLimit, options)),
   );
   const all = results.flat();
   log("recall_search_summary", {
@@ -359,50 +384,30 @@ async function resolveItemContent(fetchJSON, item, cfg, actorPeerId = "") {
   return content;
 }
 
-async function buildFallbackInjectionBlock(fetchJSON, items, cfg, actorPeerId = "", log = () => {}) {
+function formatFallback(items, cfg, log = () => {}) {
   const budgetTotal = Math.max(200, Number(cfg.recallTokenBudget || 2000));
-  let budgetRemaining = budgetTotal;
-  const lines = [
-    "<openviking-context>",
-    "Relevant context from OpenViking. Use the read MCP tool to expand URIs.",
-  ];
+  const lines = [];
   let contentCount = 0;
   let hintCount = 0;
-
+  const maxChars = Math.max(50, Number(cfg.recallMaxContentChars || 500));
   for (const item of items) {
     const score = (clampScore(item.score) * 100).toFixed(0);
-    const uriLine = `- [${item._sourceType} ${score}%] ${item.uri}`;
-
-    if (budgetRemaining > 0) {
-      const content = await resolveItemContent(fetchJSON, item, cfg, actorPeerId);
-      const contentLine = `- [${item._sourceType} ${score}%] ${content}`;
-      const lineTokens = estimateTokens(contentLine);
-
-      if (lineTokens > budgetRemaining && contentCount > 0) {
-        lines.push(uriLine);
-        hintCount++;
-      } else {
-        lines.push(contentLine);
-        budgetRemaining -= lineTokens;
-        contentCount++;
-      }
-    } else {
+    const kind = item._sourceType || item.category || "memory";
+    const uriLine = `- [${kind} ${score}%] ${item.uri}`;
+    const text = String(item.text || item.uri);
+    const content = text.length > maxChars ? `${text.slice(0, maxChars)}...` : text;
+    const contentLine = `- [${kind} ${score}%] ${content}`;
+    if (estimateTokens(wrapContext([...lines, uriLine, contentLine].join("\n"))) <= budgetTotal) {
+      lines.push(uriLine, contentLine);
+      contentCount += 1;
+    } else if (estimateTokens(wrapContext([...lines, uriLine].join("\n"))) <= budgetTotal) {
       lines.push(uriLine);
-      hintCount++;
+      hintCount += 1;
     }
   }
-
-  lines.push("</openviking-context>");
-
-  const budgetUsed = budgetTotal - budgetRemaining;
-  log("recall_injection_built", {
-    contentItems: contentCount,
-    hintItems: hintCount,
-    budgetUsed,
-    budgetTotal,
-  });
-
-  return { block: lines.join("\n"), contentCount, hintCount, budgetUsed, stage: "ranked" };
+  const budgetUsed = lines.length ? estimateTokens(wrapContext(lines.join("\n"))) : 0;
+  log("recall_injection_built", { contentItems: contentCount, hintItems: hintCount, budgetUsed, budgetTotal });
+  return { rendered: lines.join("\n"), contentCount, hintCount, budgetUsed };
 }
 
 const LEGACY_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
@@ -469,10 +474,14 @@ function looksLikeUnknownField(res) {
 }
 
 function wrapContext(body) {
+  // Retrieved text cannot introduce a second capture delimiter inside ours.
+  const text = String(body)
+    .replace(/<\/?relevant-memor(?:y|ies)\b[^>]*>/gi, "legacy memory wrapper")
+    .replace(/<\/?openviking-context\b[^>]*>/gi, "openviking context marker");
   return [
     "<openviking-context>",
     "Relevant memory from OpenViking. Use the search/read MCP tools to expand URIs.",
-    body,
+    text,
     "</openviking-context>",
   ].join("\n");
 }
@@ -488,7 +497,7 @@ export async function buildServerAssembledBlock(fetchJSON, cfg, query, options =
 
   const block = await recallViaContextFace(fetchJSON, cfg, query, { ...options, actorPeerId }, log);
   if (block !== null) return block;
-  return recallViaEndpoint(fetchJSON, cfg, query, actorPeerId, log);
+  return recallViaEndpoint(fetchJSON, cfg, query, { ...options, actorPeerId }, log);
 }
 
 /**
@@ -552,53 +561,65 @@ export function normalizeContextEntry(entry = {}) {
   };
 }
 
-async function recallViaContextFace(fetchJSON, cfg, query, options, log) {
-  const assembled = await fetchAssembledContext(fetchJSON, cfg, query, { ...options, log });
-  if (assembled === null) return null;
+/** Server relevance decisions and digest precedence are shared by every host. */
+export function selectRecallContent(result = {}) {
+  if (String(result.stats?.rewrite || "").toLowerCase() === "no_relevant") return "";
+  return String(result.digest || "").trim() || String(result.rendered || "").trim();
+}
 
-  const { rendered, entries } = assembled;
-  let digest = assembled.digest;
+function wantsLocalCompression(cfg, options) {
   const mode = String(cfg.recallRewrite || "off").toLowerCase();
-  if (String(assembled.stats?.rewrite || "").toLowerCase() === "no_relevant") {
-    log("recall_server_compression", { status: "empty" });
-    return "";
-  }
-  const wantsLocal = mode === "client" || (mode === "auto" && !digest);
-  if (wantsLocal && rendered && typeof options.runCompressor === "function") {
-    try {
-      const compression = await compressRecallContext({
-        query,
-        rendered,
-        entries,
-        cfg,
-        runCompressor: options.runCompressor,
-        cachePath: options.digestCachePath || stateFile("recall-digest.json"),
-        now: Date.now(),
-      });
-      log("recall_local_compression", { status: compression.status });
-      if (compression.status === "ok") digest = compression.context;
-      if (compression.status === "empty") return "";
-    } catch (err) {
-      log("recall_local_compression_failed", { error: String(err?.message || err) });
-    }
+  return (mode === "client" || mode === "auto")
+    && options.localCompressorAvailable !== false
+    && typeof options.runCompressor === "function";
+}
+
+// Context, legacy recall, and raw retrieval share the same result policy.
+// The host callback only runs its model; it never chooses a fallback or digest.
+async function finalizeRecall(result, cfg, query, options, log, shortContext) {
+  const selected = selectRecallContent(result);
+  if (String(result.stats?.rewrite || "").toLowerCase() === "no_relevant") return "";
+  const entries = (result.entries || []).map(normalizeContextEntry).filter((entry) => entry.uri);
+  const rendered = String(result.rendered || "").trim();
+  if (String(result.digest || "").trim() || !wantsLocalCompression(cfg, options)) return selected;
+  const fallback = shortContext ?? (entries.length ? formatFallback(entries, cfg).rendered : rendered);
+  const input = rendered || entries.map((entry) => `${entry.uri}\n${entry.text}`).join("\n");
+  if (!input) return "";
+  try {
+    const compression = await compressRecallContext({
+      query, rendered: input, shortContext: shortContext ?? (rendered || fallback),
+      entries, cfg, runCompressor: options.runCompressor,
+      cachePath: options.digestCachePath || stateFile("recall-digest.json"), now: Date.now(),
+    });
+    log("recall_local_compression", { status: compression.status });
+    if (compression.status === "ok") return compression.context;
+    if (compression.status === "empty") return "";
+  } catch (err) {
+    log("recall_local_compression_failed", { error: String(err?.message || err) });
   }
+  return fallback;
+}
 
-  const injected = digest || rendered;
-  if (!injected) return "";
-  return wrapContext(injected);
+async function recallViaContextFace(fetchJSON, cfg, query, options, log) {
+  const assembled = await fetchAssembledContext(fetchJSON, cfg, query, { ...options, log });
+  if (assembled === null) return null;
+  const text = await finalizeRecall(assembled, cfg, query, options, log);
+  return text ? wrapContext(text) : "";
 }
 
-async function recallViaEndpoint(fetchJSON, cfg, query, actorPeerId = "", log = () => {}) {
+async function recallViaEndpoint(fetchJSON, cfg, query, options, log) {
   const body = buildRecallEndpointBody(cfg);
   body.query = query;
-  const res = await postRecall(fetchJSON, body, { actorPeerId, log });
+  if (wantsLocalCompression(cfg, options)) {
+    body.max_chars = Math.max(1000, Number(cfg.recallCompressMaxInputChars || 18000));
+  }
+  const res = await postRecall(fetchJSON, body, { actorPeerId: options.actorPeerId, log });
   if (!res.ok) {
     log("recall_endpoint_fallback", { status: res.status || 0 });
     return null;
   }
-  const rendered = String(res.result?.rendered || "").trim();
-  if (!rendered) return "";
-  return wrapContext(rendered);
+  const text = await finalizeRecall(res.result || {}, cfg, query, options, log);
+  return text ? wrapContext(text) : "";
 }
 
 export async function postRecall(fetchJSON, body, opts = {}) {
@@ -711,7 +732,7 @@ async function recallForPeer(fetchJSON, cfg, query, options = {}) {
 
   const recallLimit = Math.max(1, Number(cfg.recallLimit || DEFAULT_CONTEXT_LIMIT));
   const perSourceLimit = Math.max(recallLimit * 2, 8);
-  const raw = await searchAllSources(fetchJSON, trimmed, perSourceLimit, actorPeerId, log);
+  const raw = await searchAllSources(fetchJSON, cfg, trimmed, perSourceLimit, { ...options, actorPeerId }, log);
   if (raw.length === 0) return emptyRecall("no_results");
 
   const profile = buildQueryProfile(trimmed);
@@ -727,5 +748,25 @@ async function recallForPeer(fetchJSON, cfg, query, options = {}) {
   });
 
   if (picked.length === 0) return emptyRecall("filtered_out");
-  return buildFallbackInjectionBlock(fetchJSON, picked, cfg, actorPeerId, log);
+  const local = wantsLocalCompression(cfg, options);
+  const inputLimit = Math.max(1000, Number(cfg.recallCompressMaxInputChars || 18000));
+  const contentCfg = local ? { ...cfg, recallPreferAbstract: false, recallMaxContentChars: inputLimit } : cfg;
+  const entries = await Promise.all(picked.map(async (item) => ({
+    ...item, text: await resolveItemContent(fetchJSON, item, contentCfg, actorPeerId),
+  })));
+  const fallback = formatFallback(entries, cfg, log);
+  let text = await finalizeRecall({
+    rendered: local ? entries.map((item) => `${item.uri}\n${item.text}`).join("\n").slice(0, inputLimit) : fallback.rendered,
+    entries,
+  }, cfg, trimmed, options, log, fallback.rendered);
+  if (estimateTokens(wrapContext(text)) > Math.max(200, Number(cfg.recallTokenBudget || 2000))) {
+    text = fallback.rendered;
+  }
+  if (!text) return emptyRecall("no_results");
+  const unchanged = text === fallback.rendered;
+  return {
+    block: wrapContext(text), contentCount: unchanged ? fallback.contentCount : 1,
+    hintCount: unchanged ? fallback.hintCount : 0,
+    budgetUsed: estimateTokens(wrapContext(text)), stage: "ranked",
+  };
 }

package/shared/uri-guard.mjs

@@ -91,6 +91,33 @@ export function buildGuardNotice(uri, hint = {}) {
   return lines.join("\n");
 }
 
+const SKILL_URI_RE = /^viking:\/\/(?:~|user\/[^/]+|agent)\/skills(?:\/|$)/i;
+const SHARED_SKILL_URI_RE = /^viking:\/\/agent\/skills(?:\/|$)/i;
+// The skills root, a skill directory, or its SKILL.md; anything deeper is a helper file.
+const SKILL_MD_URI_RE = /^viking:\/\/(?:~|user\/[^/]+|agent)\/skills(?:\/[^/]+(?:\/SKILL\.md)?)?\/?$/i;
+
+/**
+ * Skills are installed through the MCP add_skill tool: write and edit refuse
+ * the user's own skills subtree, and under the shared root they would bypass
+ * installation.
+ */
+export function isSkillUri(uri) {
+  return SKILL_URI_RE.test(String(uri || ""));
+}
+
+/**
+ * The add_skill call that replaces a write or edit aimed at `uri`. A shared
+ * skill goes back to the shared root: without target_uri, add_skill makes a
+ * private copy that then shadows it.
+ */
+export function addSkillExample(uri, { call = "add_skill", edited = false } = {}) {
+  const value = String(uri || "");
+  const shared = SHARED_SKILL_URI_RE.test(value) ? ', target_uri="viking://agent/skills"' : "";
+  return SKILL_MD_URI_RE.test(value)
+    ? `${call}(data="<the full ${edited ? "edited " : ""}SKILL.md text>"${shared})`
+    : `${call}(path="<local skill folder or .zip with the changed files>"${shared})`;
+}
+
 /** The hints a host gets when it names no table of its own. */
 export const DEFAULT_TOOL_HINTS = {
   read: {
@@ -110,12 +137,18 @@ export const DEFAULT_TOOL_HINTS = {
     ),
   },
   edit: {
-    tool: "OpenViking MCP edit",
-    example: (uri) => `edit(uri="${uri}", old_string="...", new_string="...")`,
+    tool: (uri) => (isSkillUri(uri) ? "OpenViking MCP add_skill" : "OpenViking MCP edit"),
+    example: (uri) => (
+      isSkillUri(uri)
+        ? addSkillExample(uri, { edited: true })
+        : `edit(uri="${uri}", old_string="...", new_string="...")`
+    ),
   },
   write: {
-    tool: "OpenViking MCP write",
-    example: (uri) => `write(uri="${uri}", content="...")`,
+    tool: (uri) => (isSkillUri(uri) ? "OpenViking MCP add_skill" : "OpenViking MCP write"),
+    example: (uri) => (
+      isSkillUri(uri) ? addSkillExample(uri) : `write(uri="${uri}", content="...")`
+    ),
   },
   bash: {
     tool: "OpenViking MCP read or search",
@@ -152,7 +185,7 @@ function resolveGuardedUri(toolName, input, { hints = DEFAULT_TOOL_HINTS } = {})
     uri,
     shell: SHELL_TOOL_NAMES.has(name),
     hint: {
-      tool: hint.tool,
+      tool: typeof hint.tool === "function" ? hint.tool(uri, input) : hint.tool,
       example: typeof hint.example === "function" ? hint.example(uri, input) : hint.example,
     },
   };

package/skills/openviking-memory/SKILL.md

@@ -91,6 +91,8 @@ Do not invent other keys or commands for this: that file is the whole interface,
 - Reusable task-execution write-ups (Experiences) have a dedicated tool pair,
   `search_experience` / `read_experience`, described in the
   `ov-experience-memory` skill.
+- Skills stored in OpenViking (the `<available-skills>` list, `add_skill`,
+  moving local skills in) are covered by the `openviking-skills` skill.
 
 ## Beyond the MCP tools
 

package/skills/openviking-skills/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: openviking-skills
+description: >
+  Find, use, create, install, share, update, and migrate agent skills stored in
+  OpenViking (viking://~/skills and viking://agent/skills). Use it when a
+  search result, or the session's <available-skills> list where the harness
+  injects one, names a skill that fits the task; when a task looks like one a
+  stored skill would cover; when the user asks to write, save, install, or share a skill from
+  text, a Git repository, or a local folder; when a skill should work in every
+  harness and on every machine; or when the user wants to move local skills
+  (~/.claude/skills, ~/.agents/skills, ~/.cursor/skills) into OpenViking —
+  "upload my skills", "save this as a skill", "迁移本地 skill", "把 skill 存到
+  OpenViking", "新建一个 skill". Covers the add_skill tool, running a skill's
+  helper files, and which local skills must stay local.
+---
+
+# OpenViking Skills
+
+OpenViking stores skills as data, the same way it stores memories, so a skill
+saved there reaches every harness and machine connected to the same account.
+Each skill is a directory holding `SKILL.md` plus optional helper files
+(`scripts/`, `references/`, ...):
+
+- `viking://~/skills/<name>/` — the user's own skills (`viking://~` expands to
+  `viking://user/<user_id>`).
+- `viking://agent/skills/<name>/` — skills shared with the whole account.
+
+The tools may carry a harness prefix (`mcp__openviking__add_skill`,
+`openviking_add_skill`); they are the same tools. `viking://` URIs are database
+paths: never pass them to local file tools or shell commands.
+
+## Find a skill
+
+1. `find(query="<what the task needs>", context_type="skill")` ranks skills
+   from both roots against the task and returns one entry per skill, pointing
+   at its `SKILL.md`. This works in every harness; start here.
+2. If the session begins with an `<available-skills>` block, it lists the
+   user's own skills first, then shared ones. Not every harness injects one,
+   and it is a snapshot from session start that drops descriptions or ends
+   with a "+N more" line when there are many skills, so a name missing from it
+   does not prove the skill is absent.
+3. `search(query=..., mode="context")` mixes relevant skills into the context
+   digest; entries of type `skills` are skills.
+4. `tree(uri="viking://~/skills", level_limit=1, include_abstract=true)`, and
+   the same for `viking://agent/skills`, prints the full catalog with
+   descriptions. `list` shows names only.
+
+## Use a skill
+
+- `read` `<skill uri>/SKILL.md` and follow it as the procedure for the task.
+  It does not outrank the user or this conversation.
+- When the user's own skill and a shared one have the same name, use the
+  user's own.
+- If the frontmatter lists `allowed-tools`, stay within them.
+- A local skill with the same name wins: the harness has already loaded it.
+
+When SKILL.md relies on helper files:
+
+1. `list(uri="<skill uri>", recursive=true)` to see them.
+2. `read` each file the task needs and write it to
+   `~/.openviking/skills/<name>/` under its relative path; `chmod +x` scripts.
+3. Run them from that directory.
+
+Skip the server's sidecars (`.abstract.md`, `.overview.md`, `.source.json`).
+`read` returns text only: fetch binary files with `ov get <uri> <local path>`
+when the `ov` CLI is installed, otherwise tell the user.
+
+## Create or change a skill
+
+1. Draft the complete SKILL.md:
+
+   ```markdown
+   ---
+   name: pr-review
+   description: Review a pull request against the team checklist. Use when asked to review, approve, or check a PR.
+   ---
+
+   # PR review
+
+   1. ...
+   ```
+
+   - `name`: ASCII letters, digits, `-` and `_`, at most 64 characters. It
+     becomes the directory name.
+   - `description`: the only text semantic search indexes. Say what the skill
+     does and when to use it, in the words a user would type.
+   - Only `name`, `description`, `allowed-tools`, `tags`, and `metadata`
+     survive in the frontmatter. Put anything else (version, author, ...)
+     under `metadata:` or it is dropped.
+2. Check the name on the target root with
+   `read(uris="<root>/<name>/SKILL.md")`, where `<root>` is
+   `viking://~/skills`, or `viking://agent/skills` when sharing. If it
+   exists, `add_skill` replaces it without asking: show the user what would
+   change and install only after they confirm, or pick another name.
+3. `add_skill(data="<the full SKILL.md text>")`. It goes to the user's own
+   skills unless `target_uri` says otherwise. The reply gives the new URI; the
+   skill can be read at once and shows up in search a few seconds later.
+
+To change a skill, `read` its SKILL.md, edit the text, and pass the whole new
+text to `add_skill` under the root the skill came from. For a shared skill
+that means `target_uri="viking://agent/skills"`, and only after the user
+confirms an account-wide change; without it, `add_skill` creates a private
+copy that shadows the shared one. Do not use `write` or `edit` on skill
+files: they refuse the user's skills subtree and would bypass installation
+under the shared root. A reinstall does not delete helper files the new
+version dropped.
+
+## Install from a repository or a local folder
+
+- **Git**: `add_skill(path="https://github.com/org/repo")`, or a
+  `.../tree/<branch>/<dir>` URL for one directory. For a repository with
+  several skills, call it with `list_only=true` first, then pass
+  `skills=["a", "b"]`. Install from a source the user did not name only after
+  asking them.
+- **Local folder or zip**: `add_skill(path="/abs/path/to/skill")` returns a
+  one-time upload URL. Every file in the archive is stored with the skill,
+  so zip without VCS data and secrets:
+  `cd <parent> && rm -f /tmp/<name>.zip && zip -r /tmp/<name>.zip <name> -x '*/.git/*' '*/.env*' '*/node_modules/*' '*/.DS_Store'`,
+  then `curl -sS -F "file=@/tmp/<name>.zip" "<upload url>"` and delete the
+  archive. The response lists the installed URIs; nothing else to call. A
+  skill that is only a SKILL.md can go through `data=` instead.
+- **`ov` CLI**, when installed: `ov skills add <path or URL>` (`-l` lists,
+  `-s a,b` selects, `-p viking://agent/skills` shares, `-y` skips the prompt).
+
+## Share with the account
+
+Pass `target_uri="viking://agent/skills"` to `add_skill`. Do this only when the
+user asks for a team- or account-wide skill: everyone on the account sees it.
+
+## Delete a skill
+
+Prefer `ov skills remove <name>` or OpenViking Studio; both also drop the
+skill's stored privacy values. `forget(uri="<skill uri>", recursive=true)`
+removes the directory but leaves those values behind, so use it only after the
+user confirms the exact URI.
+
+To rename a skill, install it under the new name with `add_skill` and remove
+the old one. Moving or copying the directory does not rename it: the skill's
+own metadata still carries the old name.
+
+## Move local skills into OpenViking
+
+Run this only when the user asks. Nothing is uploaded without their approval
+of that skill.
+
+1. **List candidates.** Read each `*/SKILL.md` under:
+   - Claude Code: `~/.claude/skills/`, `<repo>/.claude/skills/`
+   - Codex: `~/.agents/skills/`, `<repo>/.agents/skills/`
+   - Cursor: `~/.cursor/skills/`
+2. **Classify.** A skill is *environment-bound*, stays local, and is never
+   offered for upload when any of these holds:
+   - a plugin or marketplace ships it (its real path contains `/plugins/` or
+     `/marketplaces/`), so the plugin reinstalls it on update;
+   - the directory is a symlink or resolves outside the skills folder, the way
+     CLI installers such as lark-cli link their own skills;
+   - it needs a local binary, CLI, or service to work (for example
+     `metadata.<vendor>.requires.bins`, or steps that run a vendor CLI);
+   - its name carries a vendor prefix such as `lark-`, `volcengine-`, `ve-`,
+     `claude-`, or `mcp-` (a hint, not proof: check the body);
+   - it is `openviking-skills` or `openviking-memory`.
+
+   For the rest, list the whole folder, hidden files included
+   (`find <dir> -type f`), and check helper files as well as SKILL.md. Mark
+   a skill "clean up first" when any file holds credentials, tokens, `.env`
+   files, internal hostnames, or personal absolute paths. Also flag
+   frontmatter keys other than `name`, `description`, `allowed-tools`,
+   `tags` and `metadata` (for example `disable-model-invocation`,
+   `user-invocable`, `context`, `model`): OpenViking drops them, which can
+   change how the skill behaves. The rest are portable.
+3. **Confirm.** Show a table of name, path, verdict, one-line reason, and
+   target (`viking://~/skills` unless the user wants sharing). The user may
+   flip any verdict. Upload only what they approve.
+4. **Upload.** A skill that is only a SKILL.md goes through
+   `add_skill(data=...)`; a folder with helper files goes through the zip
+   upload above, or `ov skills add <dir>` when the CLI is installed
+   (`ov skills validate <dir>` first catches format errors). OpenViking
+   requires `name` and `description` in the frontmatter; when a local skill
+   lacks them, fix a copy in a temporary folder (the name is the folder
+   name), never the user's own file.
+5. **Verify.** `tree(uri="viking://~/skills", level_limit=1, include_abstract=true)`
+   should list every uploaded name. Then `remember` which skills were migrated
+   and which were skipped, so a later session does not ask again.
+6. **Keep the local copies** unless the user asks to remove them; a local
+   skill with the same name just takes precedence in that harness. Create new
+   skills with `add_skill` from now on.
+
+## Boundaries
+
+- Never upload environment-bound skills, and never delete the user's local
+  skill files on your own.
+- Never put credentials in a SKILL.md; the shared root is visible to the whole
+  account.
+- Memory search and writing are covered by the `openviking-memory` skill.
+- If the server has no `add_skill` tool (an older OpenViking), use
+  `ov skills add` when the CLI is installed; otherwise tell the user the server
+  needs an upgrade. Do not fall back to `write`, `edit`, or `add_resource`:
+  under the user's own root they are refused, and under `viking://agent/skills`
+  a write lands as an ordinary file that never goes through installation.

package/skills.mjs

@@ -4,7 +4,7 @@ import * as skillFilesystem from "@deepseek-ai/dsh-skill-filesystem";
 /** Provider name on `ctx.skills`; must not collide with DSH's own `filesystem`. */
 export const SKILL_PROVIDER_NAME = "openviking";
 
-/** The shared `openviking-memory` skill, vendored from examples/skills. */
+/** The shared `openviking-memory` and `openviking-skills` skills, vendored from examples/skills. */
 export const SKILLS_DIR = fileURLToPath(new URL("./skills", import.meta.url));
 
 export function buildSkillsConfig() {

package/uri-guard.mjs

@@ -1,7 +1,7 @@
 import { boundContextSummary } from "@deepseek-ai/dsh-llm";
 import { pluginMessage } from "./capture.mjs";
 import { MCP_SERVER_NAME } from "./config.mjs";
-import { evaluateUriGuard, evaluateUriNotice } from "./shared/uri-guard.mjs";
+import { addSkillExample, evaluateUriGuard, evaluateUriNotice, isSkillUri } from "./shared/uri-guard.mjs";
 
 /** Model-facing name of a bridged OpenViking MCP tool. */
 const mcp = rawName => `mcp__${MCP_SERVER_NAME}__${rawName}`;
@@ -25,12 +25,18 @@ const GUARDED_TOOLS = {
     example: uri => `${mcp("read")}(uris="${uri}")`,
   },
   edit: {
-    tool: mcp("edit"),
-    example: uri => `${mcp("edit")}(uri="${uri}", old_string="...", new_string="...")`,
+    tool: uri => (isSkillUri(uri) ? mcp("add_skill") : mcp("edit")),
+    example: uri =>
+      isSkillUri(uri)
+        ? addSkillExample(uri, { call: mcp("add_skill"), edited: true })
+        : `${mcp("edit")}(uri="${uri}", old_string="...", new_string="...")`,
   },
   write: {
-    tool: mcp("write"),
-    example: uri => `${mcp("write")}(uri="${uri}", content="...")`,
+    tool: uri => (isSkillUri(uri) ? mcp("add_skill") : mcp("write")),
+    example: uri =>
+      isSkillUri(uri)
+        ? addSkillExample(uri, { call: mcp("add_skill") })
+        : `${mcp("write")}(uri="${uri}", content="...")`,
   },
   str_replace_editor: {
     tool: "the OpenViking MCP tools",