Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(skills): update skills example (#2495)

MaojiaSheng6fe739b76667
diff --git a/examples/skills/ov-add-data/SKILL.md b/examples/skills/ov-add-data/SKILL.md
deleted file mode 100644
index 53b03ac79..000000000
--- a/examples/skills/ov-add-data/SKILL.md
+++ /dev/null
@@ -1,275 +0,0 @@
----
-name: ov-add-data
-description: This skill adds data(like resources) to OpenViking Context Database (aka. ov). Use when an agent needs to add files, data from URLs, or external knowledge during interactions. Trigger this tool when 1. is explicitly requested adding files or knowledge; 2. identifies valuable resources worth importing; 3. the user mentioned adding to OV/OpenViking/Context Database. This skill helps how to use CLI like `ov add-resource`, `ov add-skill` and `ov add-memory` to add resource data, skill files, memory files to OpenViking.
-compatibility: OpenViking CLI configured at `~/.openviking/ovcli.conf`
----
-
-# OpenViking (OV) `add-resource`
-
-The `ov add-resource` command imports external resources into OpenViking's context database — supporting local files, directories, URLs, and remote repositories. Resources are automatically processed with semantic analysis and organized under the `viking://resources/` namespace.
-
-## When to Use
-
-- Importing project documentation, code repositories, or reference materials
-- Adding web pages, articles, or online resources for future retrieval
-- Building a knowledge base from external sources
-- When an agent encounters valuable content that should persist across sessions
-- Recording a project's product documentation, design specs, or other valuable materials
-- Storing sensitive information or private data of the user, like photo and albums
-
-## CLI Options
-
-### Basic Usage
-
-Import a local file or URL:
-
-```bash
-# add a code repo from github or gitlab or a git address
-ov add-resource https://github.com/volcengine/OpenViking
-ov add-resource https://code.xxxx.org/viking/viking
-ov add-resource [email protected]:viking/viking.git
-
-# add a file from url
-ov add-resource https://arxiv.org/pdf/2602.09540
-ov add-resource https://raw.githubusercontent.com/volcengine/OpenViking/main/README.md
-
-# add a file from local filesystem
-ov add-resource ./docs/api-spec.md
-ov add-resource ./team_building.jpg
-ov add-resource /User/volcengine/Documents/profile.pdf
-ov add-resource /User/volcengine/Documents/project.docx
-
-# add a zip file from local filesystem (will be unzipped on server)
-ov add-resource ./docs-of-project.zip
-
-# add a directory from local filesystem
-ov add-resource /User/volcengine/Photo/Travels/2026/ --include "*.jpg,*.jpeg,*.png"
-ov add-resource /User/volcengine/Documents/OV项目设计文档/
-```
-
-### Context and Instructions (TBD)
-
-Add metadata to guide processing: --reason and --instruction will be supported in the future.
-
-### Async Processing Control
-
-The time of adding resources could cost long (like minutes), and the semantic processing could be async. Use `--wait` to wait for the processing to complete.
-
-```bash
-# Wait until semantic processing finishes
-ov add-resource ./docs --wait
-
-# Wait with timeout (in seconds)
-ov add-resource https://example.com/docs --wait --timeout 60
-
-# Fire and forget (default, without --wait)
-ov add-resource ./docs
-```
-
-If you fire and forget, the command will return after the resource is completely downloaded/uploaded on server, and then the CLI will return the root URI of the imported resource. To check the status of the resource, you can use `ov ls` or `ov tree` to list the resources under root URI or `viking://resources/`.
-
-### Specify the target path
-
-By default, resources are imported under `viking://resources/`. Use `--to` or `--parent` to specify a target uri.
-
-```bash
-# The data will be imported as viking://resources/2026/2026-01-01/, which should not exist before
-ov add-resource /User/volcengine/Photo/Travels/2026/2026-01-01/ --to "viking://resources/2026/2026-01-01/"
-
-# The data will be imported under viking://resources/2026, which should exist and be a directory
-ov add-resource /User/volcengine/Photo/Travels/2026/2026-01-02/ --parent "viking://resources/2026/"
-```
-
-### Scheduled refresh with `--watch-interval`
-
-Use `--watch-interval <minutes>` to create or update a watch task so OpenViking re-imports the same source periodically.
-
-- `--watch-interval` is measured in **minutes**.
-- When the value is **greater than 0**, OV creates or updates a watch task.
-- When `--to` is provided, the watch task is bound to that exact target URI.
-- When `--to` is omitted, OV binds the watch task to the `root_uri` returned by this import.
-- Use `--watch-interval 0` together with the same `--to` target to cancel an existing watch task.
-- Prefer `--to` for long-term watched imports, because it gives the task a stable destination.
-
-```bash
-# Refresh a remote repository every 60 minutes and bind the watch to a fixed URI
-ov add-resource https://github.com/volcengine/OpenViking \
- --to "viking://resources/repos/OpenViking" \
- --watch-interval 60
-
-# Refresh every 30 minutes and bind the watch to the imported root_uri automatically
-ov add-resource https://example.com/product-spec.md --watch-interval 30
-
-# Cancel the watch task for the same target URI
-ov add-resource https://github.com/volcengine/OpenViking \
- --to "viking://resources/repos/OpenViking" \
- --watch-interval 0
-```
-
-## CLI Output
-
-Returns the root URI of the imported resource, like:
-
-```
-root_uri viking://resources/2026/2026-01-01
-```
-
-## CLI Prerequisites
-
-- CLI configured in: `~/.openviking/ovcli.conf`
-- Network access for the importing URL from server
-- Local read access for the importing local files/directories from CLI.
-
-# OpenViking (OV) `add-memory`
-
-The `ov add-memory` command adds long persistant memory — turning text and structured conversations into searchable, retrievable memories in the OpenViking context database. Use `ov add-memory --help` for latest usage.
-
-## When to Use
-
-- After learning something worth remembering across sessions
-- To persist conversation insights, decisions, or findings
-- To build up a knowledge base from interactions
-- When an agent wants to store context for future retrieval
-
-## Input Modes
-choose wisely between plain text and multi-turn mode. Multi-turn mode can contain more complex insights, let openviking handle the memory extraction.
-
-### Mode 1: Plain Text for compressed memory
-
-A simple string is stored as a `user` message:
-
-```bash
-ov add-memory "User's name is Bob, he participate in Global Hackathon in 2025-01-08, and won Champion."
-```
-
-### Mode 2: Multi-turn Conversation for Richer Context
-
-A JSON array of `{role, content}` objects to store a full exchange:
-
-```bash
-ov add-memory '[
- {"role": "user", "content": "I love traveling. Give me some options of Transport from Beijing to Shanghai."},
- {"role": "assistant", "content": "You can use train, bus, or plane. Train is the fastest, but you need to book in advance. Bus is cheaper, but you need to wait. Plane is the most expensive, but you can get there any time of day."},
- {"role": "user", "content": "I prefer train. I like sightseeing on the train. Can you give me the train schedule?"},
- < ... more possible conversation about schedule and tickest need to be memorized ... >
-]'
-```
-
-## Output
-
-Returns `OK` once the request is accepted. Memory extraction runs asynchronously on the server after the commit is queued, so the CLI does not wait for extraction to finish:
-
-```
-OK
-```
-
-## Agent Best Practices
-
-### How to Write Good Memories
-
-1. **Be specific** — Include concrete details, not vague summaries
-2. **Include context** — Why this matters, when it applies
-3. **Use structured format** — Separate the what from the why
-
-### Batch Related Facts
-
-Group related memories in one call rather than many small ones:
-
-```bash
-ov add-memory '[
- {"role": "user", "content": "Key facts about the ov_cli Rust crate"},
- {"role": "assistant", "content": "1. runs faster than python cli\n2. uses HttpClient to connect openviking server\n3. Output formatting supports table and JSON modes\n4. Config lives at ~/.openviking/ovcli.conf"}
-]'
-```
-
-## Prerequisites
-
-- CLI configured: `~/.openviking/ovcli.conf`
-
-# OpenViking (OV) `add-skill`
-
-The `ov add-skill` command adds capabilities to OpenViking — supporting SKILL.md files, MCP tool definitions, and raw skill content. Skills are automatically processed and organized under the `viking://user/skills/` namespace, making them discoverable and usable by agents.
-
-## When to Use
-
-- Adding custom agent capabilities and workflows
-- Importing MCP (Model Context Protocol) tools
-- Persisting skill definitions across agent sessions
-- Building a library of reusable agent capabilities
-- When an agent needs to extend its toolset with custom logic
-
-## Input Formats
-
-### Mode 1: SKILL.md File
-
-Import from a single SKILL.md file with YAML frontmatter:
-
-```bash
-# Add from a single SKILL.md file
-ov add-skill ./skills/my-skill/SKILL.md
-
-# Add from a directory containing SKILL.md (includes auxiliary files)
-ov add-skill ./skills/my-skill/
-```
-
-## CLI Options
-
-### Async Processing Control
-
-Semantic processing happens asynchronously. Use `--wait` to block until complete:
-
-```bash
-# Wait until semantic processing finishes
-ov add-skill ./skills/my-skill/ --wait
-
-# Wait with timeout (in seconds)
-ov add-skill ./skills/my-skill/ --wait --timeout 60
-
-# Fire and forget (default, without --wait)
-ov add-skill ./skills/my-skill/
-```
-
-## CLI Output
-
-Returns the URI of the added skill, like:
-
-```
-uri viking://user/skills/my-skill/
-```
-
-## SKILL.md Format
-
-Skills use Markdown with YAML frontmatter:
-
-```markdown
----
-name: skill-name
-description: Brief description of the skill
-allowed-tools:
- - Tool1
- - Tool2
-tags:
- - tag1
- - tag2
----
-
-## Including Auxiliary Files
-
-When adding from a directory, all files in the directory are included as auxiliary files:
-
-```bash
-# Directory structure:
-# ./skills/code-runner/
-# ├── SKILL.md
-# ├── helper.py
-# └── templates/
-# └── script.py
-
-ov add-skill ./skills/code-runner/
-# Both helper.py and templates/ are included
-```
-
-## CLI Prerequisites
-
-- CLI configured: `~/.openviking/ovcli.conf`
-- The skill file (SKILL.md) should be in the correct markdown format.
diff --git a/examples/skills/ov-resources/SKILL.md b/examples/skills/ov-resources/SKILL.md
new file mode 100644
index 000000000..8791487b1
--- /dev/null
+++ b/examples/skills/ov-resources/SKILL.md
@@ -0,0 +1,73 @@
+---
+name: ov-resources
+description: Load when an agent needs to add, manage, browse, search, modify, or remove resources in OpenViking. Trigger on explicit user requests about resource management or context search, when the user mentions `ov add-resource`, `ov task watch`, `ov export`, `ov import`, `ov backup`, `ov restore`, `ov ls`, `ov tree`, `ov read`, `ov write`, `ov mkdir`, `ov rm`, `ov mv`, `ov find`, `ov search`, `ov grep`, `ov glob`, or when an agent needs to inspect, search, or organize the `viking://resources/` namespace.
+compatibility: OpenViking CLI configured at `~/.openviking/ovcli.conf`
+version: 1.0.0
+last_updated: 2026-06-08
+---
+
+# OpenViking (OV) Resource Management
+
+The `ov` command group for resources covers adding external knowledge, filesystem operations, scheduled refresh (watch tasks), and ovpack import/export/backup/restore.
+
+## Goal
+
+Guide an agent to correctly invoke resource and filesystem commands without guessing flags, URI semantics, or processing behavior.
+
+## Load When
+
+- User explicitly requests resource operations: `ov add-resource`, `ov task watch`, `ov export`, `ov import`, `ov backup`, `ov restore`.
+- User asks to browse, read, write, create, move, or delete files under `viking://resources/`.
+- User asks to search for context: `ov find`, `ov search`, `ov grep`, `ov glob`.
+- User asks to create or manage relations between resources (`ov link`, `ov relations`, `ov unlink`).
+- Agent needs to list, inspect, or search the resource tree to find context.
+
+## Inputs
+
+| Name | Required | Description |
+|---|---|---|
+| `subcommand` | yes | Resource command: `add-resource`, `task watch`, `export`, `import`, `backup`, `restore`, filesystem command: `ls`, `tree`, `read`, `write`, `mkdir`, `rm`, `mv`, `grep`, `glob`, `link`, `relations`, `unlink`, or search command: `find`, `search` |
+| `target` | conditional | File path, URL, Viking URI, or query string |
+| `flags` | no | Command-specific flags like `--wait`, `--to`, `--parent`, `--recursive`, `--watch-interval` |
+
+## Workflow
+
+1. Identify the user's intent and map to the correct `ov <subcommand>`.
+2. Resolve the target (local path, URL, or Viking URI).
+3. Construct the command with appropriate flags.
+4. Execute and report results.
+
+## Permissions
+
+- `ov add-resource` from external URLs may download untrusted content; verify the source when the user provides an untrusted URL.
+- `ov rm --recursive` is destructive; confirm with the user before executing on large directories.
+- `ov export`, `ov import`, `ov backup`, `ov restore` require ROOT or ADMIN permissions.
+- `ov write` replaces file content in-place; the old version is not retained.
+
+## Output
+
+- CLI output returned directly to the user.
+- Errors surfaced with suggested fixes and relevant flag guidance.
+
+## Verification
+
+- After `add-resource`, `ov ls` or `ov tree` should show the new resource under the expected URI.
+- After `rm`, `ov ls` should no longer list the removed path.
+- After `write`, `ov read` should reflect the new content.
+- After `ov import` or `ov restore`, `ov tree` should show the imported structure.
+
+## Boundaries
+
+- Do not invent paths or URLs. Use what the user provides.
+- Do not execute `ov rm --recursive` on broad paths like `viking://resources/` without explicit user confirmation.
+- Do not treat `ov add-skill` or `ov skills` as equivalent to resource commands; skill management is handled by `ov-skills`.
+- Do not treat `ov add-memory` as a resource command; memory management is out of scope for this skill.
+
+## Runtime Resources
+
+- `docs/add-resource.md` — detailed resource ingestion docs, source types, and async processing.
+- `docs/filesystem.md` — filesystem operations reference (ls, tree, read, write, mkdir, rm, mv, grep, glob, link, relations, unlink).
+- `docs/search.md` — semantic search (`ov find`, `ov search`) and search combination strategies.
+- `docs/watch-management.md` — watch task lifecycle (create, pause, resume, trigger, update, remove).
+- `docs/ovpack.md` — ovpack export/import/backup/restore reference.
+- `examples/commands.md` — common command patterns by scenario.
diff --git a/examples/skills/ov-resources/docs/add-resource.md b/examples/skills/ov-resources/docs/add-resource.md
new file mode 100644
index 000000000..cc701a558
--- /dev/null
+++ b/examples/skills/ov-resources/docs/add-resource.md
@@ -0,0 +1,153 @@
+# Resource Ingestion (`ov add-resource`)
+
+The `ov add-resource` command imports external resources into OpenViking's context database under `viking://resources/`.
+
+## Supported Sources
+
+| Type | Examples |
+|---|---|
+| Local file | `./docs/api.md`, `./team_building.jpg`, `/User/volcengine/Documents/profile.pdf` |
+| Local directory | `/User/volcengine/Photo/Travels/2026/` |
+| ZIP archive | `./docs-of-project.zip` (unzipped on server) |
+| URL | `https://example.com/guide.md`, `https://arxiv.org/pdf/2602.09540` |
+| Git repo | `https://github.com/volcengine/OpenViking`, `[email protected]:viking/viking.git` |
+
+## Basic Usage
+
+```bash
+# From URL
+ov add-resource https://github.com/volcengine/OpenViking
+ov add-resource https://arxiv.org/pdf/2602.09540
+
+# From local file
+ov add-resource ./docs/api-spec.md
+ov add-resource ./team_building.jpg
+ov add-resource /User/volcengine/Documents/project.docx
+
+# From local directory
+ov add-resource /User/volcengine/Photo/Travels/2026/ --include "*.jpg,*.jpeg,*.png"
+
+# From ZIP
+ov add-resource ./docs-of-project.zip
+```
+
+## Target Location
+
+By default resources go under `viking://resources/`. Use `--to` or `--parent` to override:
+
+```bash
+# Exact target (must not exist)
+ov add-resource ./docs --to "viking://resources/2026/2026-01-01/"
+
+# Place under existing parent directory
+ov add-resource ./docs --parent "viking://resources/docs/"
+
+# Auto-create parent if missing
+ov add-resource ./docs --parent-auto-create "viking://resources/docs/2026/05/07"
+ov add-resource ./docs -p "viking://resources/docs/{calendar:today}"
+```
+
+## Async Processing Control
+
+Semantic processing runs asynchronously. Use `--wait` to block until complete:
+
+```bash
+# Wait for completion
+ov add-resource ./docs --wait
+
+# Wait with timeout
+ov add-resource ./docs --wait --timeout 60
+
+# Fire and forget (default)
+ov add-resource ./docs
+```
+
+When `wait=false`, the CLI returns after upload/parse/finalize (non-Git sources) or after preflight (Git sources). Use the returned `task_id` with `GET /api/v1/tasks/{task_id}` or `ov observer queue` to track progress.
+
+## Scheduled Refresh (`--watch-interval`)
+
+Create a watch task to re-import periodically:
+
+```bash
+# Refresh every 60 minutes, bound to a fixed URI
+ov add-resource https://github.com/volcengine/OpenViking \
+ --to "viking://resources/repos/OpenViking" \
+ --watch-interval 60
+
+# Refresh every 30 minutes, bound to imported root_uri
+ov add-resource https://example.com/spec.md --watch-interval 30
+
+# Cancel watch for the same target
+ov add-resource https://github.com/volcengine/OpenViking \
+ --to "viking://resources/repos/OpenViking" \
+ --watch-interval 0
+```
+
+`--watch-interval` is in minutes. `> 0` creates/updates; `<= 0` cancels. Prefer `--to` for stable long-term watches.
+
+## Filtering Options
+
+```bash
+# Include only matching files
+ov add-resource ./project --include "*.py,*.md"
+
+# Exclude patterns
+ov add-resource ./project --exclude "*.tmp,*.log"
+
+# Ignore specific directory names
+ov add-resource ./project --ignore-dirs "node_modules,target,.git"
+
+# Preserve directory structure
+ov add-resource ./project --preserve-structure
+```
+
+For local directories, scanning respects `.gitignore` with standard Git semantics; `ignore_dirs`, `include`, and `exclude` further refine ingestion.
+
+## CLI Output
+
+Default table format:
+
+```
+Note: Resource is being processed in the background.
+Use 'ov wait' to wait for completion, or 'ov observer queue' to check status.
+status success
+root_uri viking://resources/01-overview
+task_id uuid-xxx
+```
+
+JSON format (`-o json`):
+
+```json
+{
+ "status": "success",
+ "root_uri": "viking://resources/01-overview",
+ "task_id": "uuid-xxx"
+}
+```
+
+With `--wait`, the response includes `queue_status` with `pending`, `processing`, `completed` counts.
+
+## Key Parameters
+
+| Parameter | Description |
+|---|---|
+| `--to` | Exact target URI (mutually exclusive with `--parent`) |
+| `--parent` / `-p` | Parent directory URI |
+| `--parent-auto-create` | Auto-create parent if missing |
+| `--reason` | Reason for adding (experimental) |
+| `--instruction` | Processing instructions (experimental) |
+| `--wait` | Block until semantic processing completes |
+| `--timeout` | Timeout in seconds when `--wait` is used |
+| `--strict` | Use strict mode |
+| `--ignore-dirs` | Directory names to ignore (comma-separated) |
+| `--include` | File patterns to include (glob) |
+| `--exclude` | File patterns to exclude (glob) |
+| `--watch-interval` | Scheduled refresh interval in minutes |
+
+## Important Notes
+
+- `path` and `temp_file_id` are mutually exclusive.
+- `to` and `parent` are mutually exclusive.
+- When `to` points to an existing resource, the call triggers an incremental update.
+- For Git repos with `wait=false`, OpenViking validates the repo, resolves the target URI, reserves `root_uri`, and returns immediately; clone/parse/finalize continues in background.
+- To create or update plain text directly, use `ov write` instead of `add_resource`.
diff --git a/examples/skills/ov-resources/docs/filesystem.md b/examples/skills/ov-resources/docs/filesystem.md
new file mode 100644
index 000000000..31373ea2c
--- /dev/null
+++ b/examples/skills/ov-resources/docs/filesystem.md
@@ -0,0 +1,169 @@
+# Filesystem Operations
+
+OpenViking provides Unix-like filesystem operations for the `viking://resources/` namespace.
+
+## Read Operations
+
+### `ov read` — Read L2 full content
+
+```bash
+ov read viking://resources/docs/api.md
+```
+
+Accepts file URIs only. Passing a directory returns `INVALID_ARGUMENT` (400) with structured `details.expected="file"`, `details.actual="directory"` so clients can fall back to `ov ls`.
+
+Parameters: `uri` (required), `offset` (line number, 0-indexed), `limit` (lines, -1 for all).
+
+### `ov abstract` — Read L0 abstract (~100 tokens)
+
+```bash
+ov abstract viking://resources/docs/
+```
+
+Directories only.
+
+### `ov overview` — Read L1 overview
+
+```bash
+ov overview viking://resources/docs/
+```
+
+Directories only.
+
+### `ov ls` — List directory contents
+
+```bash
+# Basic listing
+ov ls viking://resources/
+
+# Simple paths only
+ov ls viking://resources/ --simple
+
+# Recursive
+ov ls viking://resources/ --recursive
+```
+
+Parameters: `uri` (required), `--simple`, `--recursive`, `--show-all-hidden`, `--node-limit`.
+
+Entry fields: `name`, `size`, `mode`, `modTime`, `isDir`, `uri`, `meta`.
+
+### `ov tree` — Directory tree structure
+
+```bash
+ov tree viking://resources/my-project/
+```
+
+Parameters: `uri` (required), `--show-all-hidden`, `--node-limit`, `--level-limit`.
+
+### `ov stat` — File/directory status
+
+```bash
+ov stat viking://resources/docs/api.md
+ov stat viking://resources/docs
+```
+
+For directories, returns `count` (estimated item count). `isLocked` reports whether a path lock or ancestor TreeLock is held.
+
+## Write Operations
+
+### `ov write` — Update or create a file
+
+```bash
+ov write viking://resources/docs/api.md \
+ --content "# Updated API\n\nFresh content." \
+ --wait
+```
+
+Modes:
+- `replace` (default): overwrite existing file
+- `append`: append to existing file
+- `create`: create new file (fails if exists, accepts `.md`, `.txt`, `.json`, `.yaml`, `.yml`, `.toml`, `.py`, `.js`, `.ts`)
+
+`--wait` blocks until semantic/vector refresh completes. Parent directories are auto-created for `create`.
+
+Derived semantic files cannot be written directly: `.abstract.md`, `.overview.md`, `.relations.json`.
+
+### `ov mkdir` — Create a directory
+
+```bash
+ov mkdir viking://resources/new-project/
+ov mkdir viking://resources/new-project/ --description "API docs directory"
+```
+
+`--description` writes to `.abstract.md` and queues for L0 vectorization.
+
+## Modify Operations
+
+### `ov rm` — Remove file or directory
+
+```bash
+# Remove single file
+ov rm viking://resources/docs/old.md
+
+# Remove directory recursively
+ov rm viking://resources/old-project/ --recursive
+```
+
+`rm` is idempotent: removing a non-existent valid URI succeeds. Invalid URI formats return `INVALID_URI`. Recursive delete returns `estimated_deleted_count`.
+
+### `ov mv` — Move file or directory
+
+```bash
+ov mv viking://resources/old-name/ viking://resources/new-name/
+```
+
+## Search Operations
+
+### `ov grep` — Search by regex pattern
+
+```bash
+ov grep viking://resources/ "authentication" --ignore-case
+```
+
+Parameters: `uri`, `pattern` (required), `--ignore-case`, `--exclude-uri`, `--node-limit`, `--level-limit`.
+
+Response: `matches` with `uri`, `line`, `content`.
+
+### `ov glob` — Match files by glob pattern
+
+```bash
+ov glob "**/*.md" --uri viking://resources/
+ov glob "**/*.py" --uri viking://resources/
+```
+
+Parameters: `pattern` (required), `--uri`, `--node-limit`.
+
+## Relation Operations
+
+### `ov link` — Create relations
+
+```bash
+# Single link
+ov link viking://resources/docs/auth/ viking://resources/docs/security/ \
+ --reason "Security best practices"
+
+# Multiple links (via API/SDK)
+```
+
+### `ov relations` — List relations
+
+```bash
+ov relations viking://resources/docs/auth/
+```
+
+### `ov unlink` — Remove a relation
+
+```bash
+ov unlink viking://resources/docs/auth/ viking://resources/docs/security/
+```
+
+## WebDAV
+
+OpenViking exposes a minimal WebDAV adapter at `/webdav/resources`:
+
+- Resources only (memories, skills, sessions not exposed)
+- `PUT` accepts UTF-8 text only
+- Supported methods: `OPTIONS`, `PROPFIND`, `GET`, `HEAD`, `PUT`, `DELETE`, `MKCOL`, `MOVE`
+- Semantic sidecars and internal files are hidden
+- `PUT` does not auto-create parent collections; use `MKCOL` first
+- Creating or replacing a file triggers semantic generation
diff --git a/examples/skills/ov-resources/docs/ovpack.md b/examples/skills/ov-resources/docs/ovpack.md
new file mode 100644
index 000000000..c014bab5c
--- /dev/null
+++ b/examples/skills/ov-resources/docs/ovpack.md
@@ -0,0 +1,67 @@
+# OVPack Import/Export/Backup/Restore
+
+OVPack is a `.ovpack` archive format for backing up and migrating OpenViking resource trees. Requires ROOT or ADMIN permissions.
+
+## Export (`ov export`)
+
+Packages resources under a URI into a `.ovpack` file.
+
+```bash
+# Export a resource tree
+ov export viking://resources/my-project/ ./exports/my-project.ovpack
+
+# Include dense vector snapshot
+ov export viking://resources/my-project/ ./exports/my-project.ovpack --include-vectors
+```
+
+The ZIP stores user content under `<root>/files/` and metadata under `<root>/_ovpack/`:
+- `manifest.json` — entry list with `path`, `size`, `sha256`, `content_sha256`
+- `index_records.jsonl` — portable index scalar fields
+- `dense.f32` — pure-dense float32 vector snapshot (when `--include-vectors`)
+
+Hybrid index types reject vector snapshot export.
+
+## Import (`ov import`)
+
+Restores a `.ovpack` file to a target location.
+
+```bash
+# Basic import
+ov import ./exports/my-project.ovpack viking://resources/imported/
+
+# Explicit conflict policy
+ov import ./exports/my-project.ovpack viking://resources/imported/ --on-conflict overwrite
+
+# Require compatible dense vector snapshot
+ov import ./exports/my-project.ovpack viking://resources/imported/ --vector-mode require
+```
+
+Conflict policies: `fail` (default), `overwrite`, `skip`.
+Vector modes: `auto` (default), `recompute`, `require`.
+
+## Backup (`ov backup`)
+
+Backs up all public scope roots (`resources`, `user`, `agent`, `session`) as a restore-only `.ovpack`.
+
+```bash
+ov backup ./backups/openviking.ovpack
+ov backup ./backups/openviking.ovpack --include-vectors
+```
+
+## Restore (`ov restore`)
+
+Restores a backup package created by `ov backup` to the original public scope roots.
+
+```bash
+ov restore ./backups/openviking.ovpack --on-conflict overwrite
+ov restore ./backups/openviking.ovpack --on-conflict overwrite --vector-mode require
+```
+
+Regular import rejects backup packages. Session files are restored without vectorization.
+
+## Important Notes
+
+- Packages without a manifest are rejected.
+- Content integrity is validated (file sizes, `sha256`, `content_sha256`).
+- Runtime fields (`id`, `uri`, `account_id`, `created_at`, `updated_at`) are regenerated on import.
+- Top-level scope packages (e.g. `viking://resources/`) must be imported to `viking://`.
diff --git a/examples/skills/ov-resources/docs/search.md b/examples/skills/ov-resources/docs/search.md
new file mode 100644
index 000000000..1671f3cd8
--- /dev/null
+++ b/examples/skills/ov-resources/docs/search.md
@@ -0,0 +1,129 @@
+# Semantic Search (`ov find` / `ov search`)
+
+OpenViking provides two semantic search commands for retrieving context from resources, memories, and skills.
+
+## `ov find` — Pure Vector Similarity Search
+
+Performs hierarchical vector similarity search without session context. Best for simple, direct queries.
+
+```bash
+# Basic search across all context
+ov find "how to handle API rate limits"
+
+# Search within specific URI scope
+ov find "authentication flow" --uri "viking://resources/my-project"
+
+# Limit results and set relevance threshold
+ov find "error handling" --node-limit 5 --threshold 0.3
+
+# Time-filtered search
+ov find "invoice" --after 7d --time-field created_at
+
+# Level-filtered search (L0 only)
+ov find "overview" --level 0
+
+# Multiple levels
+ov find "details" -L 1,2
+```
+
+## `ov search` — Context-Aware Search with Intent Analysis
+
+Adds session context understanding and intent analysis on top of `find()`. Better for conversational queries.
+
+```bash
+# Search with session context
+ov search "best practices" --session-id abc123
+
+# Search with time filter
+ov search "watch vs scheduled" --after 2026-03-15 --before 2026-03-20
+
+# Search without session (still performs intent analysis)
+ov search "how to implement OAuth 2.0 authorization code flow"
+
+# Level-filtered
+ov search "best practices" --level 0
+ov search "how to implement OAuth" -L 1,2
+```
+
+## Find vs Search
+
+| Aspect | `find` | `search` |
+|--------|--------|----------|
+| Intent Analysis | No | Yes |
+| Session Context | No | Yes |
+| Query Expansion | No | Yes |
+| Default Limit | 10 | 10 |
+| Use Case | Simple queries | Conversational search |
+
+## Common Parameters
+
+| Parameter | Description |
+|---|---|
+| `--uri` | Limit search to specific URI prefix |
+| `--node-limit` / `--limit` | Maximum number of results |
+| `--threshold` / `--score-threshold` | Minimum relevance score (0-1) |
+| `--after` | Lower time bound (`2h`, `7d`, ISO 8601) |
+| `--before` | Upper time bound (`30m`, ISO 8601) |
+| `--time-field` | `updated_at` (default) or `created_at` |
+| `--level` / `-L` | Limit to levels: `0`, `1`, `2`, `0,1,2` |
+| `--peer-id` | Stable interaction peer ID |
+| `--session-id` | Session ID for context-aware search (`search` only) |
+
+## Search Result Structure
+
+Results are grouped by `context_type`:
+
+```json
+{
+ "memories": [],
+ "resources": [
+ {
+ "uri": "viking://resources/docs/auth.md",
+ "context_type": "resource",
+ "level": 2,
+ "score": 0.95,
+ "abstract": "OAuth 2.0 best practices...",
+ "overview": "This guide covers...",
+ "match_reason": "Context-aware match: OAuth login best practices",
+ "relations": []
+ }
+ ],
+ "skills": [],
+ "total": 1,
+ "query_plan": {
+ "reasoning": "User is asking about OAuth implementation...",
+ "queries": [...]
+ }
+}
+```
+
+`query_plan` is only present in `search` results.
+
+## URI Scope Targets
+
+```bash
+# Search only resources
+ov find "authentication" --uri "viking://resources"
+
+# Search only memories
+ov find "preferences" --uri "viking://user/memories"
+
+# Search only skills
+ov find "web search" --uri "viking://user/skills"
+
+# Search specific project
+ov find "API endpoints" --uri "viking://resources/my-project"
+```
+
+## Combining Search with Browse
+
+```bash
+# Step 1: Semantic search to find relevant directories
+ov find "authentication" --uri "viking://resources/project-A"
+
+# Step 2: Get overview for context
+ov overview viking://resources/project-A/backend
+
+# Step 3: Read specific content
+ov read viking://resources/project-A/backend/auth.md
+```
diff --git a/examples/skills/ov-resources/docs/watch-management.md b/examples/skills/ov-resources/docs/watch-management.md
new file mode 100644
index 000000000..980d3dcc0
--- /dev/null
+++ b/examples/skills/ov-resources/docs/watch-management.md
@@ -0,0 +1,91 @@
+# Watch Task Management (`ov task watch`)
+
+Watch tasks enable scheduled refresh of resources imported via `ov add-resource --watch-interval`. The control plane is available via `ov task watch` CLI subcommands.
+
+## Core Concepts
+
+- **Creation**: Set `watch_interval > 0` on `ov add-resource` to create or update a watch task.
+- **Binding**: Tasks bind to `--to` if provided; otherwise to the imported `root_uri`.
+- **Scheduling**: `WatchScheduler` checks expired tasks every 60 seconds.
+- **Pause/Resume**: `is_active` is orthogonal to `watch_interval`; pause without losing cadence.
+
+## Subcommands
+
+### `ov task watch ls` — List watch tasks
+
+```bash
+# List active watches only
+ov task watch ls --active-only
+
+# List all (including paused)
+ov task watch ls
+```
+
+### `ov task watch show` — Inspect a single watch
+
+```bash
+ov task watch show viking://resources/guide.md
+ov task watch show <task_id>
+```
+
+The key argument is auto-classified: `viking://` URIs route by URI, anything else is treated as a task ID.
+
+### `ov task watch pause` — Pause without losing cadence
+
+```bash
+ov task watch pause viking://resources/guide.md
+```
+
+Sets `is_active=false`. The `watch_interval` is preserved.
+
+### `ov task watch resume` — Resume a paused watch
+
+```bash
+ov task watch resume viking://resources/guide.md
+```
+
+Sets `is_active=true`.
+
+### `ov task watch update` — Update watch parameters
+
+```bash
+# Update interval
+ov task watch update viking://resources/guide.md --interval 30
+
+# Update reason and instruction
+ov task watch update viking://resources/guide.md \
+ --reason "Updated docs" \
+ --instruction "Focus on API changes"
+```
+
+Supported update fields: `--interval`, `--active` / `--no-active`, `--reason`, `--instruction`.
+
+### `ov task watch trigger` — Immediate refresh
+
+```bash
+ov task watch trigger viking://resources/guide.md
+```
+
+Fire-and-forget; returns immediately while re-ingest runs in background.
+
+### `ov task watch rm` — Remove a watch task
+
+```bash
+ov task watch rm viking://resources/guide.md
+```
+
+## Lifecycle Summary
+
+| Action | Command |
+|---|---|
+| Create/update | `ov add-resource <source> --to <uri> --watch-interval <minutes>` |
+| List | `ov task watch ls [--active-only]` |
+| Inspect | `ov task watch show <key>` |
+| Pause | `ov task watch pause <key>` |
+| Resume | `ov task watch resume <key>` |
+| Update cadence | `ov task watch update <key> --interval <minutes>` |
+| Trigger now | `ov task watch trigger <key>` |
+| Remove | `ov task watch rm <key>` |
+| Cancel via add-resource | `ov add-resource <source> --to <uri> --watch-interval 0` |
+
+`key` can be either a `viking://` URI or a task ID.
diff --git a/examples/skills/ov-resources/examples/commands.md b/examples/skills/ov-resources/examples/commands.md
new file mode 100644
index 000000000..2b27c76da
--- /dev/null
+++ b/examples/skills/ov-resources/examples/commands.md
@@ -0,0 +1,194 @@
+# Common Resource Management Command Patterns
+
+## Adding Resources
+
+```bash
+# Local file
+ov add-resource ./docs/api.md
+
+# Local directory with filters
+ov add-resource ./project --include "*.py,*.md" --ignore-dirs "node_modules"
+
+# URL
+ov add-resource https://example.com/guide.md
+
+# Git repository with watch
+ov add-resource https://github.com/volcengine/OpenViking \
+ --to "viking://resources/repos/OpenViking" \
+ --watch-interval 60
+
+# To specific location with wait
+ov add-resource ./docs --to "viking://resources/docs/" --wait
+
+# Auto-create parent path
+ov add-resource ./guide.md -p "viking://resources/docs/{calendar:today}"
+```
+
+## Browsing Resources
+
+```bash
+# List top-level resources
+ov ls viking://resources/
+
+# Recursive listing
+ov ls viking://resources/my-project/ --recursive
+
+# Tree view (limited depth)
+ov tree viking://resources/my-project/ --level-limit 3
+
+# Simple path list
+ov ls viking://resources/ --simple
+
+# File stats
+ov stat viking://resources/docs/api.md
+```
+
+## Reading Content
+
+```bash
+# Full content
+ov read viking://resources/docs/api.md
+
+# With line range
+ov read viking://resources/docs/api.md --offset 10 --limit 20
+
+# Abstract (directory)
+ov abstract viking://resources/docs/
+
+# Overview (directory)
+ov overview viking://resources/docs/
+```
+
+## Writing Content
+
+```bash
+# Replace existing file
+ov write viking://resources/docs/api.md \
+ --content "# Updated\n\nNew content." \
+ --wait
+
+# Create new file
+ov write viking://resources/docs/new.md \
+ --content "# New doc" \
+ --mode create
+
+# Append to existing
+ov write viking://resources/docs/notes.md \
+ --content "\nNew line." \
+ --mode append
+```
+
+## Directory Management
+
+```bash
+# Create directory
+ov mkdir viking://resources/new-project/
+
+# Create with description
+ov mkdir viking://resources/new-project/ --description "Project docs"
+
+# Move
+ov mv viking://resources/old-name/ viking://resources/new-name/
+
+# Remove file
+ov rm viking://resources/docs/old.md
+
+# Remove directory recursively
+ov rm viking://resources/old-project/ --recursive
+```
+
+## Searching Resources
+
+```bash
+# Grep content
+ov grep viking://resources/ "TODO" --ignore-case
+
+# Glob files
+ov glob "**/*.md" --uri viking://resources/
+ov glob "**/*.py" --uri viking://resources/
+```
+
+## Watch Task Management
+
+```bash
+# List active watches
+ov task watch ls --active-only
+
+# Inspect a watch
+ov task watch show viking://resources/guide.md
+
+# Pause / resume
+ov task watch pause viking://resources/guide.md
+ov task watch resume viking://resources/guide.md
+
+# Update interval
+ov task watch update viking://resources/guide.md --interval 30
+
+# Trigger immediate refresh
+ov task watch trigger viking://resources/guide.md
+
+# Remove watch
+ov task watch rm viking://resources/guide.md
+
+# Cancel via add-resource
+ov add-resource https://example.com/guide.md \
+ --to "viking://resources/guide.md" \
+ --watch-interval 0
+```
+
+## OVPack Operations
+
+```bash
+# Export
+ov export viking://resources/my-project/ ./backups/my-project.ovpack
+
+# Import
+ov import ./backups/my-project.ovpack viking://resources/imported/
+
+# Backup all public scopes
+ov backup ./backups/openviking.ovpack
+
+# Restore from backup
+ov restore ./backups/openviking.ovpack --on-conflict overwrite
+```
+
+## Searching Resources
+
+```bash
+# Semantic find across all context
+ov find "how to handle API rate limits"
+
+# Find within specific scope
+ov find "authentication flow" --uri "viking://resources/my-project"
+
+# Find with time filter
+ov find "invoice" --after 7d --time-field created_at
+
+# Find L0 abstracts only
+ov find "overview" --level 0
+
+# Context-aware search
+ov search "best practices" --session-id abc123
+
+# Search with intent analysis
+ov search "how to implement OAuth 2.0"
+
+# Combined: search then read
+ov find "authentication" --uri "viking://resources/project-A"
+ov overview viking://resources/project-A/backend
+ov read viking://resources/project-A/backend/auth.md
+```
+
+## Relations
+
+```bash
+# Link resources
+ov link viking://resources/docs/auth/ viking://resources/docs/security/ \
+ --reason "Security best practices"
+
+# List relations
+ov relations viking://resources/docs/auth/
+
+# Unlink
+ov unlink viking://resources/docs/auth/ viking://resources/docs/security/
+```
diff --git a/examples/skills/ov-search-context/SKILL.md b/examples/skills/ov-search-context/SKILL.md
deleted file mode 100644
index de9a1e070..000000000
--- a/examples/skills/ov-search-context/SKILL.md
+++ /dev/null
@@ -1,157 +0,0 @@
----
-name: ov-search-context
-description: Search context data(memories, skills and resource) from OpenViking Context Database (aka. ov). Trigger this tool when 1. need information that might be stored as memories, skills or resources on OpenViking; 2. is explicitly requested searching files or knowledge; 3. sees `search context`, `search openviking`, `search ov` request.
-compatibility: CLI configured at `~/.openviking/ovcli.conf`
----
-# OpenViking (OV) context searching
-The `ov search` command performs context-aware retrieval across all memories and resources in OpenViking — combining semantic understanding with directory recursive retrieval to find the most relevant context for any query.
-
-## Table of Content
-- When to Use
-- Sub-commands for search
- - List directories (`ov ls`)
- - Tree view (`ov tree`)
- - Semantic Search (`ov find`)
- - Content Pattern Search (`ov grep`)
- - File Glob Search (`ov glob`)
- - Full content read (`ov read`)
- - Get overview (`ov overview`)
- - Get Abstract (`ov abstract`)
-- Prerequisite
-
-## When to Use
-
-- Finding specific information within imported resources or saved memories
-- Retrieving context about topics, APIs, or patterns previously added
-- Searching across project documentation, code, and learnings
-- When an agent needs to reference previously stored knowledge
-
-> note: cli command can be outdated, when sees error, use `--help` to get latest usage
-
-## Sub-commands for search
-
-### List Contents (`ov ls`)
-
-Browse directory structure:
-
-```bash
-# List root directory
-ov ls
-
-# List specific directory
-ov ls viking://resources/my-project/docs/
-
-# Simple path output (only uris, no metadata)
-ov ls viking://resources --simple
-
-# Show hidden files
-ov ls viking://resources --all
-
-# Control output limits (default 256)
-ov ls viking://resources --node-limit 50
-
-# Control abstract info length limit for each node (default 256)
-ov ls viking://resources --abs-limit 128
-```
-
-### Tree View (`ov tree`)
-
-Visualize directory hierarchy:
-
-```bash
-# Show tree structure
-ov tree viking://resources
-
-# Control depth limits (default 3)
-ov tree viking://resources --level-limit 2
-
-# Control node limits
-ov tree viking://resources --node-limit 100 --abs-limit 128
-
-# Show all files including hidden
-ov tree viking://resources --all
-```
-
-### Semantic find (`ov find`)
-
-Find method with semantic relevance ranking:
-
-```bash
-# Basic find across all context
-ov find "how to handle API rate limits"
-
-# Find within specific URI scope
-ov find "authentication flow" --uri "viking://resources/my-project"
-
-# Limit results and set relevance score threshold
-ov find "error handling" --node-limit 5 --threshold 0.3
-```
-
-### Content Pattern Search (`ov grep`)
-
-Literal pattern matching:
-
-```bash
-# Find exact text pattern (Note: this is expensive, and suggest within specific small URI scope)
-ov grep "viking://resources" "TODO:" --uri "viking://resources/my-project"
-
-# Case-insensitive search
-ov grep "viking://resources" "API_KEY" --ignore-case --uri "viking://resources/my-project"
-
-# Limit results and set node limit
-ov grep "viking://resources" "API_KEY" --node-limit 5 --uri "viking://resources/my-project"
-```
-
-### File Glob Search (`ov glob`)
-
-File path pattern matching:
-
-```bash
-# Find all markdown files (Note: this is expensive, and suggest within specific small URI scope)
-ov glob "**/*.md" --uri "viking://resources/my-project"
-
-# Limit results and set node limit
-ov glob "**/*.md" --uri "viking://resources/my-project" --node-limit 5
-```
-
-### Read File Content (`ov read`)
-
-Retrieve full content (L0-L2 layer):
-
-```bash
-# Read full content
-ov read viking://resources/docs/api/api-1.md
-
-# Read first 10 lines of api-2.md
-ov read viking://resources/docs/api/api-2.md | head -n 10
-
-# Read abstract (L0 - quick summary)
-ov abstract viking://resources/docs/api/
-ov read viking://resources/docs/api/.abstract.md
-
-# Read overview (L1 - key points)
-ov overview viking://resources/docs/api/
-ov read viking://resources/docs/api/.overview.md
-```
-
-### Combining Search
-
-Use search results to guide further actions:
-
-```bash
-ov ls viking://resources/
-
-# Search for relevant files
-ov search "authentication" --uri "viking://resources/project-A"
-
-# Get overview for context
-ov overview viking://resources/project-A/backend
-
-# Decide to read specific content
-ov read viking://resources/project-A/backend/auth.md
-```
-
-## Prerequisites
-
-- CLI configured: `~/.openviking/ovcli.conf`
-- Resources or memories previously added to OpenViking
diff --git a/examples/skills/ov-skills/SKILL.md b/examples/skills/ov-skills/SKILL.md
new file mode 100644
index 000000000..99397ba7e
--- /dev/null
+++ b/examples/skills/ov-skills/SKILL.md
@@ -0,0 +1,67 @@
+---
+name: ov-skills
+description: Load when an agent needs to manage, install, update, remove, or validate OpenViking skills via the `ov skills` CLI. Trigger on explicit user requests about skill management, when the user mentions `ov skills`, `install skill`, `update skill`, `delete skill`, `validate skill`, or when an agent needs to discover what skills are available on the OpenViking server.
+compatibility: OpenViking CLI configured at `~/.openviking/ovcli.conf`
+version: 1.0.0
+last_updated: 2026-06-08
+---
+
+# OpenViking (OV) Skills Management
+
+The `ov skills` command group manages agent skills on OpenViking — including installation from local directories, Git repositories, GitHub URLs, or raw content; listing, searching, inspecting, updating, and removing skills; and validating skill format locally.
+
+## Goal
+
+Guide an agent to correctly invoke `ov skills` subcommands for skill lifecycle operations without guessing flags, source types, or update semantics.
+
+## Load When
+
+- User explicitly requests skill management: `ov skills ...`, `install skill`, `update skill`, `delete skill`, `remove skill`.
+- User asks to validate a SKILL.md or skill directory.
+- User asks to find or search installed skills.
+- User asks to inspect a skill's content, files, or source.
+- Agent needs to discover available skills before selecting one.
+
+## Inputs
+
+| Name | Required | Description |
+|---|---|---|
+| `subcommand` | yes | One of `list`, `find`, `add`, `show`, `update`, `remove`, `validate` |
+| `target` | conditional | Skill name, query string, source path/URL, or directory path |
+| `level` | no | Content level for `show`/`find`: `0` (abstract), `1` (overview), `2` (full) |
+
+## Workflow
+
+1. Identify the user's intent and map to the correct `ov skills <subcommand>`.
+2. Determine the source type for `add` (local dir, local file, Git URL, GitHub tree URL, raw content).
+3. Construct the command with appropriate flags.
+4. Execute and report results.
+
+## Permissions
+
+- `ov skills add` may download and install external code; verify the source when the user provides an untrusted URL.
+- `ov skills remove --all` is destructive; confirm with the user before executing.
+- `ov skills update` replaces skill content in-place; the old version is not retained.
+
+## Output
+
+- CLI output returned directly to the user.
+- Errors surfaced with suggested fixes.
+
+## Verification
+
+- After `add`, `list` should include the new skill.
+- After `remove`, `list` should no longer include the removed skill.
+- After `update`, `show <name> --source` should reflect fresh content.
+
+## Boundaries
+
+- Do not invent skill names or URLs. Use what the user provides.
+- Do not execute `ov skills remove --all` without explicit user confirmation.
+- Do not treat `ov add-skill` (legacy resource command) as equivalent to `ov skills add`.
+
+## Runtime Resources
+
+- `docs/upgrade-guide.md` — migrating from legacy `ov add-skill` / resource commands.
+- `examples/commands.md` — common command patterns by scenario.
+- `docs/source-types.md` — deep dive on supported source formats and URL patterns.
diff --git a/examples/skills/ov-skills/docs/source-types.md b/examples/skills/ov-skills/docs/source-types.md
new file mode 100644
index 000000000..0f25a631c
--- /dev/null
+++ b/examples/skills/ov-skills/docs/source-types.md
@@ -0,0 +1,99 @@
+# Supported Skill Source Types
+
+## Local Directory
+
+A directory containing a `SKILL.md` file at its root. All files in the directory become auxiliary files.
+
+```
+./my-skill/
+ ├── SKILL.md
+ ├── helper.py
+ └── templates/
+ └── template.txt
+```
+
+```bash
+ov skills add ./my-skill
+```
+
+## Local SKILL.md File
+
+A single `SKILL.md` file. No auxiliary files are included.
+
+```bash
+ov skills add ./my-skill/SKILL.md
+```
+
+## Git Repository URL
+
+Any valid Git URL. The repository is cloned and processed.
+
+```bash
+ov skills add https://github.com/org/skills-repo.git
+ov skills add [email protected]:org/skills-repo.git
+```
+
+## GitHub Tree URL
+
+Special support for GitHub tree URLs to install individual skills from monorepos.
+
+### Single Skill Path
+
+The URL path ends at a specific skill directory:
+
+```bash
+ov skills add https://github.com/anthropics/skills/tree/main/skills/algorithmic-art
+```
+
+This installs the `algorithmic-art` skill.
+
+### Skills Collection with Selector
+
+The URL points to a parent directory containing multiple skills:
+
+```bash
+ov skills add https://github.com/anthropics/skills/tree/main/skills --skill brand-guidelines
+```
+
+### Branch Names with Slashes
+
+Branch names containing `/` are supported as long as the skill path is under `skills/...`:
+
+```bash
+ov skills add https://github.com/org/repo/tree/feature/new-ui/skills/my-skill
+```
+
+### Preview Available Skills
+
+Use `--list` to see what skills are available at a source without installing:
+
+```bash
+ov skills add https://github.com/anthropics/skills/tree/main/skills --list
+```
+
+## Raw Content
+
+Pipe SKILL.md content directly via stdin:
+
+```bash
+ov skills add - <<'EOF'
+---
+name: inline-skill
+description: Created inline
+---
+# Inline Skill
+Content here.
+EOF
+```
+
+## Source Metadata
+
+When a skill is installed, its source is recorded in `.source.json` (hidden, not shown in `--files`):
+
+| Source Type | Recorded Fields |
+|---|---|
+| Git | `type=git`, `source`, `clone_url`, `ref_name`, `subdir`, `skill_name` |
+| Local | `type=local`, path, `skill_name` |
+| API / raw | `type=api`, operation, upload method, `skill_name` |
+
+This metadata enables `ov skills update` to automatically refresh from the original source.
diff --git a/examples/skills/ov-skills/docs/upgrade-guide.md b/examples/skills/ov-skills/docs/upgrade-guide.md
new file mode 100644
index 000000000..b6455796b
--- /dev/null
+++ b/examples/skills/ov-skills/docs/upgrade-guide.md
@@ -0,0 +1,23 @@
+# Upgrade Guide: Legacy Skill Commands to `ov skills`
+
+## Legacy vs New Commands
+
+| Scenario | Old Command | New Command |
+|---|---|---|
+| Install local single skill | `ov resources add ./skills/my-skill/SKILL.md` | `ov skills add ./skills/my-skill` |
+| Install local directory skill | `ov add-skill ./skills/my-skill/` | `ov skills add ./skills/my-skill` |
+| Install from GitHub tree | `git clone <repo>` then manual upload | `ov skills add https://github.com/anthropics/skills/tree/main/skills/algorithmic-art` |
+| List installed skills | `ov resources ls viking://user/default/skills` | `ov skills list` |
+| Search skills | Generic find across resources | `ov skills find "video generation"` |
+| View skill content | Manual read of skill directory | `ov skills show video-generate` |
+| View auxiliary files | `ov resources tree viking://user/default/skills/...` | `ov skills show video-generate --files` |
+| Update skill | Re-upload manually | `ov skills update video-generate` |
+| Delete skill | `ov resources rm viking://user/default/skills/... --recursive` | `ov skills remove video-generate` |
+| Validate skill format | No dedicated command | `ov skills validate ./skills/my-skill` |
+
+## Key Differences
+
+1. **Unified namespace**: `ov skills` operates on a dedicated skills namespace, not the generic resources tree.
+2. **Source tracking**: Skills installed via `ov skills add` record their source in `.source.json`, enabling automatic `update`.
+3. **Level-based viewing**: `ov skills show` supports `-L 0/1/2` to view abstract, overview, or full content.
+4. **GitHub tree support**: Direct installation from `https://github.com/.../tree/...` URLs without manual clone.
diff --git a/examples/skills/ov-skills/examples/commands.md b/examples/skills/ov-skills/examples/commands.md
new file mode 100644
index 000000000..f626f9237
--- /dev/null
+++ b/examples/skills/ov-skills/examples/commands.md
@@ -0,0 +1,177 @@
+# Common `ov skills` Command Patterns
+
+## Listing Skills
+
+```bash
+# List all installed skills
+ov skills list
+
+# List in JSON format
+ov skills list --json
+```
+
+## Finding Skills
+
+```bash
+# Semantic search across installed skills
+ov skills find "video generation"
+
+# Search and return only abstracts (L0)
+ov skills find "video generation" --level 0
+
+# Search with result limit and score threshold
+ov skills find "API design" --limit 5 --threshold 0.3
+```
+
+## Adding Skills
+
+### From Local Directory
+
+```bash
+# Add a skill directory (must contain SKILL.md)
+ov skills add ./skills/my-skill
+
+# Add with wait for processing
+ov skills add ./skills/my-skill --wait
+
+# List skills available in a directory without installing
+ov skills add ./skills --list
+
+# Install specific skills from a directory
+ov skills add ./skills --skill my-skill --skill another-skill
+
+# Install all skills from a directory
+ov skills add ./skills --skill "*"
+```
+
+### From Local SKILL.md File
+
+```bash
+ov skills add ./skills/my-skill/SKILL.md
+```
+
+### From Git Repository
+
+```bash
+ov skills add https://github.com/org/repo.git
+```
+
+### From GitHub Tree URL
+
+```bash
+# Single skill from GitHub tree
+ov skills add https://github.com/anthropics/skills/tree/main/skills/algorithmic-art
+
+# Specific skill from a skills collection
+ov skills add https://github.com/anthropics/skills/tree/main/skills --skill brand-guidelines
+
+# List available skills in a GitHub tree without installing
+ov skills add https://github.com/anthropics/skills/tree/main/skills --list
+```
+
+### From Raw Content
+
+```bash
+ov skills add - <<'EOF'
+---
+name: my-inline-skill
+description: A skill defined inline
+---
+# My Skill
+Skill content here.
+EOF
+```
+
+## Showing Skills
+
+```bash
+# Show full skill content (default: L0 + L1 + L2)
+ov skills show video-generate
+
+# Show only abstract (L0)
+ov skills show video-generate --level 0
+
+# Show only overview (L1)
+ov skills show video-generate --level 1
+
+# Show only full SKILL.md (L2)
+ov skills show video-generate --level 2
+
+# Show auxiliary files
+ov skills show video-generate --files
+
+# Show source information
+ov skills show video-generate --source
+
+# Combine flags
+ov skills show video-generate --files --source
+```
+
+## Updating Skills
+
+```bash
+# Update a specific skill
+ov skills update video-generate
+
+# Update multiple skills
+ov skills update video-generate image-generate
+
+# Update all updatable skills (interactive)
+ov skills update
+
+# Update all without confirmation
+ov skills update --yes
+
+# Wait for processing
+ov skills update video-generate --wait
+```
+
+### Update Behavior by Source
+
+| Source Type | Update Behavior |
+|---|---|
+| Git | Re-clone and re-process |
+| Local path | Re-read from recorded local path |
+| API / raw content | Skipped (no external source to pull) |
+
+## Removing Skills
+
+```bash
+# Remove a specific skill
+ov skills remove video-generate
+
+# Remove without confirmation
+ov skills remove video-generate --yes
+
+# Interactive selection (no name provided)
+ov skills remove
+
+# Remove all skills (destructive — confirm first)
+ov skills remove --all
+```
+
+## Validating Skills
+
+```bash
+# Validate a skill directory
+ov skills validate ./skills/my-skill
+
+# Validate a single SKILL.md file
+ov skills validate ./skills/my-skill/SKILL.md
+
+# Strict validation (name must match directory name)
+ov skills validate ./skills/my-skill --strict
+```
+
+### Validation Rules
+
+| Check | Strict Mode | Normal Mode |
+|---|---|---|
+| `name` missing | Error | Error |
+| `description` missing | Error | Error |
+| Invalid YAML frontmatter | Error | Error |
+| Name doesn't match directory | Error | — |
+| Name > 64 chars | Error | Warning |
+| Name has illegal chars | Error | Warning |
+| Description > 1024 chars | Error | Warning |
+| Body > 500 lines | Warning | Warning |
diff --git a/scripts/test_ov_intent_planner.py b/scripts/test_ov_intent_planner.py
deleted file mode 100644
index f30206e44..000000000
--- a/scripts/test_ov_intent_planner.py
+++ /dev/null
@@ -1,223 +0,0 @@
-#!/usr/bin/env python3
-"""Smoke-test OpenViking intent analysis through the configured query_planner.
-
-This calls OpenViking's IntentAnalyzer directly. It does not call Ollama with a
-hand-written payload, so it verifies the same model path used by search()
-intent analysis.
-"""
-
-from __future__ import annotations
-
-import argparse
-import asyncio
-import importlib.util
-import json
-import os
-import sys
-import time
-from dataclasses import asdict
-from pathlib import Path
-from typing import Any
-
-from openviking_cli.retrieve.types import ContextType
-from openviking_cli.utils.config import OPENVIKING_CONFIG_ENV
-from openviking_cli.utils.config.open_viking_config import OpenVikingConfigSingleton
-
-DEFAULT_CONFIG = Path.home() / ".openviking" / "ov.conf"
-EXPECTED_MODEL = "ollama/guoxuter/ov_intent_analysis_sft:v1_q8"
-
-
-CASES: dict[str, dict[str, Any]] = {
- "rfc": {
- "name": "operational RFC task",
- "compression_summary": "",
- "recent_messages": [
- ("user", "帮我写一份 RFC 文档"),
- ("assistant", "好的,标题是什么?"),
- ],
- "current_message": "标题就叫《支付链路重构》,按公司标准模板来",
- "context_type": None,
- "target_abstract": "",
- },
- "format": {
- "name": "informational format question",
- "compression_summary": "",
- "recent_messages": [
- ("user", "我在做新项目的技术选型"),
- ("assistant", "好的,需要参考什么资料?"),
- ],
- "current_message": "RFC 文档的标准格式是什么?",
- "context_type": None,
- "target_abstract": "",
- },
- "chat": {
- "name": "conversational small talk",
- "compression_summary": "",
- "recent_messages": [
- ("user", "你好"),
- ("assistant", "你好,有什么可以帮你?"),
- ],
- "current_message": "今天天气挺好的",
- "context_type": None,
- "target_abstract": "",
- },
- "memory": {
- "name": "restricted memory query",
- "compression_summary": "",
- "recent_messages": [
- ("user", "帮我对比下这次活动和上月会员日的 ROI"),
- ],
- "current_message": "活动周期 7 天,预计 10 万用户参与",
- "context_type": ContextType.MEMORY,
- "target_abstract": "User's long-term memory; preferences / events / historical KPIs",
- },
-}
-
-
-def _message(i: int, role: str, text: str):
- from openviking.message import Message, TextPart
-
- return Message(id=f"case-msg-{i}", role=role, parts=[TextPart(text=text)])
-
-
-def _messages(raw_messages: list[tuple[str, str]]) -> list[Any]:
- return [_message(i, role, text) for i, (role, text) in enumerate(raw_messages, start=1)]
-
-
-def _load_config(config_path: Path, *, preserve_log_output: bool = False):
- os.environ[OPENVIKING_CONFIG_ENV] = str(config_path)
- data = json.loads(config_path.read_text(encoding="utf-8-sig"))
- if not preserve_log_output:
- data.setdefault("log", {})
- data["log"]["output"] = "stdout"
- return OpenVikingConfigSingleton.initialize(config_dict=data)
-
-
-def _load_intent_analyzer_class():
- module_path = (
- Path(__file__).resolve().parents[1] / "openviking" / "retrieve" / "intent_analyzer.py"
- )
- spec = importlib.util.spec_from_file_location("_ov_intent_analyzer_direct", module_path)
- if spec is None or spec.loader is None:
- raise RuntimeError(f"Could not load IntentAnalyzer from {module_path}")
- module = importlib.util.module_from_spec(spec)
- spec.loader.exec_module(module)
- return module.IntentAnalyzer
-
-
-def _planner_summary(config: Any) -> dict[str, Any]:
- planner = config.get_query_planner()
- return {
- "provider": planner.provider,
- "model": planner.model,
- "api_base": planner.api_base,
- "max_tokens": planner.max_tokens,
- "timeout": planner.timeout,
- "extra_request_body": planner.extra_request_body,
- "uses_query_planner": planner is config.query_planner,
- }
-
-
-def _print_plan(case_key: str, case_name: str, elapsed: float, plan: Any) -> None:
- print(f"\n=== {case_key}: {case_name} ===")
- print(f"elapsed_seconds: {elapsed:.3f}")
- print(f"reasoning: {plan.reasoning[:400]}")
- if not plan.queries:
- print("queries: []")
- return
- print("queries:")
- for idx, query in enumerate(plan.queries, start=1):
- context_type = query.context_type.value if query.context_type else None
- print(f" {idx}. [{context_type}] p={query.priority} {query.query}")
- if query.intent:
- print(f" intent: {query.intent}")
-
-
-async def _run_case(
- intent_analyzer_class: Any,
- case_key: str,
- case: dict[str, Any],
-) -> dict[str, Any]:
- analyzer = intent_analyzer_class(max_recent_messages=5)
- start = time.perf_counter()
- plan = await analyzer.analyze(
- compression_summary=case["compression_summary"],
- messages=_messages(case["recent_messages"]),
- current_message=case["current_message"],
- context_type=case["context_type"],
- target_abstract=case["target_abstract"],
- )
- elapsed = time.perf_counter() - start
- _print_plan(case_key, case["name"], elapsed, plan)
- return {
- "case": case_key,
- "elapsed_seconds": elapsed,
- "plan": {
- "reasoning": plan.reasoning,
- "queries": [asdict(query) for query in plan.queries],
- },
- }
-
-
-async def _main() -> int:
- parser = argparse.ArgumentParser(description=__doc__)
- parser.add_argument(
- "--config",
- default=str(DEFAULT_CONFIG),
- help="Path to ov.conf. Defaults to ~/.openviking/ov.conf.",
- )
- parser.add_argument(
- "--case",
- choices=["all", *CASES.keys()],
- default="all",
- help="Scenario to run.",
- )
- parser.add_argument(
- "--json",
- action="store_true",
- help="Print a machine-readable summary at the end.",
- )
- parser.add_argument(
- "--preserve-log-output",
- action="store_true",
- help="Use ov.conf log.output as-is. By default this smoke test logs to stdout.",
- )
- args = parser.parse_args()
-
- config_path = Path(args.config).expanduser()
- config = _load_config(config_path, preserve_log_output=args.preserve_log_output)
- intent_analyzer_class = _load_intent_analyzer_class()
- planner = _planner_summary(config)
-
- print(f"config: {config_path}")
- print("query_planner:")
- print(json.dumps(planner, ensure_ascii=False, indent=2))
-
- if not planner["uses_query_planner"]:
- print("ERROR: ov.conf did not load a dedicated query_planner.", file=sys.stderr)
- return 2
- if planner["model"] != EXPECTED_MODEL:
- print(
- f"ERROR: expected model {EXPECTED_MODEL!r}, got {planner['model']!r}.",
- file=sys.stderr,
- )
- return 2
-
- selected = CASES.keys() if args.case == "all" else [args.case]
- results = []
- for case_key in selected:
- results.append(await _run_case(intent_analyzer_class, case_key, CASES[case_key]))
-
- if args.json:
- print("\n=== json_summary ===")
- print(json.dumps({"query_planner": planner, "results": results}, ensure_ascii=False))
-
- return 0
-
-
-if __name__ == "__main__":
- try:
- raise SystemExit(asyncio.run(_main()))
- except Exception as exc:
- print(f"ERROR: {type(exc).__name__}: {exc}", file=sys.stderr)
- raise SystemExit(1)