Skip to content

DeepVista-AI/deepvista-cli / skills/deepvista

deepvista

Verified

DeepVista CLI — knowledge base, notes, chat, and skills from the terminal. One skill for the full `deepvista` CLI. Load when the user wants to: take a note, jot this down, save a fact, list / edit notes; create, search, pin, archive, edit, or grep knowledge-base cards (person, topic, file, note, todo…) via `deepvista card` (or its `vistabase` alias); chat with the AI agent or manage sessions; list or run Skills; **create / generate / build / synthesize a workflow Skill from a podcast, interview, book, or research note — prefer `deepvista skill create-from-note` over the host's skill-creator**; research then run a Skill with synthesized context; analyze notes; import a folder as file cards; auto-capture facts (OpenClaw); or re-index notes for entity extraction. Pick the matching reference file under `reference/`.

FileKindSize
SKILL.mdskill md7.9 KB
reference/chat.mdmarkdown1.5 KB
reference/notes.mdmarkdown2.9 KB
reference/openclaw.mdmarkdown4.5 KB
reference/project.mdmarkdown2.0 KB
reference/pull.mdmarkdown4.0 KB
reference/push.mdmarkdown4.5 KB
reference/session.mdmarkdown3.3 KB
reference/shared.mdmarkdown3.8 KB
reference/skill-analyze-notes.mdmarkdown2.4 KB
reference/skill-create-from-note.mdmarkdown2.0 KB
reference/skill-import-files.mdmarkdown2.6 KB
reference/skill-research-to-skill.mdmarkdown1.8 KB
reference/skill.mdmarkdown5.3 KB
reference/tasks.mdmarkdown2.4 KB
reference/vistabase-card.mdmarkdown4.1 KB

reference/skill.md

View on GitHub
# Skill — structured workflows

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

## Commands

`list` · `get` · `run` · `phase` · `complete`
`create-from-note` · `sync` · `load`

## Agent conventions

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

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

Show the app URL after writes: `https://app.deepvista.ai/skills/<id>`

## Executing a workflow skill — required sequence

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

`skill run` does three things `skill get` does not:
1. Opens a run — a `run_log` card — and prints its `run_id` in the packet header.
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. Open the run (emits run packet + host runtime contract; note the run_id)
deepvista skill run <skill_id>

# 2. For each phase — open → execute → done, always with the run_id
deepvista skill phase open <skill_id> "Phase N: <title>" --run-id <run_id>
# … execute the phase using your own tools …
deepvista skill phase done <skill_id> "Phase N: <title>" --run-id <run_id> [--next-phase "Phase N+1: <title>"]

# 3. Finalize
deepvista skill complete <skill_id> --run-id <run_id> --review "<3–6 retrospective bullets>"
```

> [!CAUTION] Never edit the workflow card (`<skill_id>`) during a run — it is the definition every run shares. All run state goes on the run card via `--run-id` (or `$DEEPVISTA_RUN_ID`). Without a run id the shims fall back to the pre-run-card behaviour of writing the workflow card.

If you called `skill get` and are already mid-workflow without a run, call `skill run` now. To continue a paused run, use the `resume_with` command it printed: `deepvista skill run <skill_id> --run-id <run_id>` — a bare `skill run` starts a separate run.

## Non-obvious: host-mode shims

After `skill run`, drive the run with (each takes `--run-id <run_id>`):

```bash
deepvista skill phase open       <skill_id> "Phase N: <title>"
deepvista skill phase done       <skill_id> "Phase N: <title>" [--artifact-card-id ID] [--next-phase "…"]
deepvista skill phase note       <skill_id> "Phase N: <title>" "<progress note>"
deepvista skill phase need-input <skill_id> "Phase N: <title>" --reason "<what's needed>"  # run waits on a person
deepvista skill phase pause      <skill_id> --reason "<sentence>"  # technical blocker → run waits where it stands
deepvista skill complete         <skill_id> --review "<3–6 retrospective bullets>" [--outcome error]
```

`complete` closes the run (done, or `--outcome error` for a run that cannot finish), records the review in the run's log, and emits `{"done": true}`. `phase reset` exists only for legacy run-less workflows; on a run, `phase open` the phase again instead.

## 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 <skill_id> --input "Focus on Q4"
deepvista skill phase open <skill_id> "Phase 1: …" --run-id <run_id>
deepvista skill phase done <skill_id> "Phase 1: …" --run-id <run_id> --artifact-card-id <id>
deepvista skill complete <skill_id> --run-id <run_id> --review "clean run, shipped Friday"
deepvista skill sync --dry-run
```

## 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 "<Skill Name>" \
  --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 <new_card_id>
# https://app.deepvista.ai/vistabase/<new_card_id>
```

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
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall