Install

Prerequisites

Node.js 22+ and npm (CI runs on Node 22). The package is ESM and targets ES2022.
An OpenAI API key if you plan to use gpt-* models. Local models via LMStudio or Ollama need no key.

Clone and install

skillet_agent lives in the skillet_agent monorepo . Each package manages its own dependencies — there is no root install step.


git clone https://github.com/skilled-crew/skilled_crew.git
cd skilled_crew/packages/_skillet_agent
npm install

npm install runs the package’s postinstall step, which seeds a default user (john@example.com) so the CLI works on its first run without a manual setup step (issue #261 ).

Configure the environment

The CLI loads variables from .env in the package root via dotenv. Copy the sample file and edit it:


cp .env-sample .env

Required for OpenAI models:

Variable	Default	Purpose
`OPENAI_API_KEY`	—	API key for any `openai/*` model. Get one at platform.openai.com/api-keys .

Optional overrides:

Variable	Default	Purpose
`OPENAI_BASE_URL`	OpenAI SDK default	Override the base URL for the `openai` provider (e.g. to point at a proxy or gateway).
`LMSTUDIO_BASE_URL`	`http://localhost:1234/v1`	Override the base URL for the `lmstudio` provider (e.g. a remote LMStudio host).
`OLLAMA_BASE_URL`	`http://localhost:11434/v1`	Override the base URL for the `ollama` provider (e.g. a remote Ollama host).
`SKILLET_MODEL_RUNNER`	`openai/gpt-4.1-nano`	Model used by the orchestrator and skill agents. Format: `<provider>/<model>`. Supported providers: `openai`, `lmstudio`, `ollama`. When set, it is preflighted before the run and exits early if the provider is unreachable.
`SKILLET_MODEL_EVAL`	`openai/gpt-4.1-nano`	Model used by the LLM-as-judge in `eval_grade`. Same `<provider>/<model>` format.

If the override is not set, the runner falls back to the per-agent model line in AGENTS.md, then to openai/gpt-4.1-nano. See Models for the full list of supported providers.

The agent itself reads one optional run-control variable:

Variable	Default	Purpose
`SKILLET_MAX_TURNS`	`50`	Per-run cap on agent turns, before the runner stops the loop.

Background jobs

The durable job lane — background jobs, crews, the dispatcher, and schedules — now lives in a separate skilled_workflow package, not in _skillet_agent. It reuses the same agent runtime as a library and reads its own optional variables (spend caps via SKILLET_JOB_BUDGET_USD / SKILLET_JOB_BUDGET_WINDOW_HOURS, notifications via SKILLET_NOTIFY_*), documented in Jobs & Scheduling. SKILLET_JOB_ID is set automatically on a job worker process — you never set it by hand.

Web client

The web client reads the same .env (it loads packages/_skillet_agent/.env) and adds:

Variable	Required	Purpose
`SESSION_SECRET`	yes (web only)	Secret for signing express-session cookies. The server refuses to start without it.
`PORT`	no (default `5173`)	Port the web server listens on.
`GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET`	no	Set both to enable Google OAuth sign-in; otherwise only local email/password auth is available.

See Web Client › Running for the full setup.

Verify

Run the sample todo_list skillet in one-shot mode:


npm run dev:run:todo_list

You should see the agent list the tasks currently in the todo_list skill’s own data file (data/dotclaude_todo_list/_data/tasks.json). If you instead want an interactive REPL:


npm run dev:chat:todo_list

Either command creates a .skilled-agent/ directory at the repo root (when running from a checkout), holding the session SQLite store, cost tracker, and JSONL replay logs under state/, and the response cache under cache/. Installed via npm, these follow the XDG base directories instead. See Sessions and logs › Where these files live for the full layout.

Walk through Run your first skillet for an annotated tour of the todo_list example — what’s in the YAML, what each skill does, and how to make your own.