Skip to content

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

更新下 skills 相关的doc (#5003)

DuTao9eeeda4e1bdc
diff --git a/bot/README.md b/bot/README.md
index 9c871a940..009b090ea 100644
--- a/bot/README.md
+++ b/bot/README.md
@@ -528,3 +528,4 @@ The repository includes `deploy/docker/deploy_langfuse.sh` for local deployment.
- [Channels, Gateway, and Operations](docs/en/concepts/03-channels-and-gateway.md)
- [VikingBot and OpenViking Integration](docs/en/concepts/04-openviking-integration.md)
- [Channel Configuration](docs/en/concepts/05-channel.md)
+- [Skills: Local and Remote](docs/en/concepts/06-skills.md)
diff --git a/bot/README_CN.md b/bot/README_CN.md
index 81bd4e527..3714bdaf5 100644
--- a/bot/README_CN.md
+++ b/bot/README_CN.md
@@ -525,3 +525,4 @@ Gateway 的 Bot API 前缀为 `/bot/v1`:
- [渠道、Gateway 与运行管理](docs/zh/concepts/03-channels-and-gateway.md)
- [VikingBot 与 OpenViking 集成](docs/zh/concepts/04-openviking-integration.md)
- [渠道配置](docs/zh/concepts/05-channel.md)
+- [Skills:本地与远程技能](docs/zh/concepts/06-skills.md)
diff --git a/bot/docs/en/concepts/02-agent-capabilities.md b/bot/docs/en/concepts/02-agent-capabilities.md
index 61e51d7ed..926b7a389 100644
--- a/bot/docs/en/concepts/02-agent-capabilities.md
+++ b/bot/docs/en/concepts/02-agent-capabilities.md
@@ -26,7 +26,7 @@ Workspace bootstrap files provide a stable identity and operating rules. Images
| **Skill** | Tells the Agent how to complete a class of tasks | `SKILL.md` instructions and resources |
| **Tool** | Lets the Agent perform a concrete operation | A JSON Schema function registered with the model |
-Skills use progressive loading. Every turn includes the full content of Always Skills. Other Skills contribute only their name, description, and path until the Agent reads them with `read_file`. SkillsLoader checks dependencies such as commands and environment variables so unavailable capabilities are not presented as ready.
+Skills use progressive loading. Local Always Skills inject complete instructions each turn; other local Skills provide summaries and load through `read_file` when needed. With OpenViking tools enabled, remote Skills are retrieved for the user query and read and activated through `openviking_multi_read`. Local requirements filter summaries; remote requirements are checked in the execution sandbox. See [Skills](./06-skills.md) for usage and metadata fields.
A Skill may orchestrate several tools, but it does not receive additional permissions automatically. Tool visibility still depends on the runtime mode, channel settings, request parameters, and sandbox.
@@ -188,3 +188,4 @@ Custom Hooks can be loaded through `bot.hooks`.
- [VikingBot Architecture](./01-architecture.md)
- [Channels, Gateway, and Operations](./03-channels-and-gateway.md)
- [OpenViking Integration](./04-openviking-integration.md)
+- [Skills](./06-skills.md)
diff --git a/bot/docs/en/concepts/04-openviking-integration.md b/bot/docs/en/concepts/04-openviking-integration.md
index 56fbb0c2f..340ebed8d 100644
--- a/bot/docs/en/concepts/04-openviking-integration.md
+++ b/bot/docs/en/concepts/04-openviking-integration.md
@@ -7,6 +7,7 @@ OpenViking is VikingBot's long-term context layer. VikingBot handles real-time c
```text
OpenViking → VikingBot
Resource: provide knowledge and file context for tasks
+ Skill: provide searchable task instructions and supporting resources
Memory: provide the current user/Peer's Profile, preferences, entities, and events
Experience: provide methods the Agent used to complete similar tasks in the past
Session: provide compressed history and conversation archives
@@ -154,6 +155,14 @@ OpenViking tools obtain the current actor peer and request-scoped connection thr
`openviking_add_resource` starts asynchronous resource processing and is not registered in `readonly` mode. `openviking_memory_commit` is intended for cases where the user explicitly asks the Agent to remember something.
+## Using Remote Skills
+
+Upload a Skill package with `ov add-skill ./skills/<name>/` to the OpenViking service used by the Bot, and ensure the Bot's current identity can read it. With `ov_tools_enable` enabled on the channel, an available connection, and `openviking_multi_read` not disabled, the Bot retrieves remote Skill summaries for the user query.
+
+The model reads the selected `SKILL.md` URI with `openviking_multi_read`, which validates and activates the Skill. You can also give the Bot a canonical `SKILL.md` URI returned by the service. Text references stay remote; scripts or tools that need local files trigger package download and path rewriting. Each user message activates Skills independently, and execution copies are cleaned at turn completion.
+
+No additional Remote Skill switch or manual download is required. See [Skills](./06-skills.md) for local/remote examples, frontmatter fields, tool policies, and `bot.remote_skills` configuration.
+
## Local Sessions and OpenViking Sessions
The two Session types have different responsibilities:
@@ -287,6 +296,7 @@ Bot Chat and OpenViking APIs can therefore share one Gateway address, while Open
- [VikingBot Architecture](./01-architecture.md)
- [Agent Capabilities](./02-agent-capabilities.md)
+- [Skills](./06-skills.md)
- [Channels, Gateway, and Operations](./03-channels-and-gateway.md)
- [OpenViking Architecture](../../../../docs/en/concepts/01-architecture.md)
- [OpenViking Context Types](../../../../docs/en/concepts/02-context-types.md)
diff --git a/bot/docs/en/concepts/06-skills.md b/bot/docs/en/concepts/06-skills.md
new file mode 100644
index 000000000..bad892724
--- /dev/null
+++ b/bot/docs/en/concepts/06-skills.md
@@ -0,0 +1,262 @@
+# VikingBot Skills
+
+A Skill describes when and how to perform a task in `SKILL.md`, alongside any supporting resources. The model reads those instructions and calls tools already registered in VikingBot. A Skill does not register tools or provide an execution backend.
+
+VikingBot supports local Skills in the active Workspace and remote Skills stored in OpenViking. This chapter describes the current implementation; see [RFC #3656](https://github.com/volcengine/OpenViking/discussions/3656) for the remote Skill design background.
+
+## Local and Remote Skills
+
+| Area | Local Skill | OpenViking remote Skill |
+|------|-------------|-------------------------|
+| Storage | `<active-workspace>/skills/<name>/` | Canonical Skill URI returned by OpenViking |
+| Discovery | Scan Workspace Skill directories | Call `find_skills` with the current user query; retrieve L0 summaries only |
+| Default context | Name, description, local path | Name, description, `SKILL.md` URI, read tool |
+| Read instructions | `read_file` | `openviking_multi_read`; reading the definition activates it |
+| `always` | Can inject the full instructions every turn | Does not enable persistent or automatic activation |
+| Requirements | Check the Bot process environment; hide unavailable summaries | Check the execution sandbox before the first ordinary tool call after activation |
+| `allowed-tools` | Not enforced by the local loader | Runtime enforces restrictions on tools for the current turn |
+| Resources | Already in the Workspace | Read text by URI; download the package when a tool needs local paths |
+| Lifetime | Files persist; rebuild context each turn | Activate for each user message; remove execution copies at turn completion |
+
+Both types remain subject to Bot, channel, request, and sandbox policies. Disabling OpenViking tools does not disable local Skill loading.
+
+## Using a Local Skill
+
+Place the Skill in the **active Workspace**, such as `<workspace>/shared/skills/` in the default `shared` mode. See [Workspace and Agent Customization](./02-agent-capabilities.md#workspace-and-agent-customization) for root paths and isolation modes.
+
+```text
+<active-workspace>/skills/report-summary/
+├── SKILL.md
+├── scripts/
+│ └── summarize.py
+├── references/
+│ └── report-format.md
+└── assets/
+ └── template.md
+```
+
+Discovery lists only immediate subdirectories containing `SKILL.md`; the directory name identifies a local Skill. Each turn normally includes summaries of Skills whose requirements are met. The model then reads `skills/report-summary/SKILL.md` when needed. A local Skill with `always: true` injects its instructions without frontmatter directly into context; supporting files still load on demand.
+
+`bot.skills` selects bundled templates to copy into the active Workspace. It is not an allowlist for runtime discovery. Initialization copies selected templates and skips existing directories with the same name; manually added Workspace Skills do not need to appear in this list. Explicit loading by name prefers Workspace files over bundled templates, while normal summary discovery scans the Workspace.
+
+Tool paths in local Skills are relative to the Workspace, for example `python3 skills/report-summary/scripts/summarize.py`. Reading `SKILL.md` does not change the working directory.
+
+## Using a Remote Skill
+
+### Setup
+
+1. Configure an available connection as described in [OpenViking Integration](./04-openviking-integration.md#connection-modes), and ensure the Bot's current identity can read the Skill.
+2. Upload the Skill to that OpenViking service. Upload the directory when it contains supporting files:
+
+ ```bash
+ ov add-skill ./skills/report-summary/
+ ```
+
+ Configure the CLI for the target service and an appropriately authorized identity. Save the returned URI. If the operation returns a background `task_id`, check progress with `ov task status TASK_ID`. See the [OpenViking Skills API](../../../../docs/en/api/04-skills.md) for other import methods.
+3. Keep `ov_tools_enable: true` on the current channel. `openviking_multi_read` must be registered and must not appear in `disabled_tools`.
+4. Describe a task to let the Bot select a Skill from remote summaries, or explicitly ask it to read a particular canonical `SKILL.md` URI.
+
+No additional Remote Skill switch or `load_skill` tool is needed. `bot.remote_skills` tunes retrieval and resource handling; it has no `enabled`, `default_materialize`, or `materialize_mode` fields.
+
+### Discovery, Activation, and Execution
+
+Each ordinary user message that needs a reply creates a `SkillRuntimeContext` spanning all model and tool iterations for that message:
+
+```text
+User query → find_skills → local + remote summaries
+ → openviking_multi_read(SKILL.md) → validate and activate
+ → refresh tool schemas → check requirements → resolve resources → execute
+ → save results and usage → close runtime and clean request copies
+```
+
+Name collisions prefer local Workspace Skills, then OpenViking user Skills, then shared Skills (`viking://agent/skills/`). A local directory shadows a remote candidate even if unmet requirements hide its local summary. Explicit URIs bypass name selection. Use canonical URIs actually returned by the service; a name alone is not a unique identity across users.
+
+For example, read a user Skill at the URI returned by the service:
+
+```json
+{
+ "name": "openviking_multi_read",
+ "arguments": {
+ "uris": ["viking://user/alice/skills/report-summary/SKILL.md"]
+ }
+}
+```
+
+Activation parses frontmatter and calls `get_skill(include_integrity=true)` to validate the content, canonical URI, revision, and file manifest. It does not download auxiliary files. Instructions returned to the model include bindings from package-relative paths to canonical resource URIs. Activation requires the complete definition. The read tool currently refuses full reads of files larger than 512 KiB by default, so move lengthy reference material into auxiliary files; partial reads cannot activate a definition.
+
+If the model requests activation and other tools in the same batch, activation runs first. Other calls return `SKILL_CONTEXT_UPDATED` so the model can retry with refreshed schemas. If activation fails, ordinary calls in that batch return `SKILL_ACTIVATION_FAILED` without executing.
+
+## SKILL.md and Metadata
+
+Use YAML frontmatter and place VikingBot extensions under `metadata.vikingbot`. This remote Skill example declares Python command permissions and a runtime requirement. Both `scripts/summarize.py` and `references/report-format.md` must exist in the package.
+
+```markdown
+---
+name: report-summary
+description: Summarize a report when the user requests a report review.
+allowed-tools: Bash(python3 *)
+tags: [reporting]
+metadata:
+ author: example-team
+ version: "1.0"
+ vikingbot:
+ always: false
+ requires:
+ bins: [python3]
+---
+
+# Report summary
+
+Read references/report-format.md with openviking_multi_read.
+Run python3 scripts/summarize.py and summarize its output.
+```
+
+### Field Reference
+
+| Field | Type / default | Current behavior |
+|-------|----------------|------------------|
+| `name` | String; required remotely | Must match the Skill name in the remote URI; local identity remains the directory name, so keep them consistent |
+| `description` | String; required remotely | Describes applicable tasks for model selection; local summaries fall back to the directory name when absent |
+| `allowed-tools` | Space-separated string or compatible string list; undeclared by default | Remote tool policy, described below; not enforced by the local loader |
+| `tags` | String list; `[]` | Classification data retained by OpenViking; does not change Bot permissions or activation |
+| `metadata` | YAML object or compatible JSON string | Extension metadata container |
+| `metadata.vikingbot` | Object | VikingBot extension scope; when present, extension fields are read from this object |
+| `metadata.vikingbot.always` | Boolean; `false` | Local only: inject complete instructions each turn when requirements are met |
+| `always` | Top-level boolean; `false` | Local compatibility form; ORed with scoped `always`; ignored by the remote runtime |
+| `metadata.vikingbot.requires.bins` | Command name list; `[]` | All commands must be available; no automatic installation |
+| `metadata.vikingbot.requires.env` | Environment variable name list; `[]` | All variables must pass environment checks; declare names, not values |
+| `metadata.vikingbot.emoji` | Optional string | Informational field used by some bundled templates; the current summary builder does not read it |
+| `metadata.vikingbot.os` | Optional string list | Platform information in some templates, such as `[darwin, linux]`; the current loader does not filter platforms with it |
+| `metadata.vikingbot.install` | Optional object list | Installation hints in some templates, commonly containing `id`, `kind`, `bins`, `label`, `formula`, or `package`; not executed automatically |
+| Other metadata, such as `author`, `version` | Custom | Informational; the Bot does not use it to control execution or version its cache |
+
+The frontmatter permission field must be **`allowed-tools`**. `allowed_tools` is the parsed structured-data field in OpenViking and does not replace the hyphenated field in `SKILL.md`. Use actual YAML booleans `true` / `false`, not strings such as `"false"`.
+
+Both older metadata forms below are supported. Prefer the scoped form for new Skills to keep Bot extensions separate from other systems' metadata:
+
+```yaml
+metadata:
+ requires:
+ bins: [python3]
+```
+
+```yaml
+metadata: '{"vikingbot":{"requires":{"bins":["python3"]}}}'
+```
+
+### Requirement Checks
+
+The local loader searches the Bot process `PATH` for commands and requires nonempty environment variable values. Missing requirements remove a Skill from both summaries and Always content. This is discovery filtering, not enforcement inside the execution sandbox.
+
+The remote runtime checks commands inside the sandbox that executes tools. Environment variables only need to be defined; empty values count as present, and values are neither read nor logged. Variable names must match `[A-Za-z_][A-Za-z0-9_]*`. Each active Skill is checked once per turn before its first ordinary tool call, regardless of whether files need downloading. The `openviking_multi_read` transport does not trigger these checks. Remote requirements also accept a single string for `bins` / `env`; lists work with both loaders.
+
+### Remote allowed-tools
+
+| Declaration | Meaning |
+|-------------|---------|
+| Omit `allowed-tools` | Do not further restrict the existing tool set |
+| `allowed-tools: []` or `allowed-tools: ""` | Deny ordinary task tools; retain the `openviking_multi_read` transport |
+| `allowed-tools: Read Bash` | Allow `read_file` and `exec` |
+| `allowed-tools: Bash(python3 *)` | Allow only a single `exec` command matching this pattern |
+| `allowed-tools: Bash(git:*)` | Compatible colon form that can match `git ...` |
+
+The runtime supports these aliases. Registered tool names such as `openviking_search` or `mcp_<server>_<tool>` can also be used directly.
+
+| Skill spelling | VikingBot tool |
+|----------------|----------------|
+| `Bash` / `exec` | `exec` |
+| `Read` / `read_file` | `read_file` |
+| `Write` / `write_file` | `write_file` |
+| `Edit` / `edit_file` | `edit_file` |
+| `Glob` | `openviking_glob` |
+| `Grep` | `openviking_grep` |
+| `WebFetch` / `web_fetch` | `web_fetch` |
+| `WebSearch` / `web_search` | `web_search` |
+| `spawn` | `spawn` |
+
+When multiple remote Skills are active, ordinary tool permissions are the intersection of every active Skill's policy, subject to existing Bot/channel/request policies. Restrictions cover subsequent ordinary tool calls throughout the turn, including calls that do not reference package files. A Skill cannot restore disabled tools. `openviking_multi_read` is exempt from the Skill policy intersection but must still be available in the Bot.
+
+Multiple Bash patterns within a Skill are alternatives; patterns across Skills must all be satisfied. Patterns match the entire command string. Constrained Bash rejects pipes, redirection, command chaining, newlines, backticks, and `$()` shell substitutions. Plain `Bash` does not add this command matching restriction. Parenthesized argument constraints on other tools, such as `Read(...)`, are currently rejected. Invoke scripts through an explicit interpreter such as `python3` or `bash`; do not depend on executable file permissions after download.
+
+## Remote Resources and Local Paths
+
+After activation, use `openviking_multi_read` for text references. Materialization downloads the Skill package into the sandbox and rewrites arguments only when `exec` references a packaged file or a tool's declared input needs a local file/directory.
+
+| Example input | Behavior |
+|---------------|----------|
+| `openviking_multi_read` of `references/report-format.md` | Resolve a unique active-package match to a canonical URI and read remotely |
+| `exec` with `python3 scripts/summarize.py` | Match the manifest, download the package, and rewrite the script path |
+| Full `viking://.../assets/template.md` in an active package | Read remotely or provide a local path according to the consuming tool |
+| `scripts/summarize.py` present in multiple active packages | Reject the ambiguous path; require its canonical URI |
+| Ordinary Workspace file `workspace:input/report.csv` | Remove `workspace:` before passing it to the local file tool or `exec` |
+| Native absolute path in the current sandbox, HTTP / Data URL | Pass through to the consuming tool |
+| Unmatched bare relative file path, directory traversal, or resource from an inactive Skill | Reject; identify the source or read the corresponding `SKILL.md` first |
+
+`workspace:` is for local file parameters and `exec`; it does not make `openviking_multi_read` read Workspace files. Save outputs in the ordinary Workspace too, for example by using `workspace:output/summary.md` in command arguments, so they survive cleanup of the temporary Skill package.
+
+The runtime preserves the package directory structure but does not change the tool's working directory to the package root. Scripts should locate adjacent templates and modules relative to their own files. The model should use returned resource bindings directly, without copying resources manually or setting `working_dir` to a remote URI, cache path, or materialization directory. Execution failure does not automatically download more files and rerun the command.
+
+Tool developers declare local input parameters through `Tool.resource_inputs`, for example `{"path": "local_file", "/files/*/workspace_path": "local_file"}`. Supported kinds are `local_file` and `local_directory`; JSON Pointer style paths support `*`. Undeclared parameters are not processed just because their names resemble paths. Do not declare output parameters as inputs. This declaration belongs to the tool implementation, not Skill metadata.
+
+## Lifecycle, Cache, and Configuration
+
+Each user message discovers and activates remote Skills again. Later turns in the same Session do not inherit candidates, permission intersections, or requirement check results. Tool usage records include real `skill_uri` / `skill_uris` and resolved `resolved_args`. The current implementation uses ordinary tool-result recording for Sessions, events, and traces, so Skill instructions may enter those records too. The RFC's separate redacted views and exclusion of persisted Skill instructions are not guarantees of the current implementation.
+
+File storage has two layers:
+
+| Layer | Current path | Lifetime |
+|-------|--------------|----------|
+| Bot host cache | `<bot-data>/remote_skill_cache/` | Isolated by permission scope, canonical root URI, and server revision; evicted by TTL/LRU |
+| Tool execution copy | `<sandbox>/.remote-skill/<request-id>/<root-uri-sha256>/<skill-name>/` | Reused within the current turn and cleaned at completion; tools do not execute host cache files directly |
+
+`.remote-skill/` is the current implementation path. Cache hits still require reading and activating with the current identity and rechecking the manifest. Files are validated by size and SHA-256 before use in the request sandbox. Revision changes or failed file validation prevent further use of that snapshot. Caching avoids repeated downloads without bypassing OpenViking ACL; `metadata.version` is not the cache revision.
+
+These fields belong under **`bot.remote_skills`** in `ov.conf`. They are deployment configuration, not frontmatter:
+
+| Field | Default | Purpose |
+|-------|---------|---------|
+| `discovery_limit` | `8` | Maximum remote candidates injected; range 1–50 |
+| `score_threshold` | `0.35` | Minimum retrieval score; range 0–1 |
+| `discovery_timeout_seconds` | `2.0` | Discovery timeout in seconds; greater than 0 and at most 30 |
+| `max_files` | `128` | Maximum materialized files per package, including `SKILL.md` |
+| `max_file_bytes` | `8388608` (8 MiB) | Maximum individual file size; also applies to `SKILL.md` at activation |
+| `max_total_bytes` | `33554432` (32 MiB) | Maximum materialized package size |
+| `cache_idle_ttl_seconds` | `600` | Host cache idle TTL, refreshed on hits |
+| `cache_max_entries` | `32` | Maximum cached snapshots |
+| `cache_max_bytes` | `268435456` (256 MiB) | Maximum host cache size |
+
+File counts, sizes, and cache capacities must be positive. Later cache activity cleans expired entries; capacity pressure evicts unused entries by LRU. Server integrity API limits also apply, so increasing Bot limits cannot override server limits.
+
+## Subagents and Troubleshooting
+
+Subagents use local Workspace Skill summaries and Always content. They currently do not register OpenViking tools, so they do not discover, activate, or inherit the main Agent's remote Skill runtime or snapshots.
+
+| Symptom or error | What to check |
+|------------------|---------------|
+| Local Skill missing from summaries | Active Workspace, `SKILL.md` in an immediate Skill subdirectory, and commands/environment in the Bot process |
+| No remote candidates | Connection, channel switch, disabled tools, score/timeout, and local name collisions; discovery failure leaves local context available |
+| `SKILL_NOT_ACTIVE` | Read that package's `SKILL.md` with `openviking_multi_read` first |
+| `SKILL_TOOL_NOT_ALLOWED` | All active Skills' intersected permissions and Bash command constraints |
+| `SKILL_CAPABILITY_UNAVAILABLE` | Provide required commands/environment in the execution sandbox and ensure the sandbox is available |
+| `SKILL_RESOURCE_NOT_FOUND` / `SKILL_RESOURCE_AMBIGUOUS` | Use returned canonical resource URIs; use `workspace:` for ordinary Workspace inputs |
+| `SKILL_INTEGRITY_UNAVAILABLE` / `SKILL_REVISION_CHANGED` | Ensure server support for integrity manifests; read again in a new turn after Skill updates finish |
+| `SKILL_PACKAGE_TOO_LARGE` | Reduce package resources or review Bot and server limits |
+
+## Implementation Locations
+
+| Area | Path (relative to `bot/` unless stated otherwise) |
+|------|-------------------------------------------------|
+| Local loading, metadata, requirement filtering | `vikingbot/agent/skills.py` |
+| Main Agent / subagent Skill context | `vikingbot/agent/context.py`, `vikingbot/agent/subagent.py` |
+| Request runtime, activation, policies, resources | `vikingbot/agent/remote_skills.py` |
+| Cache and Workspace initialization | `vikingbot/agent/remote_skill_cache.py`, `vikingbot/sandbox/manager.py` |
+| Tool batches, schemas, and calls | `vikingbot/agent/loop.py`, `vikingbot/agent/tools/registry.py` |
+| Remote reads and Experience Hook | `vikingbot/agent/tools/ov_file.py`, `vikingbot/hooks/builtins/openviking_hooks.py` |
+| Configuration defaults | `vikingbot/config/schema.py` |
+| OpenViking frontmatter parsing | `openviking/core/skill_loader.py` at the repository root |
+
+## Related Documentation
+
+- [Agent Capabilities](./02-agent-capabilities.md)
+- [VikingBot and OpenViking Integration](./04-openviking-integration.md)
+- [OpenViking Skills API](../../../../docs/en/api/04-skills.md)
diff --git a/bot/docs/zh/concepts/02-agent-capabilities.md b/bot/docs/zh/concepts/02-agent-capabilities.md
index a3b044dd2..0950ae7e7 100644
--- a/bot/docs/zh/concepts/02-agent-capabilities.md
+++ b/bot/docs/zh/concepts/02-agent-capabilities.md
@@ -26,7 +26,7 @@ Bot 身份
| **Skill** | 告诉 Agent 如何完成一类任务 | `SKILL.md` 指令和资源 |
| **Tool** | 让 Agent执行具体操作 | 注册给模型的 JSON Schema 函数 |
-Skill 采用渐进式加载:Always Skill 每轮注入完整内容,其他 Skill 只注入名称、描述和路径,Agent 需要时再用 `read_file` 读取。SkillsLoader 会检查命令和环境变量等依赖,避免暴露尚不可用的能力。
+Skill 采用渐进式加载:本地 Always Skill 每轮注入完整内容,其他本地 Skill 只注入摘要,需要时用 `read_file` 读取;启用 OpenViking 工具后,远程 Skill 按用户问题召回摘要,再用 `openviking_multi_read` 读取并激活。本地依赖用于过滤摘要,远程依赖在执行沙箱检查。完整用法和元数据字段见 [Skills](./06-skills.md)。
Skill 可以编排多个工具,但不会自动获得额外权限。工具是否可见仍由运行模式、渠道设置、请求参数和沙箱决定。
@@ -188,3 +188,4 @@ HookManager 提供运行时扩展点。当前内置 Hook 主要用于:
- [VikingBot 架构](./01-architecture.md)
- [渠道、Gateway 与运行管理](./03-channels-and-gateway.md)
- [与 OpenViking 集成](./04-openviking-integration.md)
+- [Skills](./06-skills.md)
diff --git a/bot/docs/zh/concepts/04-openviking-integration.md b/bot/docs/zh/concepts/04-openviking-integration.md
index 216c2837f..3099c13db 100644
--- a/bot/docs/zh/concepts/04-openviking-integration.md
+++ b/bot/docs/zh/concepts/04-openviking-integration.md
@@ -7,6 +7,7 @@ OpenViking 是 VikingBot 的长期上下文层。VikingBot 自己负责实时对
```text
OpenViking → VikingBot
Resource:为任务提供知识与文件上下文
+ Skill:提供可检索的任务指令与配套资源
Memory:提供当前用户/Peer 的 Profile、偏好、实体和事件
Experience:提供 Agent 过去完成类似任务的方法
Session:提供压缩历史和会话归档
@@ -154,6 +155,14 @@ OpenViking 工具通过 ToolContext 获得当前 actor peer 和 request-scoped c
`openviking_add_resource` 是异步资源处理操作;`readonly` 模式不注册该工具。`openviking_memory_commit` 适用于用户明确要求“记住”某项信息的场景。
+## 使用远程 Skill
+
+先用 `ov add-skill ./skills/<name>/` 将 Skill 包上传到 Bot 所连接的 OpenViking 服务,并确认 Bot 当前身份有读取权限。当前渠道启用 `ov_tools_enable`、连接可用且 `openviking_multi_read` 未被禁用时,Bot 会根据用户问题检索远程 Skill 摘要。
+
+模型用 `openviking_multi_read` 读取选中的 `SKILL.md` URI 后,运行时自动校验并激活 Skill;也可以直接向 Bot 提供服务返回的 canonical `SKILL.md` URI。文本引用继续远程读取,脚本或工具需要本地文件时才下载包并改写路径。每条用户消息独立激活,执行副本在本 Turn 结束时清理。
+
+无需额外的 Remote Skill 开关或手工下载步骤。本地/远程使用示例、frontmatter 字段、工具权限和 `bot.remote_skills` 配置见 [Skills](./06-skills.md)。
+
## 本地 Session 与 OpenViking Session
两类 Session 不应混淆:
@@ -287,6 +296,7 @@ Bot Chat 与 OpenViking API 因而可以通过同一个 Gateway 地址访问,
- [VikingBot 架构](./01-architecture.md)
- [Agent 能力体系](./02-agent-capabilities.md)
+- [Skills](./06-skills.md)
- [渠道、Gateway 与运行管理](./03-channels-and-gateway.md)
- [OpenViking 架构](../../../../docs/zh/concepts/01-architecture.md)
- [OpenViking 上下文类型](../../../../docs/zh/concepts/02-context-types.md)
diff --git a/bot/docs/zh/concepts/06-skills.md b/bot/docs/zh/concepts/06-skills.md
new file mode 100644
index 000000000..8a9ce6d2d
--- /dev/null
+++ b/bot/docs/zh/concepts/06-skills.md
@@ -0,0 +1,262 @@
+# VikingBot Skills
+
+Skill 用 `SKILL.md` 描述一类任务的触发条件、操作步骤和配套资源。模型读取这些指令,再调用 VikingBot 已注册的工具完成任务。Skill 本身不注册工具,也不提供新的执行后端。
+
+VikingBot 支持活动 Workspace 中的本地 Skill,以及保存在 OpenViking 中的远程 Skill。本文按当前代码说明行为;远程方案的设计背景见 [RFC #3656](https://github.com/volcengine/OpenViking/discussions/3656)。
+
+## 本地与远程
+
+| 项目 | 本地 Skill | OpenViking 远程 Skill |
+|------|------------|----------------------|
+| 存储 | `<active-workspace>/skills/<name>/` | OpenViking 返回的 canonical Skill URI |
+| 发现 | 扫描工作区 Skill 目录 | 按当前用户问题调用 `find_skills`,只召回 L0 摘要 |
+| 默认上下文 | 名称、描述、本地路径 | 名称、描述、`SKILL.md` URI、读取工具 |
+| 读取正文 | `read_file` | `openviking_multi_read`;读取定义后激活 |
+| `always` | 可每轮注入完整正文 | 不支持自动常驻激活 |
+| 依赖检查 | 在 Bot 进程环境检查,缺失时隐藏摘要 | 激活后、首次普通工具调用前在实际执行沙箱检查 |
+| `allowed-tools` | 本地加载器不据此限制工具 | 运行时强制限制当前 Turn 的工具集 |
+| 配套资源 | 已在工作区内 | 文本按 URI 读取;工具需要本地路径时下载整个包 |
+| 生命周期 | 文件持续保留,每轮重新构建上下文 | 每条用户消息独立激活;Turn 结束清理执行副本 |
+
+两种 Skill 都受 Bot、渠道、请求的工具可见性和沙箱策略约束。关闭 OpenViking 工具不影响本地 Skill 加载。
+
+## 使用本地 Skill
+
+将 Skill 放到**活动 Workspace**,例如默认 `shared` 模式下的 `<workspace>/shared/skills/`。根目录解析与隔离模式见 [Workspace 与 Agent 定制](./02-agent-capabilities.md#workspace-与-agent-定制)。
+
+```text
+<active-workspace>/skills/report-summary/
+├── SKILL.md
+├── scripts/
+│ └── summarize.py
+├── references/
+│ └── report-format.md
+└── assets/
+ └── template.md
+```
+
+只有直接子目录中存在 `SKILL.md` 的 Skill 才会被列出;本地名称来自目录名。默认每轮只注入满足依赖的 Skill 摘要,模型选择后读取 `skills/report-summary/SKILL.md`。`always: true` 的本地 Skill 会直接注入去掉 frontmatter 的正文,辅助文件仍需按需读取。
+
+`bot.skills` 是从内置模板复制到活动 Workspace 的 Skill 名称列表,不是运行时扫描的白名单。初始化时只复制名单中的模板,并跳过已有的同名目录;自行放入活动 Workspace 的 Skill 无需加入该列表。显式按名称加载时,工作区文件优先于内置模板;正常摘要列表扫描的是工作区目录。
+
+本地 Skill 中的工具路径以工作区为基准,例如 `python3 skills/report-summary/scripts/summarize.py`;不能假设读取 `SKILL.md` 会切换工作目录。
+
+## 使用远程 Skill
+
+### 准备与启用
+
+1. 按 [OpenViking 集成](./04-openviking-integration.md#连接模式) 配置可用连接,并确保 Bot 当前身份有权读取目标 Skill。
+2. 将 Skill 上传到同一 OpenViking 服务。有辅助文件时上传目录,保留整个包:
+
+ ```bash
+ ov add-skill ./skills/report-summary/
+ ```
+
+ CLI 应连接目标服务并使用具有相应权限的身份。保存返回的 URI;若返回后台 `task_id`,可用 `ov task status TASK_ID` 检查处理进度。完整导入方式见 [OpenViking Skills API](../../../../docs/zh/api/04-skills.md)。
+3. 当前渠道保持 `ov_tools_enable: true`,并且 `openviking_multi_read` 已注册、未被 `disabled_tools` 禁用。
+4. 向 Bot 描述任务,让它从远程摘要中选择 Skill;也可以明确要求读取某个 `SKILL.md` 的 canonical URI。
+
+不需要额外的 Remote Skill 开关或 `load_skill` 工具。`bot.remote_skills` 只调整检索和缓存等参数,不提供 `enabled`、`default_materialize` 或 `materialize_mode`。
+
+### 发现、激活和执行
+
+每条需要回复的普通用户消息创建一个 `SkillRuntimeContext`,覆盖本条消息的全部模型与工具迭代:
+
+```text
+用户问题 → find_skills → 本地 + 远程摘要
+ → openviking_multi_read(SKILL.md) → 校验并激活
+ → 更新工具 Schema → 依赖检查 → 按需解析资源 → 执行工具
+ → 保存结果和使用记录 → 关闭运行时、清理请求副本
+```
+
+同名候选优先级是本地工作区、OpenViking 用户 Skill、OpenViking 共享 Skill(`viking://agent/skills/`)。本地目录即使因缺少依赖未出现在摘要中,也会遮蔽同名远程候选。显式 URI 不走名称选择,应使用服务实际返回的 canonical URI;不要把名称当作跨用户唯一标识。
+
+例如,对服务返回的用户 Skill URI 发起工具调用:
+
+```json
+{
+ "name": "openviking_multi_read",
+ "arguments": {
+ "uris": ["viking://user/alice/skills/report-summary/SKILL.md"]
+ }
+}
+```
+
+激活会解析 frontmatter,并通过 `get_skill(include_integrity=true)` 校验正文、canonical URI、revision 和文件清单。此时不下载辅助文件。模型收到的正文附带包内相对路径与 canonical URI 的映射。激活需要完整正文;当前读取工具默认拒绝完整返回超过 512 KiB 的文件,因此应将大段参考资料拆到辅助文件,不能通过分段读取来激活定义。
+
+如果模型在同一批中同时请求读取定义和执行其他工具,运行时先处理激活,其余调用返回 `SKILL_CONTEXT_UPDATED`,由模型在新 Schema 下重试;激活失败时返回 `SKILL_ACTIVATION_FAILED`,不执行同批普通工具。
+
+## SKILL.md 与元数据
+
+建议使用 YAML frontmatter,并将 VikingBot 扩展放在 `metadata.vikingbot` 下。下面的远程 Skill 示例声明了 Python 命令权限和依赖;`scripts/summarize.py`、`references/report-format.md` 必须实际存在于包中。
+
+```markdown
+---
+name: report-summary
+description: Summarize a report when the user requests a report review.
+allowed-tools: Bash(python3 *)
+tags: [reporting]
+metadata:
+ author: example-team
+ version: "1.0"
+ vikingbot:
+ always: false
+ requires:
+ bins: [python3]
+---
+
+# Report summary
+
+Read references/report-format.md with openviking_multi_read.
+Run python3 scripts/summarize.py and summarize its output.
+```
+
+### 字段参考
+
+| 字段 | 类型 / 默认 | 当前行为 |
+|------|-------------|----------|
+| `name` | 字符串;远程必填 | 远程激活时必须与 URI 中的 Skill 名称一致;本地仍以目录名标识 Skill,建议两者一致 |
+| `description` | 字符串;远程必填 | 描述适用任务,供模型选择;本地未提供时摘要回退到目录名 |
+| `allowed-tools` | 空格分隔字符串,也兼容字符串列表;默认未声明 | 远程工具策略,详见下一节;本地加载器不执行该策略 |
+| `tags` | 字符串列表;默认 `[]` | OpenViking 保留的分类信息,不改变 Bot 工具权限或触发方式 |
+| `metadata` | YAML 对象,也兼容 JSON 字符串 | 扩展元数据容器 |
+| `metadata.vikingbot` | 对象 | VikingBot 识别的扩展作用域;存在时从此对象读取扩展字段 |
+| `metadata.vikingbot.always` | 布尔值;默认 `false` | 仅本地:依赖满足时,每轮注入完整正文 |
+| `always` | 顶层布尔值;默认 `false` | 本地兼容写法,与 scoped `always` 按“或”判断;远程运行时不读取 |
+| `metadata.vikingbot.requires.bins` | 命令名列表;默认 `[]` | 所有命令都必须可用;不会自动安装 |
+| `metadata.vikingbot.requires.env` | 环境变量名列表;默认 `[]` | 所有变量都必须满足环境检查;声明变量名,不在 Skill 中写值 |
+| `metadata.vikingbot.emoji` | 字符串;可选 | 部分内置模板使用的说明信息,当前 Skill 摘要生成器不读取 |
+| `metadata.vikingbot.os` | 字符串列表;可选 | 部分模板声明的平台信息,如 `[darwin, linux]`;当前加载器不据此过滤平台 |
+| `metadata.vikingbot.install` | 对象列表;可选 | 部分模板中的安装说明,常含 `id`、`kind`、`bins`、`label`、`formula` 或 `package`;当前 Bot 不自动执行 |
+| 其他 metadata,如 `author`、`version` | 自定义 | 可作说明信息,当前 Bot 不据此控制执行或缓存版本 |
+
+frontmatter 的权限字段必须是 **`allowed-tools`**。`allowed_tools` 是 OpenViking 解析后的结构化数据字段,不能替代 `SKILL.md` 中带连字符的字段。用真正的 YAML 布尔值 `true` / `false`,不要写字符串 `"false"`。
+
+以下两种旧 metadata 写法也受支持;新 Skill 建议采用上面的作用域形式,避免其他系统的扩展字段与 Bot 混在一起:
+
+```yaml
+metadata:
+ requires:
+ bins: [python3]
+```
+
+```yaml
+metadata: '{"vikingbot":{"requires":{"bins":["python3"]}}}'
+```
+
+### 依赖检查的区别
+
+本地加载器用 Bot 进程的 `PATH` 查找命令,并要求环境变量值非空。缺少依赖的 Skill 不进入摘要或 Always 内容;这属于发现过滤,不是执行沙箱中的权限检查。
+
+远程运行时在真正执行工具的沙箱内检查命令;环境变量只检查是否已定义,空值也算存在,不读取或记录值。环境变量名必须符合 `[A-Za-z_][A-Za-z0-9_]*`。每个激活 Skill 在本 Turn 首次普通工具调用前检查一次,与是否下载文件无关;`openviking_multi_read` 作为读取通道不触发这项检查。远程也接受单个字符串形式的 `bins` / `env`,但统一使用列表可兼容本地加载器。
+
+### 远程 allowed-tools
+
+| 声明 | 含义 |
+|------|------|
+| 不写 `allowed-tools` | 不额外收窄已有工具集 |
+| `allowed-tools: []` 或 `allowed-tools: ""` | 不允许普通任务工具;保留 `openviking_multi_read` 读取通道 |
+| `allowed-tools: Read Bash` | 允许 `read_file` 和 `exec` |
+| `allowed-tools: Bash(python3 *)` | 只允许匹配该模式的单条 `exec` 命令 |
+| `allowed-tools: Bash(git:*)` | 兼容冒号写法,可匹配 `git ...` |
+
+运行时支持的别名如下;也可以直接填写已注册的工具名,如 `openviking_search` 或 `mcp_<server>_<tool>`。
+
+| Skill 写法 | VikingBot 工具 |
+|------------|---------------|
+| `Bash` / `exec` | `exec` |
+| `Read` / `read_file` | `read_file` |
+| `Write` / `write_file` | `write_file` |
+| `Edit` / `edit_file` | `edit_file` |
+| `Glob` | `openviking_glob` |
+| `Grep` | `openviking_grep` |
+| `WebFetch` / `web_fetch` | `web_fetch` |
+| `WebSearch` / `web_search` | `web_search` |
+| `spawn` | `spawn` |
+
+多个远程 Skill 同时激活时,普通工具权限取所有已激活 Skill 的交集,再受原有 Bot/渠道/请求策略限制。限制覆盖本 Turn 后续的普通工具调用,不仅是引用该包文件的调用。Skill 无法恢复已禁用工具;`openviking_multi_read` 豁免 Skill 策略交集,但仍须在 Bot 中可用。
+
+同一个 Skill 的多个 Bash 模式按“或”匹配,不同 Skill 之间按“且”匹配。模式匹配完整命令字符串;带参数约束时拒绝管道、重定向、命令连接、换行、反引号和 `$()` 等复合 shell 语法。无参数约束的 `Bash` 不增加这层命令匹配。其他工具暂不支持括号参数约束,例如 `Read(...)` 会被拒绝。需要执行脚本时应显式使用 `python3`、`bash` 等解释器,不依赖下载后的可执行位。
+
+## 远程资源与本地路径
+
+激活之后,文本说明仍用 `openviking_multi_read` 读取。`exec` 引用包内文件,或普通工具声明的输入参数需要本地文件/目录时,运行时才把 Skill 包下载到沙箱并改写参数。
+
+| 输入示例 | 处理 |
+|----------|------|
+| `openviking_multi_read` 读取 `references/report-format.md` | 唯一匹配已激活包后转换为 canonical URI,远程读取 |
+| `exec` 执行 `python3 scripts/summarize.py` | 匹配清单,下载整个包,改写脚本路径 |
+| 已激活包内的完整 `viking://.../assets/template.md` | 按消费工具要求远程读取或转成本地路径 |
+| 多个包都有 `scripts/summarize.py` | 拒绝模糊路径,要求完整 canonical URI |
+| 普通工作区文件 `workspace:input/report.csv` | 去掉 `workspace:` 前缀,传给原本地文件工具或 `exec` |
+| 当前沙箱的原生绝对路径、HTTP / Data URL | 原样交给消费工具 |
+| 未匹配的裸相对文件路径、目录逃逸或未激活包的资源 | 拒绝;先确认来源或读取对应 `SKILL.md` |
+
+`workspace:` 用于本地文件参数与 `exec`;它不是 `openviking_multi_read` 的工作区读取协议。输出也应保存在普通工作区,例如命令参数使用 `workspace:output/summary.md`,避免 Turn 结束时跟随临时 Skill 包被删除。
+
+运行时保留包内目录结构,但不会把工具工作目录切到包根。脚本应根据自己的文件位置解析相邻模板和模块;模型直接使用返回的资源绑定,不应手工复制资源或把 `working_dir` 设置成远程 URI、缓存路径或物化目录。执行失败不会自动补下载并重跑原命令。
+
+工具开发者通过 `Tool.resource_inputs` 声明本地输入参数,例如 `{"path": "local_file", "/files/*/workspace_path": "local_file"}`。支持 `local_file`、`local_directory` 和带 `*` 的 JSON Pointer 风格路径。未声明的参数不会仅因名字像路径而自动处理;输出参数不应声明成输入。此声明属于工具实现,不是 Skill metadata。
+
+## 生命周期、缓存与配置
+
+每条用户消息重新发现、激活远程 Skill;同一 Session 下一轮不会继承候选、权限交集或依赖检查结果。工具使用记录包含真实 `skill_uri` / `skill_uris` 和解析后的 `resolved_args`。当前代码沿用普通工具结果的 Session、事件和 Trace 记录流程,读取到的 Skill 正文也可能进入这些记录;RFC 提出的独立脱敏视图和正文不持久化不能视为当前实现保证。
+
+文件分为两层存储:
+
+| 层级 | 当前路径 | 生命周期 |
+|------|----------|----------|
+| Bot 主机缓存 | `<bot-data>/remote_skill_cache/` | 按权限域、canonical 根 URI 和服务端 revision 隔离,TTL/LRU 淘汰 |
+| 工具执行副本 | `<sandbox>/.remote-skill/<request-id>/<root-uri-sha256>/<skill-name>/` | 当前 Turn 内复用,结束时清理;不会直接执行主缓存文件 |
+
+这里的 `.remote-skill/` 是当前代码路径。缓存命中仍需当前身份成功读取、激活并复查 manifest;随后逐文件校验大小和 SHA-256,复制到请求沙箱。版本变化或文件校验失败时拒绝继续使用该快照。缓存减少重复下载,不跳过 OpenViking ACL,也不以 `metadata.version` 作为缓存版本。
+
+以下字段位于 `ov.conf` 的 **`bot.remote_skills`** 对象中,都是部署配置,不是 frontmatter:
+
+| 字段 | 默认值 | 作用 |
+|------|--------|------|
+| `discovery_limit` | `8` | 最多注入的远程候选数,范围 1–50 |
+| `score_threshold` | `0.35` | 最低召回分数,范围 0–1 |
+| `discovery_timeout_seconds` | `2.0` | 发现超时秒数,须大于 0 且不超过 30 |
+| `max_files` | `128` | 单包物化文件数,包含 `SKILL.md` |
+| `max_file_bytes` | `8388608`(8 MiB) | 单文件大小;读取激活的 `SKILL.md` 也受此限制 |
+| `max_total_bytes` | `33554432`(32 MiB) | 单包物化总大小 |
+| `cache_idle_ttl_seconds` | `600` | 主缓存空闲 TTL,命中后刷新 |
+| `cache_max_entries` | `32` | 主缓存最多保留的快照数 |
+| `cache_max_bytes` | `268435456`(256 MiB) | 主缓存总大小上限 |
+
+文件数、大小和缓存容量须为正数。过期缓存会在后续缓存活动时清理;容量不足按 LRU 淘汰未占用条目。服务端完整性 API 的限制也会生效,调大 Bot 限额不能绕过服务端限制。
+
+## 子 Agent 与常见问题
+
+子 Agent 使用工作区本地 Skill 摘要和 Always 内容。当前子 Agent 不注册 OpenViking 工具,因此不发现、激活或继承主 Agent 的远程 Skill 运行时与快照。
+
+| 现象或错误 | 检查方式 |
+|------------|----------|
+| 本地 Skill 未出现在摘要 | 检查活动 Workspace、直接子目录中的 `SKILL.md`,以及 Bot 进程的命令和环境变量 |
+| 无远程候选 | 检查连接、渠道开关、工具禁用、检索分数/超时、同名本地目录;发现失败时继续使用本地上下文 |
+| `SKILL_NOT_ACTIVE` | 先用 `openviking_multi_read` 读取该包的 `SKILL.md` |
+| `SKILL_TOOL_NOT_ALLOWED` | 检查所有已激活 Skill 的权限交集,以及 Bash 命令约束 |
+| `SKILL_CAPABILITY_UNAVAILABLE` | 在实际执行沙箱提供声明的命令/环境变量,确认沙箱可用 |
+| `SKILL_RESOURCE_NOT_FOUND` / `SKILL_RESOURCE_AMBIGUOUS` | 使用返回的 canonical 资源 URI;普通工作区输入使用 `workspace:` |
+| `SKILL_INTEGRITY_UNAVAILABLE` / `SKILL_REVISION_CHANGED` | 确认服务端支持完整性清单;Skill 更新完成后在新 Turn 重新读取 |
+| `SKILL_PACKAGE_TOO_LARGE` | 精简包内资源,或核对 Bot 与服务端限制 |
+
+## 实现位置
+
+| 内容 | 路径(相对 `bot/`,另有说明除外) |
+|------|------------------------------------------------|
+| 本地加载、metadata 和依赖过滤 | `vikingbot/agent/skills.py` |
+| 主 Agent / 子 Agent 的 Skill 上下文 | `vikingbot/agent/context.py`、`vikingbot/agent/subagent.py` |
+| 请求运行时、激活、策略与资源解析 | `vikingbot/agent/remote_skills.py` |
+| 缓存与工作区初始化 | `vikingbot/agent/remote_skill_cache.py`、`vikingbot/sandbox/manager.py` |
+| 工具批次、Schema 与调用处理 | `vikingbot/agent/loop.py`、`vikingbot/agent/tools/registry.py` |
+| 远程读取与 Experience Hook | `vikingbot/agent/tools/ov_file.py`、`vikingbot/hooks/builtins/openviking_hooks.py` |
+| 配置默认值 | `vikingbot/config/schema.py` |
+| OpenViking frontmatter 解析 | 仓库根目录 `openviking/core/skill_loader.py` |
+
+## 相关文档
+
+- [Agent 能力体系](./02-agent-capabilities.md)
+- [VikingBot 与 OpenViking 集成](./04-openviking-integration.md)
+- [OpenViking Skills API](../../../../docs/zh/api/04-skills.md)
diff --git a/docs/en/api/04-skills.md b/docs/en/api/04-skills.md
index d1034199e..7e81415b1 100644
--- a/docs/en/api/04-skills.md
+++ b/docs/en/api/04-skills.md
@@ -1,6 +1,6 @@
# Skills
-Skills are callable capabilities that agents can invoke. This module provides skill addition and management functionality.
+Skills are task instructions and supporting resources for agents to read. OpenViking stores, retrieves, and manages them; the consuming Agent/Harness handles activation, tool policies, and execution. This page follows the HTTP API, SDKs, and `ov` CLI in the current repository.
## Core Concepts
@@ -10,14 +10,14 @@ OpenViking supports multiple skill definition formats:
1. **Structured skill data**: Dictionary with name, description, content, etc.
2. **SKILL.md files**: Markdown files with YAML frontmatter
-3. **MCP Tool format**: Automatically detected and converted to OpenViking skill format
+3. **MCP Tool format**: Converted into Skill documentation; does not connect to an MCP server or register executable tools
+4. **Skill packages and collections**: Directories or ZIPs containing `SKILL.md` and auxiliary files, or Git repository / GitHub tree URLs
### Skill Storage Structure
-Skills are stored under the current user's skills root. The home alias
-`viking://~/skills/` expands to `viking://user/{user_id}/skills/` for the
-authenticated request (the uid-less spelling `viking://user/skills/` is no longer
-accepted):
+Skills support the current user's private root `viking://user/{user_id}/skills/` and the account-shared root `viking://agent/skills/`. The add target resolves in this order: request `target_uri` → user `add_targets.skill_uri` → server `user_config_defaults.add_targets.skill_uri` → current user's private root. Access remains subject to the current identity and permissions.
+
+The home alias `viking://~/skills/` always resolves to the authenticated user's private root, independently of the configured add target. The uid-less `viking://user/skills/` and peer-scoped skills are unsupported. The private package layout below also applies under the shared root:
```
viking://user/{user_id}/skills/
@@ -41,12 +41,15 @@ Skills can be defined using SKILL.md files with YAML frontmatter:
---
name: skill-name
description: Brief description of the skill
-allowed_tools:
- - Tool1
- - Tool2
+allowed-tools: Read Bash(python3 *)
tags:
- tag1
- tag2
+metadata:
+ author: example-team
+ vikingbot:
+ requires:
+ bins: [python3]
---
# Skill Name
@@ -68,15 +71,18 @@ Concrete examples of skill invocation.
| Field | Type | Description |
|-------|------|-------------|
-| name | str | Skill name (kebab-case recommended) |
+| name | str | Nonempty; at most 64 ASCII letters, digits, underscores, or hyphens; kebab-case recommended |
| description | str | Brief description |
**Optional Fields**
| Field | Type | Description |
|-------|------|-------------|
-| allowed_tools | List[str] | Tools this skill can use |
+| allowed-tools | str / List[str] | Space-separated tool declarations or a compatible string list; parentheses can contain spaces; the consumer interprets and enforces policies |
| tags | List[str] | Tags for categorization |
+| metadata | object | Preserved extensions such as `metadata.vikingbot.requires`; OpenViking does not install these dependencies |
+
+Use hyphenated **`allowed-tools`** in `SKILL.md`; parsed structured data and API summaries use **`allowed_tools`**. Do not substitute the underscore spelling in frontmatter. An omitted declaration and an explicit empty declaration can have different Harness permissions; a summary with `allowed_tools: []` cannot distinguish them. Read the full definition before execution. See [VikingBot Skills](../../../bot/docs/en/concepts/06-skills.md) for instruction and metadata handling.
### MCP Format Automatic Conversion
@@ -85,7 +91,7 @@ OpenViking automatically detects and converts MCP tool definitions to skill form
**Detection Rule**: A dictionary is treated as MCP format if it contains an `inputSchema` field.
**Conversion Process**:
-1. Name is converted to kebab-case
+1. Underscores in the name are replaced with hyphens (camelCase is not converted automatically)
2. Description is preserved
3. Parameters are extracted from `inputSchema.properties`
4. Required fields are marked from `inputSchema.required`
@@ -115,8 +121,8 @@ Input (MCP format):
}
```
-Output (Skill format):
-```json
+Output (Python dictionary):
+```python
{
"name": "search-web",
"description": "Search the web",
@@ -155,27 +161,34 @@ Skills are a special type of resource that define actions or tools agents can pe
1. Receive skill data or uploaded temporary file
2. Detect data format (structured data, SKILL.md content, MCP format)
3. Parse skill definition
-4. Store to the current user's `viking://user/{user_id}/skills/` path
+4. Store the package under the selected private or account-shared skills root
5. Return a `task_id` by default for tracking background vectorization
**Code Entry Points**:
- `sdk/python/openviking_sdk/client.py:AsyncHTTPClient.add_skill` - Python SDK entry point
-- `openviking_cli/client/http.py:AsyncHTTPClient.add_skill` - SDK entry point (HTTP)
+- `openviking_cli/client/http.py` - Compatibility import forwarding to the Python SDK
- `openviking/server/routers/resources.py:add_skill` - HTTP router
- `openviking/service/resource_service.py:ResourceService.add_skill` - Core service implementation
-- `crates/ov_cli/src/handlers.rs:handle_add_skill` - CLI handler
+- `openviking/server/routers/skills.py` - List, find, read, validate, update, and delete endpoints
+- `crates/ov_cli/src/commands/skills.rs` - CLI Skill command handlers
#### 2. Interface and Parameters
-**Parameters**
+**HTTP body parameters** (`POST /api/v1/skills`)
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
-| data | Any | No | - | Inline skill content or structured data. Mutually exclusive with `temp_file_id` |
-| temp_file_id | str | No | - | Temporary upload file ID (from `temp_upload`). Mutually exclusive with `data` |
+| data | Any | No | - | Inline SKILL.md, structured/MCP data, or Git URL; choose this or `temp_file_id` |
+| temp_file_id | str | No | - | Temporary upload file ID (from `temp_upload`); choose this or `data` |
| wait | bool | No | False | Wait for skill processing to complete |
| timeout | float | No | None | Timeout in seconds, only effective when `wait=true` |
| telemetry | TelemetryRequest | No | False | Whether to return telemetry data |
+| target_uri | str | No | Target resolution order | Skills root, such as `viking://~/skills` or `viking://agent/skills` |
+| skills | List[str] | No | `[]` | Select directory names from a directory/Git collection; empty or `["*"]` selects all |
+| list_only | bool | No | False | Inspect source Skills without installing; requires a resolvable file, directory, or Git source, not an inline dictionary |
+| source_metadata | object | No | Generated automatically | Source tracking saved in `.source.json`; distinct from frontmatter `metadata` |
+
+Supply at least one of `data` or `temp_file_id`. The current server gives uploads precedence if both are present; clients should send only one to avoid ambiguity. Unknown body fields are rejected.
**Additional Notes**:
- **Local file handling**:
@@ -183,12 +196,13 @@ Skills are a special type of resource that define actions or tools agents can pe
- Raw HTTP callers should either:
- Send structured skill data directly in `data`
- Send raw `SKILL.md` content in `data`
- - First call `POST /api/v1/resources/temp_upload` to upload a local `SKILL.md` file/zip directory, then call `POST /api/v1/skills` with `temp_file_id`
- - `temp_upload` defaults to local temporary storage; pass `upload_mode=shared` only when you explicitly need distributed shared temporary uploads. Python HTTP clients can set `upload.mode = "shared"` in `ovcli.conf`; the Rust `ov` CLI instead uses `OPENVIKING_UPLOAD_MODE=shared`
+ - Send a Git repository or GitHub tree URL for server-side source resolution
+ - First call `POST /api/v1/resources/temp_upload` to upload a local `SKILL.md` or directory ZIP, then call `POST /api/v1/skills` with `temp_file_id`
+ - `temp_upload` defaults to local temporary storage; pass `upload_mode=shared` only when you explicitly need distributed shared temporary uploads. Python HTTP clients can set `upload.mode = "shared"` in `ovcli.conf`; the Rust `ov` CLI instead uses `OPENVIKING_UPLOAD_MODE=shared`.
- `POST /api/v1/skills` does not accept direct host filesystem paths in `data`.
- **Targeting**:
- - Skills are always user-scoped. `add_skill` does not accept `to`, `parent`, or `root_uri`.
+ - Add requests use `target_uri` for the skills root; `to`, `parent`, and `root_uri` are not HTTP request fields. CLI `-p/--parent-auto-create` maps to `target_uri`.
- Peer-scoped skill roots are not supported; actor peer filtering only applies to peer memories/resources, not peer skills.
- Use the home alias `viking://~/skills/...` to address your own skills when listing, reading, deleting, or searching. The uid-less `viking://user/skills/...` spelling returns an error with a corrective hint.
@@ -196,11 +210,35 @@ Skills are a special type of resource that define actions or tools agents can pe
1. **Dict (Skill format)**: Includes `name`, `description`, `content`, etc.
2. **Dict (MCP Tool format)**: Includes `name`, `description`, `inputSchema`, auto-detected and converted
3. **String (SKILL.md content)**: Complete SKILL.md content
- 4. **Path (file or directory)**: Path to `SKILL.md` file, or directory containing `SKILL.md` (auxiliary files included)
+ 4. **Path (automatically uploaded by SDK/CLI)**: SKILL.md file, Skill directory/collection, or ZIP; a single Markdown file does not include sibling resources
+ 5. **Git URL**: Repository or Skill subdirectory. Collection `skills` selectors use directory names, not frontmatter names. A discovered `SKILL.md` owns its subtree; nested `SKILL.md` files remain attachments rather than separate discovered Skills
+
+Local `.json` files are not automatically decoded into structured Skills. Parse JSON and send the object in `data`, or use a frontmatter-based `SKILL.md` instead.
#### 3. Usage Examples
-Imports return a `task_id` by default. Query the [Task API](17-tasks.md) and search the skill after the task reaches `completed`.
+Single-Skill imports return a `task_id` by default. Query the [Task API](17-tasks.md) and search after the task reaches `completed`. With `wait=true`, the call waits for queue processing and returns `queue_status`. Multiple imports return an `installed` array with independent task information per result; the batch is not atomic. `list_only=true` returns source `skills` and `total` without creating import tasks.
+
+HTTP fields and SDK parameters do not have identical names or nesting. Python `add_skill(data, wait=False, timeout=None, options=None)` / `update_skill(skill_name, data, ...)` take `target_uri` and `telemetry` inside `options`. Put fields such as `skills`, `list_only`, `source_metadata` (add), and `from_source` (update) in `options["extra"]`. TypeScript uses `targetUri` and `extra`; Go uses `TargetURI` and `Extra`. TypeScript local path uploads require Node.js.
+
+```python
+# Preview a local collection without writing to OpenViking
+listing = client.add_skill(
+ "./skills",
+ options={"extra": {"list_only": True}},
+)
+print(listing["skills"])
+
+# Select directory names and install in the shared root (requires permission)
+result = client.add_skill(
+ "./skills",
+ wait=True,
+ options={
+ "target_uri": "viking://agent/skills",
+ "extra": {"skills": ["search-web", "calculator"]},
+ },
+)
+```
**HTTP API**
@@ -230,7 +268,7 @@ curl -X POST http://localhost:1933/api/v1/skills \
"data": "---\nname: my-skill\ndescription: My custom skill\n---\n\n# My Skill\n\nSkill content here."
}'
-# Using MCP Tool format (auto-detected and converted
+# Using MCP Tool format (auto-detected and converted)
curl -X POST http://localhost:1933/api/v1/skills \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
@@ -255,7 +293,7 @@ curl -X POST http://localhost:1933/api/v1/skills \
TEMP_FILE_ID=$(
curl -s -X POST http://localhost:1933/api/v1/resources/temp_upload \
-H "X-API-Key: your-key" \
- -F "file=@./skills/my-skill.json" \
+ -F "file=@./skills/my-skill/SKILL.md" \
| jq -r '.result.temp_file_id'
)
@@ -291,7 +329,7 @@ Search the web for current information.
result = client.add_skill(data=skill)
print(f"Added: {result['root_uri']}")
-# Approach 2: Using MCP Tool format (auto-detected and converted
+# Approach 2: Using MCP Tool format (auto-detected and converted)
mcp_tool = {
"name": "calculator",
"description": "Perform mathematical calculations",
@@ -313,7 +351,7 @@ print(f"Added: {result['uri']}")
result = client.add_skill(data="./skills/search-web/SKILL.md")
print(f"Added: {result['uri']}")
-# Approach 4: Add from directory containing SKILL.md (auxiliary files included
+# Approach 4: Add from directory containing SKILL.md (auxiliary files included)
result = client.add_skill(data="./skills/code-runner/")
print(f"Added: {result['uri']}")
print(f"Auxiliary files: {result['auxiliary_files']}")
@@ -354,10 +392,12 @@ ov add-skill ./examples/compile/ov-compile-skills --list
ov add-skill ./examples/compile/ov-compile-skills --skill llm-wiki daily-report --yes
# Add a skill from a local file or directory
-ov add-skill ./skills/my-skill.json
ov add-skill ./skills/search-web/SKILL.md
ov add-skill ./skills/code-runner/
+# Target the shared root and wait for processing
+ov skills add ./skills/code-runner/ -p viking://agent/skills --wait
+
# Check progress using the task_id returned by submission
ov task status TASK_ID
@@ -378,11 +418,7 @@ ov add-skill ./skills/my-skill/ -o json
"name": "my-skill",
"auxiliary_files": 2,
"task_id": "uuid-xxx"
- },
- "telemetry": {
- "operation_id": "550e8400-e29b-41d4-a716-446655440000"
- },
- "time": 0.1
+ }
}
```
@@ -414,13 +450,13 @@ task_id uuid-xxx
| Field | Type | Description |
|-------|------|-------------|
-| `status` | string | Processing status: `success` or `error` |
+| `status` | string | Successful import results use `success`; synchronous failures use HTTP error responses |
| `root_uri` | string | Canonical final URI of the skill in OpenViking (same as `uri`) |
| `uri` | string | Canonical final URI of the skill in OpenViking (same as `root_uri`) |
| `name` | string | Skill name |
| `auxiliary_files` | number | Number of auxiliary files included with the skill |
| `task_id` | string | Returned in the default asynchronous mode; query the Task API for the background processing task's final status |
-| `queue_status` | object | (Optional, only when `wait=true`) Queue processing status with `pending`, `processing`, `completed` counts |
+| `queue_status` | object | With `wait=true`, queue names such as `Semantic` / `Embedding` map to `processed`, `requeue_count`, `error_count`, and `errors` |
#### 4. Error Handling
@@ -440,6 +476,8 @@ If skill parsing or processing fails synchronously, raw HTTP returns the standar
The Python HTTP SDK raises the corresponding mapped exception for this response.
+Error codes depend on the failure stage: invalid names/targets use `INVALID_ARGUMENT` / `INVALID_URI`, missing Skills use `NOT_FOUND`, oversized integrity manifests use `RESOURCE_EXHAUSTED`, and wait timeouts use `DEADLINE_EXCEEDED`. Success with `wait=false` only confirms the synchronous import stage; inspect task status for background failures. Standard responses may include optional `telemetry` / `profile`, but have no generic `time` field. SDKs normally return the `result` object directly.
+
## Skill Management Operations
The Python HTTP SDK and Go SDK expose dedicated skill management methods:
@@ -450,6 +488,8 @@ filesystem/content/retrieval methods still work for URI-level access.
### List Skills
+`GET /api/v1/skills` accepts query parameters `node_limit=1000` and optional `target_uri`. Without a target it merges private and shared roots, retaining same-name Skills distinguished by `root_uri`. The current server fixes directory scanning at `node_limit=1000` per root and does not forward the requested `node_limit` to that scan; do not rely on it as a global result limit or pagination parameter.
+
**Python SDK**
```python
@@ -480,6 +520,19 @@ curl -X GET "http://localhost:1933/api/v1/skills?node_limit=1000" \
### Read Skill
+`GET /api/v1/skills/{skill_name}`:
+
+| Query parameter | Default | Meaning |
+|-----------------|---------|---------|
+| `target_uri` | Unspecified | Skills root to try first |
+| `level` | Unspecified | `0` returns abstract, `1` overview, `2` SKILL.md; omitted returns all three levels |
+| `include_content` | Unspecified | `true` adds content; `false` disables content when level is omitted; `level=2` always returns content |
+| `include_files` | `true` | File and directory manifest, without hashes by default |
+| `include_integrity` | `false` | Read a snapshot under a tree lock; requires `include_files=true` to produce file hashes and revision |
+| `include_source` | `false` | Include `.source.json` tracking; absent tracking returns `source.tracked=false` |
+
+Read, update, and delete share name resolution: by default, try the private user Skill, then the shared Skill. An explicit `target_uri` is tried first, but a miss still falls back to private/shared roots. For these operations, `target_uri` currently does not guarantee exclusive resolution within that root. Read and inspect the returned `root_uri` when managing same-name Skills.
+
**Python SDK**
```python
@@ -515,8 +568,53 @@ curl -X GET "http://localhost:1933/api/v1/skills/search-web?include_content=true
-H "X-API-Key: your-key"
```
+### Integrity Manifests and Remote Use
+
+A remote Harness can request an integrity manifest before downloading scripts or binary resources:
+
+```python
+skill = client.get_skill(
+ "search-web",
+ target_uri="viking://~/skills",
+ include_content=True,
+ include_files=True,
+ include_integrity=True,
+)
+print(skill["root_uri"], skill["revision"], skill["content_sha256"])
+for entry in skill["files"]:
+ if not entry["is_dir"]:
+ print(entry["path"], entry["uri"], entry["size"], entry["sha256"])
+```
+
+The HTTP equivalent is `GET /api/v1/skills/search-web?include_content=true&include_files=true&include_integrity=true`. The current Python SDK exposes `include_integrity`. TypeScript/Go `getSkill` / `GetSkill` options and `ov skills show` do not yet expose it; use HTTP or the Python SDK when needed.
+
+| Response field | Meaning |
+|----------------|---------|
+| `content_sha256` | SHA-256 of the returned SKILL.md text; present whenever `content` is returned, even without integrity mode |
+| `revision` | Version derived from the sorted package manifest: paths, directory flags, sizes, and hashes; not a Git commit or metadata.version |
+| `files[].name/path/uri` | Entry name, package-relative path, and canonical URI |
+| `files[].is_dir/kind` | Directory flag; kind is `definition`, `summary`, `auxiliary`, or `directory` |
+| `files[].size/sha256` | Byte size and SHA-256 for non-directory entries in integrity mode; absent from ordinary manifests |
+
+The manifest includes `SKILL.md`, summaries, and auxiliary files/directories, but excludes `.source.json`. Integrity limits are **512 entries (including directories), 16 MiB per file, and 64 MiB total file bytes**, with read concurrency 8. Exceeding a limit returns `RESOURCE_EXHAUSTED`. Content, manifest, and revision are obtained under one tree lock, but later downloads can encounter updates; consumers should verify file hashes and recheck revision.
+
+Search and `get_skill` return content and manifests without executing scripts or installing files in an Agent sandbox. A Harness can read text remotely and download resources when a tool requires local paths. See [VikingBot Skills](../../../bot/docs/en/concepts/06-skills.md) for the complete consumer workflow.
+
### Search Skills
+`POST /api/v1/skills/find` body:
+
+| Parameter | Default | Meaning |
+|-----------|---------|---------|
+| `query` | Required | Search text |
+| `limit` | `10` | Requested candidate limit per search root |
+| `score_threshold` | `null` | Minimum score; omission uses underlying retrieval defaults |
+| `level` | `null` | Level filter list such as `[0]`; unlike the single integer on get |
+| `target_uri` | `null` | Search scope; omitted searches private and shared roots separately |
+| `telemetry` | `false` | Telemetry configuration |
+
+Merged results are sorted by score, without name deduplication or a final `limit` truncation, so the total can exceed `limit`. `total` is the returned array length, not a count of all possible matches. Results are summaries, not complete packages.
+
**Python SDK**
```python
@@ -555,10 +653,28 @@ curl -X POST http://localhost:1933/api/v1/skills/find \
### Validate and Update Skills
+`POST /api/v1/skills/validate` accepts required `data` (structured data or complete SKILL.md text), `strict=false`, `source_path=null`, `skill_dir_name=null`, and `target_uri=null`. `source_path` is report information, not an instruction to read a server-local file. The current endpoint accepts but does not use `target_uri` for validation. SDK `validate_skill` does not upload paths automatically; read the file text first.
+
+Missing names/descriptions and invalid YAML produce errors. Directory/name mismatch, invalid name length/characters, and descriptions over 1024 characters produce warnings normally and errors with `strict=true`. A body exceeding 500 lines remains only a warning in strict mode. Validation does not install Skills or check registered tools and executable dependencies; it does not replace import or Harness checks.
+
+`PUT /api/v1/skills/{skill_name}` replaces the entire package and accepts:
+
+| Parameter | Default | Meaning |
+|-----------|---------|---------|
+| `data` / `temp_file_id` | Unspecified | New content or uploaded package, as for add |
+| `from_source` | `false` | Refresh from recorded Git source; cannot be combined with data/temp_file_id |
+| `target_uri` | Unspecified | Skills root to try first; see read resolution fallback |
+| `source_metadata` | Generated automatically | Updated source tracking |
+| `wait` / `timeout` | `false` / `null` | Wait for background processing and timeout in seconds |
+| `telemetry` | `false` | Telemetry configuration |
+
+Supply new content/an upload, or set `from_source=true`. The new name must match `skill_name` in the URL; update is neither rename nor a partial patch. The server parses and checks the new package before backing up and replacing the old one, and attempts restoration on synchronous failure. Include all auxiliary files that should remain in the replacement package.
+
**Python SDK**
```python
validated = client.validate_skill(data={"name": "search-web", "description": "..."})
+print(validated["valid"], validated["errors"], validated["warnings"])
updated = client.update_skill(
skill_name="search-web",
data="./skills/search-web",
@@ -608,8 +724,28 @@ curl -X PUT http://localhost:1933/api/v1/skills/search-web \
}'
```
+Source refresh requires a recorded Git source and fetches the recorded repository, ref, and subdirectory again. A local upload has no Git source to pull automatically:
+
+```python
+updated = client.update_skill(
+ "search-web",
+ data=None,
+ wait=True,
+ options={"extra": {"from_source": True}},
+)
+```
+
+```bash
+curl -X PUT http://localhost:1933/api/v1/skills/search-web \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{"from_source": true, "wait": true}'
+```
+
### Delete Skills
+`DELETE /api/v1/skills/{skill_name}` accepts optional query parameter `target_uri`. It recursively removes the resolved package and handles its associated Skill privacy configuration. Target fallback is the same as for read.
+
**Python SDK**
```python
@@ -636,6 +772,21 @@ curl -X DELETE "http://localhost:1933/api/v1/skills/old-skill" \
-H "X-API-Key: your-key"
```
+### CLI Management Commands
+
+```bash
+ov skills list -p viking://~/skills
+ov skills find "search the internet" --level 0 --limit 5 -p viking://~/skills
+ov skills show search-web --level 2 --files --source -p viking://~/skills
+ov skills validate ./skills/search-web --strict
+ov skills update search-web -p viking://~/skills --wait --yes
+ov skills remove old-skill -p viking://~/skills --yes
+```
+
+The long form of `-p` is `--uri` for `list/find/show` and `--parent-auto-create` for `add/update/remove`. `show` returns all text levels by default; request files with `--files` and tracking with `--source`. `validate` runs locally without installation. `update` refreshes recorded Git sources; for non-Git sources, interactive use can prompt for a path/URL.
+
+Without names, `ov skills update` attempts all installed Skills and reports unsuccessful entries in `skipped`. `remove` without names opens interactive selection; only `--all` selects everything. Update and remove require confirmation; use `--yes` explicitly in scripts.
+
### Skill Management Responses
List and search return a `skills` array and `total`. Without `target_uri`, `root_uris` identifies the private user and shared Agent roots; with a target, the response contains a single `root_uri`.
@@ -735,6 +886,7 @@ skill = {
### Comprehensive Content
Include in your skill content:
+
- Clear parameter descriptions with types
- When to use the skill
- Concrete examples
@@ -743,6 +895,7 @@ Include in your skill content:
### Consistent Naming
Use kebab-case for skill names:
+
- `search-web` (recommended)
- `searchWeb` (avoid)
- `search_web` (avoid)
@@ -754,3 +907,4 @@ Use kebab-case for skill names:
- [Context Types](../concepts/02-context-types.md) - Skill concept
- [Retrieval](06-retrieval.md) - Finding skills
- [Sessions](05-sessions.md) - Tracking skill usage
+- [VikingBot Skills](../../../bot/docs/en/concepts/06-skills.md) - Local/remote activation, metadata, and execution
diff --git a/docs/zh/api/04-skills.md b/docs/zh/api/04-skills.md
index 6e296ae41..46f85a232 100644
--- a/docs/zh/api/04-skills.md
+++ b/docs/zh/api/04-skills.md
@@ -1,6 +1,6 @@
# 技能
-技能是智能体可以调用的能力定义。本模块提供技能的添加和管理功能。
+技能是供智能体读取的任务指令与配套资源。OpenViking 负责存储、检索和管理技能;读取后的激活、工具权限与执行由使用它的 Agent/Harness 负责。本文以当前仓库的 HTTP API、SDK 和 `ov` CLI 实现为准。
## 核心概念
@@ -10,12 +10,14 @@ OpenViking 支持多种技能定义格式:
1. **结构化技能数据**:包含 name、description、content 等字段的字典
2. **SKILL.md 文件**:带有 YAML frontmatter 的 Markdown 文件
-3. **MCP Tool 格式**:自动检测并转换为 OpenViking 技能格式
+3. **MCP Tool 格式**:自动检测并转换为技能文档,不会连接 MCP Server 或注册可执行工具
+4. **Skill 包与集合**:包含 `SKILL.md` 和辅助文件的目录、ZIP,或 Git 仓库 / GitHub tree URL
### 技能存储结构
-技能存储在当前用户的 skills 根。家目录别名 `viking://~/skills/` 会按认证请求身份展开为
-`viking://user/{user_id}/skills/`(无 uid 的写法 `viking://user/skills/` 不再被接受):
+技能支持当前用户私有根 `viking://user/{user_id}/skills/` 和账户内共享根 `viking://agent/skills/`。新增时的目标优先级为:请求 `target_uri` → 用户 `add_targets.skill_uri` → 服务端 `user_config_defaults.add_targets.skill_uri` → 当前用户私有根。所有访问仍受当前身份和权限约束。
+
+家目录别名 `viking://~/skills/` 始终按认证身份展开为当前用户的私有根,不随默认新增目标改变。无 uid 的 `viking://user/skills/` 和 peer-scoped skills 均不支持。私有根的包结构如下;共享根使用相同结构:
```
viking://user/{user_id}/skills/
@@ -39,12 +41,15 @@ viking://user/{user_id}/skills/
---
name: skill-name
description: Brief description of the skill
-allowed_tools:
- - Tool1
- - Tool2
+allowed-tools: Read Bash(python3 *)
tags:
- tag1
- tag2
+metadata:
+ author: example-team
+ vikingbot:
+ requires:
+ bins: [python3]
---
# Skill Name
@@ -66,15 +71,18 @@ Concrete examples of skill invocation.
| 字段 | 类型 | 说明 |
|------|------|------|
-| name | str | 技能名称(建议使用 kebab-case)|
+| name | str | 非空,最多 64 个 ASCII 字母、数字、下划线或连字符;建议 kebab-case |
| description | str | 简要描述 |
**可选字段**:
| 字段 | 类型 | 说明 |
|------|------|------|
-| allowed_tools | List[str] | 该技能可使用的工具 |
+| allowed-tools | str / List[str] | 空格分隔的工具声明,也兼容字符串列表;括号内可含空格,由消费方解释和执行策略 |
| tags | List[str] | 用于分类的标签 |
+| metadata | object | 原样保留的扩展字段,如 `metadata.vikingbot.requires`;OpenViking 不自动安装这些依赖 |
+
+`SKILL.md` 使用带连字符的 **`allowed-tools`**,解析后的结构化数据和 API 摘要使用 **`allowed_tools`**。不要在 frontmatter 中用下划线拼写替代它。未声明和显式空声明可能在 Harness 中有不同权限含义,摘要里的 `allowed_tools: []` 不能区分二者;执行前应读取完整 `SKILL.md`。正文与扩展字段的消费方式见 [VikingBot Skills](../../../bot/docs/zh/concepts/06-skills.md)。
### MCP 格式自动转换
@@ -83,7 +91,7 @@ OpenViking 会自动检测并将 MCP Tool 定义转换为技能格式。
**检测规则**:如果字典包含 `inputSchema` 字段,则被视为 MCP 格式。
**转换过程**:
-1. 名称转换为 kebab-case
+1. 将名称中的下划线替换为连字符(不会自动转换 camelCase)
2. 描述保持不变
3. 从 `inputSchema.properties` 中提取参数
4. 从 `inputSchema.required` 中标记必填字段
@@ -113,8 +121,8 @@ OpenViking 会自动检测并将 MCP Tool 定义转换为技能格式。
}
```
-输出(技能格式):
-```json
+输出(Python 字典形式):
+```python
{
"name": "search-web",
"description": "Search the web",
@@ -153,41 +161,49 @@ This tool wraps the MCP tool `search-web`. Call this when the user needs functio
1. 接收技能数据或上传的临时文件
2. 检测数据格式(结构化数据、SKILL.md 内容、MCP 格式)
3. 解析技能定义
-4. 存储到当前用户的 `viking://user/{user_id}/skills/` 路径下
+4. 将包存储到选定的用户私有或账户共享 skills 根
5. 默认返回 `task_id`,用于查询后台向量化任务
**代码入口**:
- `sdk/python/openviking_sdk/client.py:AsyncHTTPClient.add_skill` - Python SDK 入口
-- `openviking_cli/client/http.py:AsyncHTTPClient.add_skill` - SDK 入口(HTTP)
+- `openviking_cli/client/http.py` - 兼容导入入口,转发到 Python SDK
- `openviking/server/routers/resources.py:add_skill` - HTTP 路由
- `openviking/service/resource_service.py:ResourceService.add_skill` - 核心服务实现
-- `crates/ov_cli/src/handlers.rs:handle_add_skill` - CLI 处理
+- `openviking/server/routers/skills.py` - 列表、检索、读取、校验、更新和删除
+- `crates/ov_cli/src/commands/skills.rs` - CLI Skill 命令处理
#### 2. 接口和参数说明
-**参数**:
+**HTTP 请求体参数**(`POST /api/v1/skills`):
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
-| data | Any | 否 | - | 内联技能内容或结构化数据。与 `temp_file_id` 二选一 |
-| temp_file_id | string | 否 | - | 临时上传文件 ID(通过 `temp_upload` 获取)。与 `data` 二选一 |
+| data | Any | 否 | - | 内联 SKILL.md、结构化/MCP 数据或 Git URL;与 `temp_file_id` 选择一个 |
+| temp_file_id | string | 否 | - | 临时上传文件 ID(通过 `temp_upload` 获取);与 `data` 选择一个 |
| wait | bool | 否 | False | 是否等待技能处理完成 |
| timeout | float | 否 | None | 超时时间(秒),仅 `wait=True` 时生效 |
| telemetry | TelemetryRequest | 否 | False | 是否返回遥测数据 |
+| target_uri | string | 否 | 按目标优先级解析 | 目标 skills 根,例如 `viking://~/skills` 或 `viking://agent/skills` |
+| skills | List[str] | 否 | `[]` | 从目录/Git 集合按目录名选择 Skill;空列表或 `["*"]` 选择全部 |
+| list_only | bool | 否 | False | 只列出来源中的 Skill,不安装;需可解析的文件、目录或 Git 来源,不能使用内联字典 |
+| source_metadata | object | 否 | 自动生成 | 来源跟踪信息,保存在 `.source.json`;不是 frontmatter 的 `metadata` |
+
+至少提供 `data` 或 `temp_file_id`。当前服务端两者同时存在时优先消费临时上传;客户端应只传一种,避免来源混淆。请求体不接受未知字段。
**补充说明**:
- **本地文件处理**:
- Python SDK 和 CLI 可以直接接收本地 `SKILL.md` 文件或目录。处于 HTTP 模式时,它们会先自动上传,再调用服务端 API。
- - 裸 HTTP 调用有三种推荐方式:
+ - 裸 HTTP 调用可以:
1. 在 `data` 中直接传结构化 skill 数据
2. 在 `data` 中直接传原始 `SKILL.md` 内容
- 3. 先调用 `POST /api/v1/resources/temp_upload` 上传本地 `SKILL.md` 文件/zip 目录,再调用 `POST /api/v1/skills` 并传入 `temp_file_id`
- 4. `temp_upload` 默认使用本地临时存储;只有在明确需要分布式共享临时上传时,才传 `upload_mode=shared`。Python HTTP client 可以在 `ovcli.conf` 中设置 `upload.mode = "shared"`;Rust `ov` CLI 则使用 `OPENVIKING_UPLOAD_MODE=shared`
+ 3. 直接传 Git 仓库或 GitHub tree URL,让服务端解析来源
+ 4. 先调用 `POST /api/v1/resources/temp_upload` 上传本地 `SKILL.md` 或目录 ZIP,再调用 `POST /api/v1/skills` 并传入 `temp_file_id`
+ - `temp_upload` 默认使用本地临时存储;只有在明确需要分布式共享临时上传时,才传 `upload_mode=shared`。Python HTTP client 可以在 `ovcli.conf` 中设置 `upload.mode = "shared"`;Rust `ov` CLI 则使用 `OPENVIKING_UPLOAD_MODE=shared`。
- `POST /api/v1/skills` 不接受在 `data` 中直接传宿主机本地路径。
- **目标规则**:
- - Skills 始终是 user-scoped;`add_skill` 不接受 `to`、`parent` 或 `root_uri`。
+ - 新增使用 `target_uri` 指定 skills 根,不接受 `to`、`parent` 或 `root_uri` 作为 HTTP 请求字段。CLI 的 `-p/--parent-auto-create` 映射到 `target_uri`。
- 不支持 peer-scoped skill 根;actor peer 过滤只作用于 peer memories/resources,不作用于 peer skills。
- 列出、读取、删除或搜索技能时,使用家目录别名 `viking://~/skills/...` 访问自己的技能;无 uid 的 `viking://user/skills/...` 写法会报错并提示正确写法。
@@ -195,11 +211,35 @@ This tool wraps the MCP tool `search-web`. Call this when the user needs functio
1. **字典(技能格式)**:包含 `name`、`description`、`content` 等字段
2. **字典(MCP Tool 格式)**:包含 `name`、`description`、`inputSchema` 字段,会自动检测并转换
3. **字符串(SKILL.md 内容)**:完整的 SKILL.md 内容
- 4. **路径(文件或目录)**:指向 `SKILL.md` 文件的路径,或包含 `SKILL.md` 的目录路径(辅助文件会一并包含)
+ 4. **路径(SDK/CLI 自动上传)**:SKILL.md 文件、Skill 目录/集合或 ZIP;单个 Markdown 文件不包含同目录辅助文件
+ 5. **Git URL**:仓库或 Skill 子目录;集合中的 `skills` 选择器使用目录名,非 frontmatter 名称。已发现 `SKILL.md` 的目录拥有整个子树,内部嵌套 `SKILL.md` 作为附件保留,不再单独发现
+
+本地 `.json` 文件不会自动解码成结构化 Skill。应先解析 JSON 并把对象传入 `data`,或改用带 frontmatter 的 `SKILL.md`。
#### 3. 使用示例
-导入默认返回 `task_id`。通过 [任务 API](17-tasks.md) 查询状态,任务为 `completed` 后再检索该技能。
+单个 Skill 导入默认返回 `task_id`。通过 [任务 API](17-tasks.md) 查询状态,任务为 `completed` 后再检索;`wait=true` 则等待队列处理并返回 `queue_status`。多 Skill 导入返回 `installed` 数组,每个结果独立携带任务信息,不保证批次原子性。`list_only=true` 只返回来源中的 `skills` 与 `total`,不创建导入任务。
+
+HTTP 字段和 SDK 参数并非同名同层级:Python `add_skill(data, wait=False, timeout=None, options=None)` / `update_skill(skill_name, data, ...)` 将 `target_uri`、`telemetry` 放在 `options` 中;`skills`、`list_only`、`source_metadata`(新增)及 `from_source`(更新)等字段放在 `options["extra"]` 中。TypeScript 使用 `targetUri` 和 `extra`,Go 使用 `TargetURI` 和 `Extra`。TypeScript 的本地路径自动上传仅适用于 Node.js。
+
+```python
+# 预览本地集合;不写入 OpenViking
+listing = client.add_skill(
+ "./skills",
+ options={"extra": {"list_only": True}},
+)
+print(listing["skills"])
+
+# 选择目录名,并安装到共享根(需相应权限)
+result = client.add_skill(
+ "./skills",
+ wait=True,
+ options={
+ "target_uri": "viking://agent/skills",
+ "extra": {"skills": ["search-web", "calculator"]},
+ },
+)
+```
**TypeScript SDK**
@@ -261,7 +301,7 @@ curl -X POST http://localhost:1933/api/v1/skills \
TEMP_FILE_ID=$(
curl -s -X POST http://localhost:1933/api/v1/resources/temp_upload \
-H "X-API-Key: your-key" \
- -F "file=@./skills/my-skill.json" \
+ -F "file=@./skills/my-skill/SKILL.md" \
| jq -r '.result.temp_file_id'
)
@@ -352,10 +392,12 @@ ov add-skill ./examples/compile/ov-compile-skills --list
ov add-skill ./examples/compile/ov-compile-skills --skill llm-wiki daily-report --yes
# 添加技能(从文件或目录)
-ov add-skill ./skills/my-skill.json
ov add-skill ./skills/search-web/SKILL.md
ov add-skill ./skills/code-runner/
+# 指定共享目标,并等待处理完成
+ov skills add ./skills/code-runner/ -p viking://agent/skills --wait
+
# 使用提交时返回的 task_id 查询进度
ov task status TASK_ID
@@ -376,11 +418,7 @@ ov add-skill ./skills/my-skill/ -o json
"name": "my-skill",
"auxiliary_files": 2,
"task_id": "uuid-xxx"
- },
- "telemetry": {
- "operation_id": "550e8400-e29b-41d4-a716-446655440000"
- },
- "time": 0.1
+ }
}
```
@@ -412,13 +450,13 @@ task_id uuid-xxx
| 字段 | 类型 | 说明 |
|------|------|------|
-| `status` | string | 处理状态:`success` 成功,`error` 失败 |
+| `status` | string | 成功导入结果为 `success`;同步失败使用 HTTP 错误响应 |
| `root_uri` | string | 技能在 OpenViking 中的 canonical 最终 URI(同 `uri`)|
| `uri` | string | 技能在 OpenViking 中的 canonical 最终 URI(同 `root_uri`)|
| `name` | string | 技能名称 |
| `auxiliary_files` | number | 技能附带的辅助文件数量 |
| `task_id` | string | 默认异步模式下返回的后台处理任务 ID;通过任务 API 查询最终状态 |
-| `queue_status` | object | (可选,仅当 `wait=True` 时)队列处理状态,包含 `pending`、`processing`、`completed` 计数 |
+| `queue_status` | object | `wait=True` 时按队列名(如 `Semantic`、`Embedding`)返回 `processed`、`requeue_count`、`error_count` 和 `errors` |
#### 4. 错误处理
@@ -438,6 +476,8 @@ task_id uuid-xxx
Python HTTP SDK 会把该响应映射为对应异常(`ProcessingError`)。
+具体错误码取决于失败阶段,例如名称或目标参数无效为 `INVALID_ARGUMENT` / `INVALID_URI`,找不到 Skill 为 `NOT_FOUND`,完整性清单超限为 `RESOURCE_EXHAUSTED`,等待超时为 `DEADLINE_EXCEEDED`。`wait=false` 返回成功只表示同步导入阶段完成,后台失败需通过任务状态确认。标准响应可能带可选 `telemetry` / `profile`,没有通用 `time` 字段;SDK 通常直接返回 `result` 对象。
+
## 技能管理操作
Python HTTP SDK 和 Go SDK 都暴露专用技能管理方法。Python 方法包括
@@ -447,6 +487,8 @@ Python HTTP SDK 和 Go SDK 都暴露专用技能管理方法。Python 方法包
### 列出技能
+`GET /api/v1/skills` 的查询参数为 `node_limit=1000` 和可选 `target_uri`。省略目标时合并私有与共享根,同名 Skill 都保留,以 `root_uri` 区分。当前服务端实际固定每个根的目录扫描 `node_limit=1000`,尚未把请求的 `node_limit` 传到扫描层,不应依赖它作为全局条数限制或分页参数。
+
**Python SDK**:
```python
@@ -478,6 +520,19 @@ curl -X GET "http://localhost:1933/api/v1/skills?node_limit=1000" \
### 读取技能
+`GET /api/v1/skills/{skill_name}`:
+
+| 查询参数 | 默认值 | 含义 |
+|----------|--------|------|
+| `target_uri` | 未指定 | 优先查找的 skills 根 |
+| `level` | 未指定 | `0` 返回 abstract,`1` 返回 overview,`2` 返回 SKILL.md;未指定时返回三个层级 |
+| `include_content` | 未指定 | `true` 额外返回正文;`false` 在未指定 level 时关闭正文;`level=2` 始终返回正文 |
+| `include_files` | `true` | 返回文件和目录清单,默认不计算哈希 |
+| `include_integrity` | `false` | 在树锁内读取快照;与 `include_files=true` 一起使用才生成文件哈希与 revision |
+| `include_source` | `false` | 返回 `.source.json` 来源信息;没有记录时 `source.tracked=false` |
+
+按名称读取、更新、删除共用查找逻辑:默认先找用户私有 Skill,再找共享 Skill;显式指定 `target_uri` 时先找目标根,未找到时仍会回退到私有/共享根。当前 `target_uri` 对这三个操作不是严格的“仅限该根”保证。处理同名 Skill 时,应先读取并检查返回的 `root_uri`。
+
**Python SDK**:
```python
@@ -514,8 +569,53 @@ curl -X GET "http://localhost:1933/api/v1/skills/search-web?include_content=true
-H "X-API-Key: your-key"
```
+### 完整性清单与远程使用
+
+远程 Harness 需要下载脚本或二进制文件时,可先请求完整性清单:
+
+```python
+skill = client.get_skill(
+ "search-web",
+ target_uri="viking://~/skills",
+ include_content=True,
+ include_files=True,
+ include_integrity=True,
+)
+print(skill["root_uri"], skill["revision"], skill["content_sha256"])
+for entry in skill["files"]:
+ if not entry["is_dir"]:
+ print(entry["path"], entry["uri"], entry["size"], entry["sha256"])
+```
+
+HTTP 对应查询为 `GET /api/v1/skills/search-web?include_content=true&include_files=true&include_integrity=true`。当前 Python SDK 暴露 `include_integrity`;TypeScript、Go 的 `getSkill` / `GetSkill` options 及 `ov skills show` 暂无此选项,需要此能力时使用 HTTP 或 Python SDK。
+
+| 返回字段 | 含义 |
+|----------|------|
+| `content_sha256` | 返回的 SKILL.md 正文的 SHA-256;只要返回 `content` 就有该字段,不要求开启完整性模式 |
+| `revision` | 根据排序后的包清单(路径、目录标记、文件大小与哈希)计算的版本标识,不是 Git commit 或 metadata.version |
+| `files[].name/path/uri` | 条目名称、包内相对路径、canonical URI |
+| `files[].is_dir/kind` | 目录标记;kind 为 `definition`、`summary`、`auxiliary` 或 `directory` |
+| `files[].size/sha256` | 完整性模式下非目录文件的字节数与 SHA-256;普通清单不包含这些字段 |
+
+清单包含 `SKILL.md`、摘要和辅助文件/目录,不包含 `.source.json`。完整性 API 上限为 **512 个条目(包含目录)、单文件 16 MiB、总文件字节数 64 MiB**,读取并发为 8;超限返回 `RESOURCE_EXHAUSTED`。正文、清单和 revision 在同一次树锁保护的读取中取得,但后续下载仍可能遇到更新,消费方应校验文件哈希并复查 revision。
+
+检索与 `get_skill` 只返回内容和清单,不会执行脚本或把文件安装到 Agent 沙箱。Harness 可按需远程读文本,在工具需要本地路径时下载资源。VikingBot 的完整流程见 [Skills](../../../bot/docs/zh/concepts/06-skills.md)。
+
### 搜索技能
+`POST /api/v1/skills/find` 请求体:
+
+| 参数 | 默认值 | 含义 |
+|------|--------|------|
+| `query` | 必填 | 检索文本 |
+| `limit` | `10` | 每个检索根请求的候选上限 |
+| `score_threshold` | `null` | 最低分数,未指定时使用底层检索默认行为 |
+| `level` | `null` | 层级过滤列表,例如 `[0]`;与读取接口的单个整数不同 |
+| `target_uri` | `null` | 限定检索范围;省略时分别检索私有与共享根 |
+| `telemetry` | `false` | 遥测配置 |
+
+双根检索合并后按分数排序,不按名称去重,也不再按 `limit` 截断,因此总结果可能超过 `limit`。`total` 是本次返回数组长度,不是所有匹配项的总数。结果是摘要,不是完整 Skill 包。
+
**Python SDK**:
```python
@@ -555,10 +655,28 @@ curl -X POST http://localhost:1933/api/v1/skills/find \
### 校验和更新技能
+`POST /api/v1/skills/validate` 接收 `data`(必填的结构化数据或完整 SKILL.md 文本)、`strict=false`、`source_path=null`、`skill_dir_name=null` 和 `target_uri=null`。`source_path` 仅作为报告信息,不会让服务端读取本地文件;当前 `target_uri` 被接受但不参与格式校验。SDK 的 `validate_skill` 也不自动上传路径,应先读取文件内容。
+
+缺少名称/描述和无效 YAML 会产生 errors。名称/目录不一致、名称长度或字符不合规、描述超过 1024 字符在普通模式为 warnings,`strict=true` 时升级为 errors;正文超过 500 行在严格模式仍只是 warning。该接口不安装 Skill、不验证工具是否已注册或依赖是否可执行,不能替代实际导入与 Harness 检查。
+
+`PUT /api/v1/skills/{skill_name}` 替换整个包,接收以下请求体:
+
+| 参数 | 默认值 | 含义 |
+|------|--------|------|
+| `data` / `temp_file_id` | 未指定 | 新内容或上传包,使用方式与新增相同 |
+| `from_source` | `false` | 根据已记录的 Git 来源更新;不能与 data/temp_file_id 同用 |
+| `target_uri` | 未指定 | 优先查找的 skills 根,参见读取接口的回退规则 |
+| `source_metadata` | 自动生成 | 更新来源信息 |
+| `wait` / `timeout` | `false` / `null` | 是否等待后台处理及超时秒数 |
+| `telemetry` | `false` | 遥测配置 |
+
+必须提供新内容/上传包,或设 `from_source=true`。新内容的名称必须与 URL 中的 `skill_name` 一致;更新不是重命名或局部 patch。先解析并检查新包,再备份替换;同步失败会尝试恢复旧包。需保留的辅助文件应随新包一起提交。
+
**Python SDK**:
```python
validated = client.validate_skill(data={"name": "search-web", "description": "..."})
+print(validated["valid"], validated["errors"], validated["warnings"])
updated = client.update_skill(
skill_name="search-web",
data="./skills/search-web",
@@ -609,8 +727,28 @@ curl -X PUT http://localhost:1933/api/v1/skills/search-web \
}'
```
+从来源更新仅适用于已记录 Git 来源的 Skill,使用记录的仓库、ref 与子目录重新获取内容;本地上传没有可自动拉取的 Git 来源:
+
+```python
+updated = client.update_skill(
+ "search-web",
+ data=None,
+ wait=True,
+ options={"extra": {"from_source": True}},
+)
+```
+
+```bash
+curl -X PUT http://localhost:1933/api/v1/skills/search-web \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{"from_source": true, "wait": true}'
+```
+
### 删除技能
+`DELETE /api/v1/skills/{skill_name}` 接受可选查询参数 `target_uri`,递归删除解析到的 Skill 包,并处理关联 Skill privacy 配置。目标根回退规则与读取相同。
+
**Python SDK**:
```python
@@ -637,6 +775,21 @@ curl -X DELETE "http://localhost:1933/api/v1/skills/old-skill" \
-H "X-API-Key: your-key"
```
+### CLI 管理命令
+
+```bash
+ov skills list -p viking://~/skills
+ov skills find "search the internet" --level 0 --limit 5 -p viking://~/skills
+ov skills show search-web --level 2 --files --source -p viking://~/skills
+ov skills validate ./skills/search-web --strict
+ov skills update search-web -p viking://~/skills --wait --yes
+ov skills remove old-skill -p viking://~/skills --yes
+```
+
+`list/find/show` 的 `-p` 长选项为 `--uri`;`add/update/remove` 为 `--parent-auto-create`。`show` 默认返回各文本层级,文件清单需 `--files`,来源需 `--source`。`validate` 在本地校验,不安装;`update` 从记录的 Git 来源刷新,非 Git 来源在交互模式可要求补充路径/URL。
+
+`ov skills update` 不带名称时尝试更新全部已安装 Skill,并在 `skipped` 中报告无法更新项。`remove` 不带名称时进入交互选择,`--all` 才表示全部。更新和删除需要确认,脚本中显式使用 `--yes`。
+
### 技能管理响应
列出和搜索都返回 `skills` 数组与 `total`。未指定 `target_uri` 时使用 `root_uris` 表示用户私有与 Agent 共享两个检索根;指定后返回单个 `root_uri`。
@@ -736,6 +889,7 @@ skill = {
### 命名一致性建议
技能名称使用 kebab-case:
+
- `search-web`(推荐)
- `searchWeb`(避免)
- `search_web`(避免)
@@ -747,3 +901,4 @@ skill = {
- [上下文类型](../concepts/02-context-types.md) - 技能概念
- [检索](06-retrieval.md) - 查找技能
- [会话](05-sessions.md) - 跟踪技能使用情况
+- [VikingBot Skills](../../../bot/docs/zh/concepts/06-skills.md) - 本地/远程 Skill 的激活、metadata 与执行