ov-skills

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. ov add-skill is the same command as ov skills add and takes the same flags.

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 (alias ls), find, add, show, update, remove (aliases rm, delete), validate
argument	conditional	Skill name(s) for show/update/remove, query string for find, source path/URL or raw SKILL.md text for add, local path for validate
root	no	Skill root URI passed with -p: viking://~/skills (private) or viking://agent/skills (shared with the account). add defaults to the private root; list/find search both roots; show/update/remove resolve a name to the private copy first, then the shared one
level	no	-L/--level for show/find: 0 (abstract), 1 (overview), 2 (full SKILL.md)

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). When a source may hold several skills, run ov skills add <source> --list first and pick skills with --skill.
3. Construct the command with flags from examples/commands.md only. The long form of -p is --uri for list/find/show and --parent-auto-create for add/update/remove. Add the global -o json for machine-readable output.
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 update and ov skills remove always ask for confirmation, and so does ov skills add when the source resolves to more than one skill. Without a terminal the command fails with requires confirmation. Pass --yes to skip the prompt.; confirm with the user in the conversation, then rerun with --yes.
• 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: tables by default, JSON with -o json (show also accepts --format json).
• Errors surfaced with suggested fixes.

Verification

• After add, list should include the new skill. Processing may continue in the background unless --wait was passed; check it with ov task status <task_id>.
• After remove, list should no longer include the removed skill.
• After update, show <name> --level 2 should show the fresh SKILL.md, and show <name> --source the recorded source.

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 run ov skills remove without skill names from an agent shell: it opens an interactive picker that needs a terminal.
• Remove skills with ov skills remove, not ov rm: only ov skills remove also deletes the skill's privacy configuration.

Runtime Resources

• docs/upgrade-guide.md — moving from generic filesystem commands to ov skills.
• examples/commands.md — common command patterns by scenario.
• docs/source-types.md — deep dive on supported source formats and URL patterns.