openviking-skills

# 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/` - pi: `~/.pi/agent/skills/`, `<repo>/.pi/skills/` - OpenCode: `~/.config/opencode/skills/`, `<repo>/.opencode/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.