Reference

Skill — structured workflows

A Skill is a multi-step workflow the agent works through phase by phase. Run deepvista skill --help or deepvista skill --help for full flag reference.

Commands

list · get · run · phase · complete · status create-from-note · discover · install · sync · load

Agent conventions

> [!CAUTION] run, phase, complete, install are writes. Confirm first.

Read-only: list, get, status, discover, sync --dry-run, load.

Show the app URL after writes: https://app.deepvista.ai/skills/

Executing a workflow skill — required sequence

> [!IMPORTANT] To run a workflow skill you must call deepvista skill run --mode host first. Do NOT call skill get and drive the phases manually — that skips the run lock, phase tracking, and the host runtime contract entirely.

skill run --mode host does three things skill get does not:

1. Acquires the run lock (status = "in_progress") on the skill card.
2. Emits the host runtime contract that tells you to call the skill phase shims.
3. Indicates the active_phase so resumed runs continue from the right place.

Required sequence for every workflow run:

# 1. Initiate the run (acquires lock, emits run packet + host runtime contract)
deepvista skill run --mode host 

# 2. For each phase — open → execute → done
deepvista skill phase open  "Phase N: "
# … execute the phase using your own tools …
deepvista skill phase done  "Phase N: " [--next-phase "Phase N+1: "]

# 3. Finalize
deepvista skill complete  --review ""

If you called skill get and are already mid-workflow without a lock, call skill run --mode host now — it is idempotent on an already-in-progress card and will re-emit the correct active phase.

Non-obvious: skill run modes

skill run has three modes (set with --mode, default host):

| Mode | Behaviour | |---|---| | host | CLI prints a JSON run packet + SKILL.md body. The host agent (Claude Code, Cursor, etc.) drives the run using skill phase / skill complete shims. Use when the workflow needs host tools (Bash, Edit, MCPs, repo state). | | deepvista | Posts to /imagine, streams NDJSON from the DeepVista server agent end-to-end. Use for KB-internal workflows where server tools are sufficient. | | auto | Routes per-phase: server-side tool phases go to DeepVista, the rest stay host. |

Non-obvious: host-mode shims

After skill run --mode host, drive the run with:

deepvista skill phase open        "Phase N: "
deepvista skill phase done        "Phase N: " [--artifact-card-id ID] [--next-phase "…"]
deepvista skill phase reset       "Phase N: "   # revert a done/active phase to pending
deepvista skill phase need-input  "Phase N: " --reason ""  # :::dvNeedIntervention
deepvista skill phase pause       --reason ""  # technical blocker → :::dvNeedIntervention
deepvista skill complete          --review ""

complete appends ## Review, releases the run lock, and emits {"done": true}.

Non-obvious: sync and load

sync writes thin SKILL.md stubs (frontmatter + lazy-fetch shell) into the agent skills directory. Safe in a SessionStart hook — always exits 0. Idempotent; only touches dirs with the x-deepvista-catalog marker; never overwrites user-authored skills.

load fetches the full SKILL.md body for a catalog skill at invocation time (5-min cache). Called by stubs — rarely needed directly.

Examples

deepvista skill list
deepvista skill run  --input "Focus on Q4"          # host mode
deepvista skill run  --mode deepvista                # server agent
deepvista skill run  --mode auto                     # per-phase routing
deepvista skill phase open  "Phase 1: …"
deepvista skill phase done  "Phase 1: …" --artifact-card-id 
deepvista skill complete  --review "clean run, shipped Friday"
deepvista skill discover --category workflow
deepvista skill sync --dry-run

Continuing a run

skill run returns a run_chat_id. Continue with:

deepvista chat +send "Add one more step" --chat-id 

Importing a skill from a downloaded markdown file

When the user downloads a SKILL.md from another account and wants to import it without AI re-synthesis, write the content directly as a type=skill card. This is the right path when the markdown is already a complete, finished skill — no processing needed.

> [!CAUTION] Write — confirm before running.

deepvista card create --type skill \
  --title "" \
  --content-file /absolute/path/to/downloaded-skill.md \
  --no-enrich

--no-enrich skips entity enrichment. Use it here because the skill body is already structured — enrichment would add latency and noise without value.

After creation, verify with:

deepvista card get 
# https://app.deepvista.ai/vistabase/

Do not use skill create-from-note for this — that command runs the DeepVista agent to synthesize a skill from raw notes, which is unnecessary (and slow) when the SKILL.md content is already ready.

See also

• [skill-create-from-note.md](skill-create-from-note.md) — synthesize a skill from notes
• [skill-research-to-skill.md](skill-research-to-skill.md) — research then run pattern
• [skill-analyze-notes.md](skill-analyze-notes.md) — notes synthesis pattern
• [vistabase-card.md](vistabase-card.md) — card create full flag reference

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DeepVista-AI
• Source: DeepVista-AI/deepvista-cli
• License: Apache-2.0
• Homepage: https://www.deepvista.ai/

Install and usage instructions live in the source repository linked above.