@openviking/opencode-plugin 2026.9.22 → 2026.9.23

package/INSTALL-ZH.md

@@ -113,6 +113,8 @@ export { OpenVikingPlugin, default } from "./openviking/index.mjs"
       "commitTokenThreshold": 20000,
       "commitKeepRecentCount": 10,
       "profileTokenBudget": 10000,
+      "skillCatalog": true,
+      "skillCatalogTokenBudget": 1200,
       "resumeContextBudget": 32000
     }
   }
@@ -124,6 +126,8 @@ export { OpenVikingPlugin, default } from "./openviking/index.mjs"
 `recallLimit` 是遗留的配额缩放输入，不是最终结果上限。显式设置为
 1 到 5 时，有效总配额仍为 6，因为六个 coding 分类会各保留一个检索槽位。
 
+每个 session 的第一条消息会带上一个隐藏的 `<openviking-context source="session-start">` 块，里面有你的 `profile.md`、`preferences/` 和 `entities/` 记忆索引，以及 `<available-skills>` skill 清单：先列你自己的 skill，再列 `viking://agent/skills` 下账号共享的 skill；共享 skill 与你自己的 skill 同名时不再列出。`profileTokenBudget` 只管 profile 和记忆索引，skill 清单有独立的预算 `skillCatalogTokenBudget`（默认 `1200`，环境变量 `OPENVIKING_SKILL_CATALOG_TOKEN_BUDGET`）。放不下描述时只列 skill 名，名字也列不全时末尾注明 `... +N more`；连一个名字都放不下时，只写一行 skill 总数。设置 `skillCatalog: false`（`OPENVIKING_SKILL_CATALOG=0`）或把预算设为 `0` 即可关闭 skill 清单；没有 skill，或服务端没有 `GET /api/v1/skills` 接口时，这一块会直接省略。
+
 推荐通过环境变量提供 API Key，而不是写入配置文件：
 
 ```bash
@@ -166,7 +170,6 @@ OpenCode 的 `mcp.openviking` 配置。
 - `openviking_read`、`openviking_list`、`openviking_tree`、`openviking_grep`、`openviking_glob`
 - `openviking_remember`、`openviking_write`、`openviking_edit`、`openviking_add_resource`、`openviking_add_skill`
 - `openviking_list_watches`、`openviking_cancel_watch`、`openviking_forget`、`openviking_health`
-- `openviking_list_watches`、`openviking_cancel_watch`
 
 如果行为异常，先查看运行时文件：
 
@@ -196,6 +199,7 @@ curl http://localhost:1933/health
 - `openviking_write`：创建、覆盖或追加 `viking://` 文件
 - `openviking_edit`：对 `viking://` 文件做精确字符串替换
 - `openviking_add_resource`：添加 URL、本地文件、sitemap 或 feed
+- `openviking_add_skill`：用完整的 `SKILL.md` 文本（`data`）创建或替换 skill，或从 Git URL、本地 `SKILL.md`、skill 目录或 `.zip`（`path`）安装；传 `target_uri="viking://agent/skills"` 则共享给整个账号
 - `openviking_forget`：在用户明确确认后删除 `viking://` URI
 - `openviking_list_watches` / `openviking_cancel_watch`：查看或取消资源 watch
 - `openviking_health`：检查 OpenViking server 健康状态
@@ -207,6 +211,7 @@ curl http://localhost:1933/health
 - 枚举文件用 `openviking_glob`
 - 读取内容用 `openviking_read`
 - 探索目录结构用 `openviking_list`
+- 照 `<available-skills>` 里的某个 skill 做事之前，先用 `openviking_read` 读它的 `SKILL.md`；创建、安装或共享 skill 用 `openviking_add_skill`
 - 删除前必须先获得用户明确确认，再调用 `openviking_forget`
 - 如果 agent 误用 OpenCode 本地 `read`、`glob`、`grep` 工具访问 `viking://` URI，插件会阻止这次本地文件系统调用，并提示改用 MCP 工具。
 - `bash` 命令里带 `viking://` URI 时照常执行，插件会在输出末尾附一段提示，建议改用 MCP 工具；URI 本来就是命令参数时，agent 可以忽略这段提示。

package/INSTALL.md

@@ -113,6 +113,8 @@ Example configuration:
       "commitTokenThreshold": 20000,
       "commitKeepRecentCount": 10,
       "profileTokenBudget": 10000,
