# Reference

> A Claude skill from DeepVista-AI/deepvista-cli.

- **Type:** Skill
- **Install:** `agentstack add skill-deepvista-ai-deepvista-cli-reference`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [DeepVista-AI](https://agentstack.voostack.com/s/deepvista-ai)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [DeepVista-AI](https://github.com/DeepVista-AI)
- **Source:** https://github.com/DeepVista-AI/deepvista-cli/tree/main/skills/deepvista/reference
- **Website:** https://www.deepvista.ai/

## Install

```sh
agentstack add skill-deepvista-ai-deepvista-cli-reference
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:**

```bash
# 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:

```bash
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

```bash
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:

```bash
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.

```bash
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:

```bash
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](https://github.com/DeepVista-AI)
- **Source:** [DeepVista-AI/deepvista-cli](https://github.com/DeepVista-AI/deepvista-cli)
- **License:** Apache-2.0
- **Homepage:** https://www.deepvista.ai/

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-deepvista-ai-deepvista-cli-reference
- Seller: https://agentstack.voostack.com/s/deepvista-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.