skynet-dev

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:

1. Specify a custom working directory (e.g., a project repo path)
2. 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

1. Build: pnpm install && pnpm build
2. Create a workspace: pnpm skynet workspace new --name my-project
3. Start the workspace: pnpm skynet workspace start my-project -d
4. Create agents: pnpm skynet agent new --workspace my-project --name backend --type claude-code --role "backend engineer"
5. Start the agent: pnpm skynet agent start backend --workspace my-project
6. Create a human: pnpm skynet human new --workspace my-project --name alice
7. Human joins chat (tell them to run): pnpm skynet chat --workspace my-project --name alice
8. Check status: pnpm skynet status --workspace my-project
9. 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:

1. Creates a workspace with PM, backend, and frontend agents (all claude-code) and a human
2. Starts all agents as daemons
3. Uses pipe mode to simulate the human sending the initial project brief to PM
4. Monitors agent collaboration and tracks progress through 5 phases
5. Verifies agents produce deliverables in the working directory
6. 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:

# Run full test with defaults
pnpm e2e:skill-marketplace

# Run with custom timeout and workdir
pnpm e2e:skill-marketplace --timeout 3600 --workdir /tmp/my-test

# Resume a test (skip setup, reuse existing workspace)
pnpm e2e:skill-marketplace --skip-setup --workspace e2e-skill-marketplace

# Keep workspace running after test for manual inspection
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.