| name | skynet-dev |
| description | Manage the Skynet multi-agent collaboration network using the local dev CLI (pnpm skynet). Use when developing and testing Skynet locally. |
Skynet Management Skill (Development)
You can manage the Skynet multi-agent collaboration network using the local dev CLI. All commands below are non-interactive (pass all options as flags) so you can run them directly via your shell tool.
Prerequisites: From the Skynet repo root, run pnpm install && pnpm build first.
Note: All commands use pnpm skynet instead of skynet. This runs the locally built CLI.
Workspace Management
Create a workspace
pnpm skynet workspace new --name <workspace-name> [--host <host>] [--port <port>]
--name (required): Human-readable workspace name--host (optional): Bind address, default 0.0.0.0--port (optional): Port number, default 4117
List workspaces
pnpm skynet workspace list
Delete a workspace
pnpm skynet workspace delete <workspace-uuid> --force
Removes the workspace from the registry and deletes all its data (agents, messages, config).
Start a workspace (daemon)
pnpm skynet workspace start <name-or-id> -d
Stop a workspace
pnpm skynet workspace stop <name-or-id>
Check workspace daemon status
pnpm skynet workspace status <name-or-id>
View workspace logs
pnpm skynet workspace logs <name-or-id>
Agent Management
All agent commands require a running workspace. --workspace <name-or-id> is always required.
Create an agent
pnpm skynet agent new --name <agent-name> --type <agent-type> [--role <role>] [--persona <persona>] [--workdir <path>] [--skills <spec...>] --workspace <name-or-id>
--name (required): Agent display name--type (required): Agent type. Currently claude-code, opencode, and codex-cli are supported. Other types (gemini-cli, generic) are not yet supported — do not use them unless explicitly asked by the user.--role (optional): Agent's role description (e.g., "backend engineer")--persona (optional): Persona description for the agent's behavior--workdir (optional): Custom working directory (default: ~/.skynet/<ws>/<id>/work)--skills (optional, repeatable): Install skills into the agent's working directory via npx skills add. Format: source[:skill-name]. Can be specified multiple times (e.g., --skills github.com/org/repo --skills ./local-skill:my-skill)
Working directory prompt: If the user does not explicitly specify --workdir, you must ask the user before running the command:
The agent's working directory determines where it reads/writes files. Would you like to:
- Specify a custom working directory (e.g., a project repo path)
- Use the default (
~/.skynet/<ws>/<id>/work)
If the user chooses a custom path, pass it via --workdir <path>. If they choose the default, omit --workdir.
Finding skills: If the user wants to create an agent with a particular skill but does not provide a specific skill source/path, search for it first:
npx skills find <query>
Review the search results with the user and confirm which skill to use before passing it to --skills.
Start an agent
pnpm skynet agent start <agent-name-or-id> --workspace <name-or-id>
Connects the agent to the workspace and starts processing messages as a background daemon (default). Use -f to run in foreground instead.
Stop an agent
pnpm skynet agent stop <agent-name-or-id> --workspace <name-or-id>
Check agent daemon status
pnpm skynet agent status <agent-name-or-id> --workspace <name-or-id>
View agent logs
pnpm skynet agent logs <agent-name-or-id> --workspace <name-or-id>
Delete an agent
pnpm skynet agent delete <agent-uuid> --force --workspace <name-or-id>
Deletes the agent from the workspace. Fails if the agent is currently connected.
Interrupt an agent
pnpm skynet agent interrupt <agent-name-or-id> --workspace <name-or-id>
Interrupts the agent's currently running task (equivalent to Ctrl+C). The agent remains connected and can receive new tasks.
Reset an agent's session (forget)
pnpm skynet agent forget <agent-name-or-id> --workspace <name-or-id>
Clears the agent's conversation history so it starts fresh. Useful when reassigning an agent to an unrelated task.
List agents
pnpm skynet agent list --workspace <name-or-id>
Human Management
Create a human
pnpm skynet human new --name <human-name> --workspace <name-or-id>
Delete a human
pnpm skynet human delete <human-uuid> --force --workspace <name-or-id>
Deletes the human from the workspace. Fails if the human is currently connected.
List humans
pnpm skynet human list --workspace <name-or-id>
Chat (Human Only)
Do NOT run this command yourself. pnpm skynet chat launches an interactive TUI for humans to join the workspace. When you need a human to join, tell them to run this command in a separate terminal.
pnpm skynet chat [--name <human-name>] --workspace <name-or-id>
--name (optional): Human name to join as (skips selection prompt)- If only one human is registered, it is auto-selected.
Doctor
Check system prerequisites
pnpm skynet doctor
Runs diagnostic checks for Node.js version, pnpm, git, agent CLIs (claude, gemini, codex), workspace status, and port availability. Use this to troubleshoot environment issues.
Status
Check workspace status
pnpm skynet status --workspace <name-or-id>
Shows all registered agents and humans with their id, name, role, persona, and online status.
Typical Workflow
- Build:
pnpm install && pnpm build
- Create a workspace:
pnpm skynet workspace new --name my-project
- Start the workspace:
pnpm skynet workspace start my-project -d
- Create agents:
pnpm skynet agent new --workspace my-project --name backend --type claude-code --role "backend engineer"
- Start the agent:
pnpm skynet agent start backend --workspace my-project
- Create a human:
pnpm skynet human new --workspace my-project --name alice
- Human joins chat (tell them to run):
pnpm skynet chat --workspace my-project --name alice
- Check status:
pnpm skynet status --workspace my-project
- Stop when done:
pnpm skynet agent stop backend --workspace my-project && pnpm skynet workspace stop my-project
Logs
All runtime logs are written to ~/.skynet/<workspace-uuid>/logs/:
- Server log:
~/.skynet/<workspace-uuid>/logs/server.log
- Agent logs:
~/.skynet/<workspace-uuid>/logs/<agent-uuid>.log
E2E Testing
Run the skill-marketplace E2E test
pnpm e2e:skill-marketplace [options]
Runs a full end-to-end test of the Skynet workflow using the skill-marketplace scenario. This test:
- Creates a workspace with PM, backend, and frontend agents (all
claude-code) and a human
- Starts all agents as daemons
- Uses pipe mode to simulate the human sending the initial project brief to PM
- Monitors agent collaboration and tracks progress through 5 phases
- Verifies agents produce deliverables in the working directory
- Cleans up all resources
Options:
| Flag | Default | Description |
|---|
--timeout <seconds> | 1800 (30 min) | Overall timeout |
--workdir <path> | /tmp/skynet-e2e-marketplace | Agent working directory |
--workspace <name> | e2e-skill-marketplace | Workspace name |
--skip-setup | false | Reuse existing workspace (skip creation) |
--skip-cleanup | false | Keep workspace running after test |
Examples:
pnpm e2e:skill-marketplace
pnpm e2e:skill-marketplace --timeout 3600 --workdir /tmp/my-test
pnpm e2e:skill-marketplace --skip-setup --workspace e2e-skill-marketplace
pnpm e2e:skill-marketplace --skip-cleanup
Note: This test uses real claude-code agents and incurs API costs. Ensure your environment has the necessary API keys configured.
Tips
- CRITICAL: When deleting workspaces, agents, or humans, you MUST always pass
--force. Without --force, the command enters an interactive confirmation prompt that will hang and block the agent indefinitely.
- Run
pnpm skynet status to see who is currently connected.
- Each workspace stores its data in
~/.skynet/<workspace-uuid>/data.db.
- The workspace server exposes a REST API at
http://<host>:<port>/api/ for programmatic access.
