Agent Skills
› davepoon/buildwithclaude
› nika
nika
GitHubNika用于将可重复的AI工作流定义为.yaml文件，通过预检查审计成本、权限和模式，确保运行安全可控。支持DAG编排、成本封顶、防篡改追踪及CI集成，保障AI任务透明高效执行。
触发场景
需要自动化执行重复性AI任务
要求严格管控AI调用成本与权限
需要生成可审计且防篡改的工作流执行记录
安装
npx skills add davepoon/buildwithclaude --skill nika -g -y
SKILL.md
Frontmatter
{
"name": "nika",
"category": "automation",
"requires": {
"bins": [
"nika"
]
},
"description": "Runs repeatable AI work as checked, budgeted workflow files. The agent captures a repeated task as a .nika.yaml DAG, audits cost\/permits\/schema before a single token is spent, and runs it with tamper-evident traces."
}
Authoring Nika workflows
Nika turns repeatable AI work into files: one .nika.yaml, four verbs,
audited before it runs. You author the file; nika check is the
oracle; the human runs it.
The loop (always)
- Start from a template or example, never from scratch:
nika examples list·nika examples show <slug>·nika new --from <template> <file>.nika.yaml - Write the file. Envelope is always
nika: v1+workflow: <kebab-id>+tasks:. Pick models and builtins from the embedded catalogs —nika catalog(providers · models · capabilities · which env var each needs) andnika tools(thenika:*builtins aninvokereaches without MCP); before a run,nika inspect <file>shows the anatomy: tasks · waves · the cost floor. - Check it:
nika check <file>(exit 0 = clean · 2 = findings), thennika check --native-strict <file>— it fails on anynative-firsthint (anexec:a builtin covers). - Repair from the diagnostics — they name the exact task, reference
and fix. Unknown code?
nika explain NIKA-XXXX. - Repeat 3–4 until clean. Never hand a file to the human that does
not pass
nika check— and pass--native-stricttoo, unless every remainingexec:is in the exec ledger (below). - The human (or CI) runs it:
nika run <file>. Preview offline with--model mock/echo; run locally with--model ollama/<model>. Inputs ride--var key=value(repeatable · unknown keys refused); a run paused on anika:promptresumes withnika run <file> --resume <trace> --answer <task>=<value>(confirm gates take booleans:--answer approve=true). - Pin it for CI:
nika test <file> --updatewrites<file>.golden.jsonfrom an offline mock run;nika test <file>replays and compares — deterministic, zero keys. - Prove a run that mattered: every run writes a hash-chained
journal to
.nika/traces/—nika trace verify <trace>checks the chain (tamper-evidence),nika trace show <trace>reads the card. Cite the trace, never a memory of the run.
Cost honesty (never hide unknown spend)
nika checkprints the cost ceiling BEFORE any token:≤ $Xis a ceiling ·≥ $X FLOORmeans at least one task is unbounded — name the reason (a missingmax_tokens, an uncataloged model, an expression fan-out), never round it to $0.- A local model (
ollama/…) is unpriced compute, not « free » — say "unpriced", never "$0" or "free". - A spend cap rides the run:
nika run <file> --max-cost-usd <n>blocks BEFORE the call that would cross the cap. nika explain <file>narrates all of this (waves · cost · touches · how to run) — use it before handing a workflow to a human.
The four verbs (exactly one per task)
infer:— an LLM call (prompt,schema?for typed output,max_tokens?)exec:— a shell command (command,capture: text|structured) · last resort: run the native-first interrogation first (below)invoke:— a builtin or MCP tool (tool,args) · HTTP fetch istool: "nika:fetch", a tool, not a verbagent:— a bounded multi-turn loop (prompt,toolsallowlist,max_turns,max_tokens_total)
Native-first (the law)
The order is invoke: nika:* → invoke: mcp:<server>/<tool> →
exec:. Before writing ANY exec:, answer in your head:
- Which builtin replaces it?
nika tools --jsonis the catalog. HTTP (curl/wget/helper fetch) →nika:fetch· uploads →multipart:· site crawls →traverse:· file plumbing (cat/tee/cp/mkdir) →nika:read/nika:write(create_dirs: true) · JSON shaping (jq/sed) →nika:jq(or anoutput:binding) · in-place edits →nika:edit· image/speech provider calls →nika:image_generate/nika:tts_generate· image styling (ImageMagick convert / PIL filters / dither scripts) →nika:image_fx(deterministic — same input+args = same bytes, the artifact sha256 joins the trace chain). - Which MCP tool replaces it? A product API deserves an MCP server, never a helper script.
- Neither? Name the exact gap — then
exec:is legitimate (build tools · git · a product CLI with no MCP surface yet) and goes in the ledger.
Never write a helper script (node bin/helper.mjs …) that wraps
HTTP/files/JSON — that is native-first/005, the exact failure class
this law exists for.
Exec ledger (mandatory when any exec remains)
Every surviving exec: gets a row in the workflow's header comment:
# EXEC LEDGER ·
# | task | command | why no native path | unlock that removes it |
--native-strict + a complete ledger = a reviewable workflow.
Discipline
- References:
${{ tasks.<id>.output }}·${{ vars.x }}·${{ env.KEY }}·${{ secrets.X }}(never inline a credential). - A task that reads another task's output MUST declare it in
depends_on: [<id>]. - Models are
provider/name(ollama/llama3.2:3blocal-first ·mock/echooffline preview). - Timeouts are quoted Go-durations (
timeout: "7m") — give local providers ≥300s: thinking models routinely think past 30s. - Declare the blast radius:
nika check --infer-permits <file>prints the tightestpermits:block — paste it in (default-deny from then on). - Structured output: give
infer:aschema:; addadditionalProperties: falsefor a deterministic shape. - Auth rides
headers: { x-api-key: "${{ secrets.KEY }}" }(masked · declared insecrets:with itsegress:sink) — neverexec: curlfor the sake of a header.
版本历史
- b79ed72 当前 2026-07-19 18:35