+      "skillCatalog": true,
+      "skillCatalogTokenBudget": 1200,
       "resumeContextBudget": 32000
     }
   }
@@ -125,6 +127,8 @@ Keys in `plugin` apply to every harness; keys in `plugin.opencode` apply to this
 Explicit values from 1 through 5 produce an effective total quota of 6 because
 each coding category keeps one retrieval slot.
 
+The first message of each session carries a hidden `<openviking-context source="session-start">` block with your `profile.md`, the `preferences/` and `entities/` memory indexes, and an `<available-skills>` catalog: your own skills first, then the account-shared ones under `viking://agent/skills`, leaving out a shared skill that has the same name as one of yours. `profileTokenBudget` covers the profile and memory indexes; the catalog has its own budget, `skillCatalogTokenBudget` (default `1200`, `OPENVIKING_SKILL_CATALOG_TOKEN_BUDGET`). When the descriptions do not fit, the catalog lists names only (with a `... +N more` tail if even the names do not all fit), and when not even one name fits, a one-line count. `skillCatalog: false` (`OPENVIKING_SKILL_CATALOG=0`) or a budget of `0` turns the catalog off; with no skills, or on a server without `GET /api/v1/skills`, it is left out.
+
 It is recommended to provide the API key through an environment variable instead of writing it into the configuration file:
 
 ```bash
@@ -163,7 +167,6 @@ In a new OpenCode session, ask the agent to browse OpenViking memory or search f
 - `openviking_read`, `openviking_list`, `openviking_tree`, `openviking_grep`, `openviking_glob`
 - `openviking_remember`, `openviking_write`, `openviking_edit`, `openviking_add_resource`, `openviking_add_skill`
 - `openviking_list_watches`, `openviking_cancel_watch`, `openviking_forget`, `openviking_health`
-- `openviking_list_watches`, `openviking_cancel_watch`
 
 If anything looks wrong, check the runtime files:
 
@@ -193,7 +196,7 @@ The plugin registers OpenViking's stdio MCP proxy through OpenCode config. The s
 - `openviking_write`: create, overwrite, or append to a `viking://` file.
 - `openviking_edit`: exact string replacement in a `viking://` file.
 - `openviking_add_resource`: add a URL, local file, sitemap, or feed.
-- `openviking_add_skill`: create, install, or replace an agent skill.
+- `openviking_add_skill`: create or replace a skill from its full `SKILL.md` text (`data`), or install one from a Git URL or a local `SKILL.md`, skill directory, or `.zip` (`path`); `target_uri="viking://agent/skills"` shares it with the account.
 - `openviking_forget`: delete a `viking://` URI after explicit user confirmation.
 - `openviking_list_watches` / `openviking_cancel_watch`: inspect or cancel resource watches.
 - `openviking_health`: check OpenViking server health.
@@ -205,6 +208,7 @@ Usage guidance:
 - Use `openviking_glob` to enumerate files.
 - Use `openviking_read` to read content.
 - Use `openviking_list` to explore directory structure.
+- Before following a skill from `<available-skills>`, read its `SKILL.md` with `openviking_read`; create, install, or share a skill with `openviking_add_skill`.
 - Before deleting anything, obtain explicit user confirmation first; then call `openviking_forget`.
 - If an agent tries to use OpenCode's local `read`, `glob`, or `grep` tools on a `viking://` URI, the plugin blocks that call and points it to the MCP tools.
 - A `bash` command that contains a `viking://` URI still runs; the plugin appends a notice pointing to the MCP tools to its output, which the agent can ignore when the URI is intentional.

package/README.md

@@ -13,6 +13,7 @@ The plugin uses OpenCode hooks for lifecycle behavior and registers OpenViking's
 ## What It Does
 
 - Injects indexed `viking://resources/` repositories into the system prompt.
+- On the first message of each session, injects your profile, memory indexes, and an `<available-skills>` catalog of your own and account-shared OpenViking skills.
 - Exposes the same OpenViking MCP tools used by the Claude Code and Codex memory plugins.
 - Maps each OpenCode session to an OpenViking session.
 - Captures user and assistant text messages into OpenViking.
