nika
Runs repeatable AI work as checked, budgeted workflow files.
- License 许可
- MIT
- 最近更新
- 2026-10-22
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- nika
- risk
- critical
- author
- Thibaut Melen (@ThibautMelen) · SuperNovae Studio (github.com/supernovae-st)
- source
- https://github.com/supernovae-st/nika-agents/tree/main/skills/nika
- license
- MIT
- version
- 1.1.0
- metadata
- { "hermes": { "tags": [ "Workflow", "Automation", "Deterministic", "Cost-Control", "Audit", "Local-First", "MCP" ], "category": "autonomous-ai-agents", "homepage": "https://nika.sh", "related_skills": [ "opencode", "claude-code", "codex" ], "requires_toolsets": [ "terminal" ] } }
- platforms
- [ "linux", "macos" ]
- description
- Runs repeatable AI work as checked, budgeted workflow files.
- source_repo
- supernovae-st/nika-agents
- source_type
- community
- prerequisites
- { "commands": [ "nika" ] }
- license_source
- https://github.com/supernovae-st/nika-agents/blob/main/LICENSE
03 SKILL.md 正文
Nika Skill
Use Nika 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.yamlworkflow - 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
opencodeskill - 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
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="<id>")
process(action="log", session_id="<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 = green, safe to run. 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):
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-usdrefuses to start (exit 2, zero tokens) — and since 0.99 the pre-start floor prices the EFFECTIVE model,--modeloverride 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 runprints 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/<run>.ndjson", workdir="~/project")
terminal(command="nika trace verify .nika/traces/<run>.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 <file> --from <template> |
Scaffold a workflow (--from '?' lists) |
nika check <file> --json |
Static pre-flight — ALWAYS before run |
nika explain <file> |
Narrate: waves, cost floor, touches |
nika run <file> --model <p/m> --max-cost-usd <usd> |
Execute with budget |
nika test <file> |
Golden test under the mock provider (offline) |
nika trace show/verify/outputs/flow <trace> |
Receipts after a run (path from the run card's trace: line) |
nika doctor |
Diagnose env/keys — prints exact fixes |
nika catalog |
Provider/model ids + required env vars |
Procedure
- Verify readiness:
terminal(command="nika --version"); install per Prerequisites if missing. - If the task is new, scaffold:
nika new <file> --from <template>. - Check:
nika check <file> --json. Fix every finding (nika explain <code>). Do not run an unchecked file. - Preview offline when useful:
nika run <file> --model mock/echo. - Run with an explicit
--modeland, for any paid model, an explicit--max-cost-usd. - For long runs use
background=trueand poll withprocess(action="poll"|"log"). - After the run:
nika trace show <trace>+nika trace verify <trace>(path from the run card); report outputs, actual cost, and the verify verdict to the user.
Rules
- NEVER run an unchecked workflow —
nika checkfirst, every time. - ALWAYS pass
--max-cost-usdwhen the model is a paid cloud model. - Prefer local models (
ollama/...) ormock/echofor drafts; escalate to cloud models only when needed. - Report the final run card honestly: status, actual cost, trace path,
trace verifyverdict. - One workflow file per delegated task; keep files in the user's repo so they are diffable and reusable.
- If a run fails, read
nika explain <NIKA-code>before retrying — do not blind-retry.
Pitfalls
nika runrenders live on a TTY; when piped (Hermes terminal), output can stay quiet until completion — for anything long, preferbackground=true+ poll, then readnika trace show <trace>for the final card.nika newwith no--fromopens a guided TTY flow; in a pipe it fails fast naming the flag — always pass--from <template>when delegating.- The budget guard stops NEW admissions: one wide parallel wave can overshoot
by that wave's spend. Tighten with
max_parallel:when the budget is strict. - Uncataloged model ids meter as $0 — never rely on
--max-cost-usdfor a custom endpoint model. - Workflow
outputs:are not resolved on a budget stop — per-task values live in the trace (nika trace outputs).
Limitations
- Static checks reduce risk but cannot prove that remote content, shell steps, provider behavior, or generated outputs are safe or correct.
- Cost caps are not reliable for uncataloged paid models and a parallel wave can overshoot before new work is stopped; require explicit user approval for paid runs and report the actual ledger result.
- Trace verification proves integrity of the recorded chain, not correctness of the workflow or truth of its outputs.
Verification
Smoke test (offline, zero keys):
terminal(command="nika examples run 01-hello --model mock/echo")
Success criteria: run completes exit 0 with a final run card · nika check
exits 0 before any real run · nika trace verify exits 0 after the run.
04 同仓库更多 Skills
testing-best-practices
Laravel test design and review. Use when selecting coverage, naming or structuring tests, choosing assertions or test data, isolating dependencies, testing HTTP or security boundaries, improving suite performance, or reviewing test value. Use framework guidance or search-docs for Pest and PHPUnit syntax.
tailwindcss-development
Always invoke when the user's message includes 'tailwind' in any form. Also invoke for: building responsive grid layouts (multi-column card grids, product grids), flex/grid page structures (dashboards with sidebars, fixed topbars, mobile-toggle navs), styling UI components (cards, tables, navbars, pricing sections, forms, inputs, badges), adding dark mode variants, fixing spacing or typography, and Tailwind v3/v4 work. The core use case: writing or fixing Tailwind utility classes in HTML templates (Blade, JSX, Vue). Skip for backend PHP logic, database queries, API routes, JavaScript with no HTML/CSS component, CSS file audits, build tool configuration, and vanilla CSS.
laravel-best-practices
Apply this skill whenever writing, reviewing, or refactoring Laravel PHP code. This includes creating or modifying controllers, models, migrations, form requests, policies, jobs, scheduled commands, service classes, and Eloquent queries. Triggers for N+1 and query performance issues, caching strategies, authorization and security patterns, validation, error handling, queue and job configuration, route definitions, and architectural decisions. Also use for Laravel code reviews and refactoring existing Laravel code to follow best practices. Covers any task involving Laravel backend PHP code patterns.
infer-conventions
Use this skill to analyze how a Laravel application is actually written and record its conventions as shared rules. Trigger when the user wants to detect, infer, document, or standardize project conventions or coding style, set up or grow `.ai/rules`, resolve mixed or conflicting patterns (e.g. "are we using Form Requests or inline validation?"), or onboard agents and teammates to "how we do things here". Covers: a systematic sweep of ~49 Laravel convention dimensions (validation, models, architecture, testing, frontend, database, console), open-ended house-pattern discovery, conflict reporting, and recording rules scoped to the right paths via the Boost `record-rule` MCP tool. Only run this skill when the user explicitly asks for it; never start a sweep as part of another task. Do not use for one-off code review, enforcing formatting a linter already handles, or editing `.ai/rules` files by hand.
inertia-react-development
Develops Inertia.js v2 React client-side applications. Activates when creating React pages, forms, or navigation; using <Link>, <Form>, useForm, or router; working with deferred props, prefetching, or polling; or when user mentions React with Inertia, React pages, React forms, or React navigation.
deploying-to-cloud
Deploys and manages Laravel applications on Laravel Cloud using the `cloud` CLI. Use when the user wants to deploy an app, ship to Cloud, create or manage applications, environments, databases, caches, object storage, queues, domains, instances, background processes, secrets, compute, scheduled tasks, or Laravel Cloud infrastructure; or check billing, usage, or spend. Triggers on deployment, shipping, Cloud management, environment setup, database provisioning, billing or usage queries, the `cloud` CLI, and Laravel Cloud deployment troubleshooting.