CLI commands

The CLI is one binary, skilled_crew. Run any subcommand with npx skilled_crew <subcommand>, or install it globally (npm install -g skilled_crew) and call skilled_crew <subcommand> directly.

Quick reference

The durable job lane (create, list, cost, dispatcher, schedules) is no longer part of this CLI — it moved to the separate skilled_workflow package and its own skilled_workflow binary. See Jobs & Scheduling › CLI reference.

Shared flags

chat and run accept the same set of flags:

chat

npx skilled_crew chat -c ./data/skillets/todo_list.skilled_crew.yaml
npx skilled_crew chat -c todo_list   # same crew, resolved by skilletId
npx skilled_crew chat                # no -c → defaults to the todo_list crew

Starts a readline REPL. The prompt shows the skillet name. Existing session history is replayed before the first prompt so you can see prior context.

• Type a message to send it to the agent.
• Type a / command — built-in (slash commands reference) or user-defined (.command.md) — for slash behavior.
• Hit Ctrl+C or type /exit to quit. MCP connections are closed cleanly on exit.

run

npx skilled_crew run -c ./data/skillets/todo_list.skilled_crew.yaml 'what are my tasks?'

Sends one task, prints the response, exits. Useful for scripting, cron jobs, or quick smoke tests. Same flags as chat. Streaming works (-s).

list

npx skilled_crew list

Prints the skilletId and resolved path of every crew that -c can load by id — one per line, id<TAB>path. Crews are discovered from the package’s bundled data/skillets and from your user config directory; a user crew overrides a bundled crew that shares the same id. Use this to find the id to pass to chat -c <id> or run -c <id>.

eval_run

npx skilled_crew eval_run \
  -c ./data/skillets/bluesky_social_manager.skilled_crew.yaml \
  -f ./data/skillets/evals/bluesky_evals

Runs every eval in <eval-folder>/evals.json against the skillet. Writes one eval_<id>_run.json per eval into the sibling <eval-folder>_output/ directory. See Evaluations.

eval_grade

npx skilled_crew eval_grade -f ./data/skillets/evals/bluesky_evals

Reads the eval_<id>_run.json files from a prior eval_run and grades each eval with an LLM judge (default openai/gpt-4.1-nano, overridable with SKILLET_MODEL_EVAL in <provider>/<model> form). Writes eval_<id>_grade.json back into the same <eval-folder>_output/ directory. Scores run 0–10.

schema_generate

npx skilled_crew schema_generate

Serializes the Zod source to JSON Schema: SkilledCrewYamlConfigZod → data/schemas/skilled_crew.schema.json. Re-run when you change the Zod source. (The .job_workflow.yaml schema is generated by the separate skilled_workflow package’s own schema:generate.) See JSON Schema (VSCode).

schema_check

npx skilled_crew schema_check

Regenerates the schema in-memory and compares it to the committed file. Exits non-zero if it differs. This is wired into CI (npm run schema:check) so a stale schema can’t slip in.

convert

npx skilled_crew convert from_claude <dotClaudeDir> -c <path>
npx skilled_crew convert to_claude   <dotClaudeDir> -c <path>

Bridges Claude Code’s .claude folder layout and skilled_crew’s .skilled_crew.yaml. Two directions:

• from_claude — read an existing Claude folder and generate a .skilled_crew.yaml that references it. Use this to bring a Claude Code project into skilled_crew.
• to_claude — read a .skilled_crew.yaml and write a Claude folder that Claude Code can consume. Use this to hand a skillet back to Claude Code.

Both subcommands take the Claude folder as a positional argument and require -c to point at the .skilled_crew.yaml. Note that -c here is always a file path (the file to write or read), not a pathOrId like the chat / run flag.

convert from_claude

npx skilled_crew convert from_claude ./data/dot_claude \
  -c ./data/skillets/my_crew.skilled_crew.yaml

Reads the Claude folder and writes a single-agent .skilled_crew.yaml. This is an index operation: the YAML only references the files in the Claude folder, it does not copy them. Every path in the emitted YAML is written relative to the output YAML file so the result stays portable.

What maps to what:

Details:

• The skillet id is derived from the folder name — or its parent directory when the folder is named .claude or dot_claude — sanitized to [a-z0-9_]. The single agent is named <id>_agent.
• A .mcp.json aggregate is split into one file per server. Each entry’s key becomes the server name, and type is inferred when absent (stdio when a command is present, http when only a url is). Entries that duplicate an existing mcp_servers/*.json server are skipped.
• This is single-agent only. Additional agents/*.md subagent files are detected and reported, not converted.
• Anything detected but not converted is printed as a note: line, so nothing is dropped silently.

convert to_claude

npx skilled_crew convert to_claude ./build/dot_claude \
  -c ./data/skillets/todo_list.skilled_crew.yaml

Reads a .skilled_crew.yaml and writes a Claude folder. Unlike from_claude, this direction copies the referenced files into the Claude layout, creating <dotClaudeDir> if it does not exist.

What maps to what:

Details:

• The entry agent is entryPointAgent, or the first agent when that is unset.
• The export is best-effort, not a guaranteed round-trip. skilled_crew concepts with no Claude equivalent — multi-agent routing, toolChoice, script_runtime — are flattened or dropped. Each loss is printed as a note: line.
• Every file written is printed, so you can see exactly what landed in the folder.

log stream

npx skilled_crew log stream

Discovers every .jsonl session log under the session-logs root (.skilled-agent/state/.agent_session_logs in a checkout; override with --logs-dir <path>), prints the existing user/agent turns oldest-first, then follows new appends — across all sessions, including running job workers. See Sessions and logs.

Jobs (separate package)

The durable job lane — creating jobs from workflows, listing the board, rolling up cost, running the dispatcher, and managing recurring schedules — is not part of the _skillet_agent CLI. It moved to the separate skilled_workflow package, which embeds the agent runtime as a library and exposes its own skilled_workflow binary (the jobs … command group). The full command tree is documented in Jobs & Scheduling › CLI reference.

npm script shortcuts

The package ships a few common invocations as npm scripts:

npm run dev:chat:todo_list                 # chat with todo_list skillet
npm run dev:run:todo_list                  # one-shot: "what are my tasks?"
npm run dev:chat:bluesky_social_manager    # chat with the bluesky skillet
npm run dev:chat:business_analyst
npm run dev:chat:web_browser
npm run dev:chat:multi_bluesky_agent       # multi-agent example
 
npm run schema:generate                    # schema_generate
npm run schema:check                       # schema_check
 
npm run dev:eval:run:bluesky               # eval_run on the bluesky suite
npm run dev:eval:grade:bluesky             # eval_grade on the bluesky suite
 
npm run dev:log:stream                     # log stream
 
npm run dev:cost:list                      # one-shot cost UI (openai-cost)
npm run dev:cost:list:watch                # live cost UI, refreshed continuously
npm run dev:cost:clear                     # reset the cost tracker

These are aliases — read packages/_skillet_agent/package.json to see what each one maps to. The dev:jobs:* scripts now live in the separate skilled_workflow package.