--- name: nika description: "Runs repeatable AI work as checked, budgeted workflow files." risk: critical source: https://github.com/supernovae-st/nika-agents/tree/main/skills/nika date_added: "2026-07-12" source_repo: supernovae-st/nika-agents source_type: community version: 1.1.0 author: Thibaut Melen (@ThibautMelen) · SuperNovae Studio (github.com/supernovae-st) license: MIT license_source: https://github.com/supernovae-st/nika-agents/blob/main/LICENSE platforms: [linux, macos] prerequisites: commands: [nika] metadata: hermes: tags: [Workflow, Automation, Deterministic, Cost-Control, Audit, Local-First, MCP] category: autonomous-ai-agents related_skills: [opencode, claude-code, codex] homepage: https://nika.sh requires_toolsets: [terminal] --- # Nika Skill Use [Nika](https://nika.sh) as a deterministic workflow worker orchestrated by the Hermes `terminal` tool. Nika is an open-source (AGPL) Rust engine that captures a repeatable AI task as a plain-text `*.nika.yaml` file, audits it **before a single token is spent** (plan, cost floor, secret flows, types), executes it against local or cloud providers (Ollama/llama.cpp/vLLM included), and records a tamper-evident trace. Division of labor: **Hermes orchestrates · Nika captures repeatable work as a checkable file and runs it with receipts.** Nika is NOT another coding agent — for autonomous coding, use the `opencode` skill. Delegate to Nika when the work should be *repeatable, budgeted, and auditable*. ## When to Use - The user asks to run, check, or author a `*.nika.yaml` workflow - A task will be repeated (daily digest, triage, ETL, report, multi-step LLM pipeline) — capture it as a workflow instead of re-prompting - The user wants a hard cost cap, a cost estimate before running, or receipts/audit of what ran - A pipeline mixes models/providers (local + cloud) or mixes LLM steps with shell/HTTP/file steps - The user wants a run they can replay, verify, or reproduce later ### When NOT to use - One-off questions or single tool calls — just answer or use a tool - Autonomous code implementation/refactoring/PR review — use the `opencode` skill - Interactive back-and-forth tasks — workflows are non-interactive by design ## Prerequisites - Nika installed: `brew install supernovae-st/tap/nika` — other install paths (script, manual download) are documented at https://nika.sh: installing is a human step, not something this skill runs - Verify: `terminal(command="nika --version")` - Zero keys needed for local/offline work: `--model mock/echo` (offline) and `--model ollama/...` (local) run without any API key - Cloud providers read standard env vars from the shell; `terminal(command="nika doctor")` diagnoses and prints exact fix commands Confirm the installed Nika version and its actual CLI schema; the 0.98/0.99 examples and provider/model IDs below are historical, not verified current API promises. Hermes terminal/process wrappers are host-specific pseudocode. A mock model does not make arbitrary workflows offline: shell, fetch and MCP tasks can still access networks or mutate files. Inspect every task/tool argument and secret/data destination before mock or real execution, and restrict scope/credentials. Workflows with model calls are repeatable definitions, not deterministic outputs. Budget protection can overshoot and does not cover arbitrary tool-side charges. Redact traces before sharing; a valid hash chain does not authenticate the truth or completeness of recorded events. The skill MIT notice and engine AGPL claim refer to distinct artifacts and must be verified independently before redistribution. ## How to Run Prove the toolchain offline first (no key, no network): ``` terminal(command="nika examples run 01-hello --model mock/echo") ``` Run a real workflow — local model first: ``` terminal(command="nika run flow.nika.yaml --model ollama/qwen3.5:4b", workdir="~/project") ``` Cloud model with a hard budget (always set one for paid models): ``` terminal(command="nika run flow.nika.yaml --model mistral/mistral-small-latest --max-cost-usd 0.25", workdir="~/project") ``` Pass workflow variables: ``` terminal(command="nika run report.nika.yaml --var city=Paris --var days=7 --max-cost-usd 0.50", workdir="~/project") ``` Long runs: launch in background and poll — do not block the turn: ``` terminal(command="nika run long.nika.yaml --max-cost-usd 1.00", workdir="~/project", background=true) process(action="poll", session_id="") process(action="log", session_id="") ``` ### The check-before-run law Never run a workflow you have not checked. `nika check` is a static pre-flight (no tokens spent, no network): plan shape, cost floor, secret-flow analysis, type checks, tool args. ``` terminal(command="nika check flow.nika.yaml --json", workdir="~/project") ``` Findings carry `NIKA-XXXX` codes that explain themselves via `nika explain NIKA-XXXX`. Exit 0 means the implemented static checks passed; it is not permission or proof that execution is safe. Fix findings before running — never suppress them. ### Authoring a workflow Turn a repeated task into a file. List templates, then instantiate: ``` terminal(command="nika new --from '?'") terminal(command="nika new flow.nika.yaml --from chain", workdir="~/project") ``` `--from` also accepts plain-words intent. Edit the skeleton (`vars:`, `tasks:`, `outputs:`), then **check it**. `nika explain flow.nika.yaml` narrates what it will do, the waves, the cost floor, and what it touches — before anything runs. The artifact you are producing looks like this (checks clean on 0.98): ```yaml nika: v1 workflow: daily-brief model: ollama/qwen3.5:4b tasks: - id: fetch invoke: tool: "nika:fetch" args: { url: "https://hn.algolia.com/api/v1/search?tags=front_page" } - id: brief depends_on: [fetch] infer: max_tokens: 300 prompt: | Five bullet points, most signal first: ${{ tasks.fetch.output }} outputs: brief: ${{ tasks.brief.output }} ``` One file, plain YAML: tasks, an explicit dependency, a bounded model step, a declared output. That file is what gets checked, run, diffed and reused. ### Cost honesty - When the workflow prices above the budget, `--max-cost-usd` refuses to start (exit 2, zero tokens) — and since 0.99 the pre-start floor prices the EFFECTIVE model, `--model` override included - Mid-run, the ledger stops the workflow the moment real spend crosses the budget: the crossing call completes, nothing new starts, the run fails `NIKA-1704` (exit 1) with spent-vs-budget - Estimates use LIST RATES from the vendored public catalog; local · mock · unpriced work is never blocked - A model absent from the catalog meters as $0 — a paid *uncataloged* model runs with no budget protection; prefer cataloged ids (`nika catalog`) - Report the cost line from the final run card (the summary block `nika run` prints last — status, cost, trace path) back to the user verbatim ### Receipts and verification Every run writes a trace under `.nika/traces/` — the run card prints the trace path on its `trace:` line. Both commands take that path (bare invocations are a usage error): ``` terminal(command="nika trace show .nika/traces/.ndjson", workdir="~/project") terminal(command="nika trace verify .nika/traces/.ndjson", workdir="~/project") ``` `trace verify` checks the tamper-evidence hash chain: exit 0 intact · 2 broken · 3 pre-chain. Also useful: `nika trace outputs` · `nika trace flow` · `nika trace reproduce` · `nika trace export` (OTLP lines). ### Optional: MCP oracle tools Nika also ships a read-only MCP oracle (`nika mcp`) exposing validation and learning tools (`nika_check`, `nika_explain`, `nika_schema`, `nika_examples`, `nika_template`, `nika_canon`, `nika_catalog`, `nika_tools`). If the user wants those wired into their agent client, point them at the wiring guide — https://github.com/supernovae-st/nika-agents/tree/main/integrations/mcp — editing the client's own configuration is the user's step, never this skill's. Without the oracle, everything above still works over the terminal; running workflows stays there regardless, where the budget flags and traces live. ## Quick Reference | Command | Use | |---------|-----| | `nika welcome` | What Nika is + what this machine has (offline, exit 0) | | `nika new --from