@@ -139,6 +140,8 @@ Behaviour knobs live in `~/.openviking/ovcli.conf` beside the connection fields,
       "commitTokenThreshold": 20000,
       "commitKeepRecentCount": 10,
       "profileTokenBudget": 10000,
+      "skillCatalog": true,
+      "skillCatalogTokenBudget": 1200,
       "resumeContextBudget": 32000
     }
   }
@@ -152,6 +155,8 @@ Explicit values from 1 through 5 produce an effective total quota of 6 because
 each coding category keeps one retrieval slot. Use Context `quotas` directly
 when exact category ceilings are required.
 
+`profileTokenBudget` covers the profile and memory indexes in the session-start block. The `<available-skills>` catalog comes from one `GET /api/v1/skills` and has its own budget, `skillCatalogTokenBudget` (default `1200`, `OPENVIKING_SKILL_CATALOG_TOKEN_BUDGET`). Your own skills are listed first, then the ones shared under `viking://agent/skills`, leaving out a shared skill that has the same name as one of yours; each description is cut to about 40 tokens. When the descriptions do not fit, the catalog lists names only (with a `... +N more` tail if even the names do not all fit), and when not even one name fits, a one-line count. The agent reads a skill's `SKILL.md` with `openviking_read` before following it. `skillCatalog: false` (`OPENVIKING_SKILL_CATALOG=0`) or a budget of `0` turns the catalog off; with no skills, or on a server without `GET /api/v1/skills`, it is left out.
+
 API keys are resolved from environment variables or `~/.openviking/ovcli.conf` and sent as `Authorization: Bearer ...` by both hooks and the MCP proxy. Recall goes through the server-side context face (`POST /api/v1/search/search` with `mode="context"`), falling back to the deprecated `/api/v1/search/recall` on older deployments. `account` and `user` are trusted-mode identity
 headers sent as `X-OpenViking-Account` and `X-OpenViking-User`; an `api_key`
 server reads both out of the key, so the plugin withholds them there.
@@ -212,7 +217,7 @@ OpenCode sees the OpenViking MCP server as `openviking`, so tool names are names
 - `openviking_write`: create, overwrite, or append to a `viking://` file.
 - `openviking_edit`: exact string replacement in a `viking://` file.
 - `openviking_add_resource`: add a URL, local file, sitemap, or feed.
-- `openviking_add_skill`: create, install, or replace an agent skill.
+- `openviking_add_skill`: create or replace a skill from its full `SKILL.md` text (`data`), or install one from a Git URL or a local `SKILL.md`, skill directory, or `.zip` (`path`); `target_uri="viking://agent/skills"` shares it with the account.
 - `openviking_forget`: delete a `viking://` URI after explicit user confirmation.
 - `openviking_list_watches` / `openviking_cancel_watch`: inspect or cancel resource watches.
 - `openviking_health`: check OpenViking server health.

package/lib/session-inject.mjs

@@ -18,7 +18,7 @@ export function createSessionInject({ config, sessionManager }) {
       fetchJSON(config, endpoint, init, { ...options, actorPeerId, timeoutMs: 10000 })
 
     const parts = []
-    const profile = await buildProfileBlock(clientFetch, config.profileTokenBudget, actorPeerId)
+    const profile = await buildProfileBlock(clientFetch, config.profileTokenBudget, actorPeerId, config)
     if (profile?.block) parts.push(profile.block)
 
     const archive = await fetchArchiveBlock(clientFetch, ovSessionId, config.resumeContextBudget)

package/lib/shared/config-schema.mjs

@@ -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" },
@@ -228,6 +243,7 @@ export const HARNESS_KEYS = {
   claudeCode: "claude_code",
   codex: "codex",
   cursor: "cursor",
+  kimicode: "kimicode",
   trae: "trae",
   traeCn: "trae_cn",
   zcode: "zcode",

package/lib/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/lib/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openviking/opencode-plugin",
-  "version": "2026.9.22",
+  "version": "2026.9.23",
   "author": "@openviking",
   "description": "Unified OpenCode plugin for OpenViking repository retrieval and long-term memory",
   "type": "module",
@@ -45,5 +45,5 @@
     "code-search"
   ],
   "license": "Apache-2.0",
-  "openvikingSourceCommit": "6b127eb92ccdb627eb343a959f0e4fe0dbf9a16c"
+  "openvikingSourceCommit": "03391bae4335eacf440a62d942f3951de6a63cbe"
 }