[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M71R5EY991CDHH4YWC4XRM7P":3,"skill-same:01M71R5EY991CDHH4YWC4XRM7P":74},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":43,"linkOnly":44,"markdownContent":45,"markdownBody":46,"frontMatter":47,"refName":48,"commitSha":49,"skillDirectory":50,"forksCount":51,"repositoryHtmlUrl":52,"repositoryHomepageUrl":6,"ownerHtmlUrl":53,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":54,"install":55,"resources":67},"01M71R5EY991CDHH4YWC4XRM7P","monkeybot",null,"Entry point for monkeybot — install the CLI from PyPI if needed, then scaffold, configure, validate, and chat with an agent. Use when a user installs this skill via `npx skills add human-plus-machine\u002Fmonkeybot --skill monkeybot`, sets up monkeybot for the first time, installs the monkeybot CLI, scaffolds monkeybot_config\u002F, explains monkeybot.yaml options, or smoke-tests from the terminal.","human-plus-machine\u002Fmonkeybot","human-plus-machine","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F280167390?v=4","01M71R5340DFF1C4XV5B369MPN","human plus machine","01M71R5357ZTPM4CKBNH5XNSFY",3,"MIT","https:\u002F\u002Fgithub.com\u002Fhuman-plus-machine\u002Fmonkeybot\u002Fblob\u002Fdevelop\u002Fcli\u002Fskills\u002Fmonkeybot\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[5,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42],"install","use","pypi","npx","tests","machine","for","smoke","point","add","config","terminal","options","human","cli","configure","when","up","time","2026-11-10 13:02:02",false,"---\nname: monkeybot\ndescription: Entry point for monkeybot — install the CLI from PyPI if needed, then scaffold, configure, validate, and chat with an agent. Use when a user installs this skill via `npx skills add human-plus-machine\u002Fmonkeybot --skill monkeybot`, sets up monkeybot for the first time, installs the monkeybot CLI, scaffolds monkeybot_config\u002F, explains monkeybot.yaml options, or smoke-tests from the terminal.\n---\n\n# monkeybot\n\nGuide a new user from **only this skill** to a working agent. Installing the skill (`npx skills add …`) gives you these instructions — it does **not** install the monkeybot CLI. **Always run Tier 0 first** unless you already know the toolchain is ready. Day-1 users do **not** need to clone the monkeybot repo.\n\n## Tier 0 — Bootstrap toolchain\n\nRun these checks before anything else. Do not skip to Tier 1 until the CLI probe succeeds.\n\n### 0. Detect what's already installed\n\n```bash\ncommand -v monkeybot && monkeybot --help\n```\n\nIf that works, skip to Tier 1.\n\n### 1. Install prerequisites (only if missing)\n\n| Tool | Check | Install |\n|---|---|---|\n| **uv** | `command -v uv` | `curl -LsSf https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.sh \\| sh` then `export PATH=\"$HOME\u002F.local\u002Fbin:$PATH\"` |\n| **Python 3.11+** | `uv python find 3.11` or `python3 --version` | `uv python install 3.12` |\n\nTell the user what you're installing and why. On macOS\u002FLinux you can run these yourself; on Windows, point them at [uv](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002F).\n\n### 2. Install the global CLI\n\n```bash\n# browser-harness pins Pillow 12. Core 3.12 needs Pillow 13, and\n# `uv tool install` ignores the package override unless this file is passed.\n# Without it the resolver stays on core 3.10.0.\nprintf 'pillow>=13\\n' > \u002Ftmp\u002Fmonkeybot-overrides.txt\nuv tool install --overrides \u002Ftmp\u002Fmonkeybot-overrides.txt monkeybot-cli\nmonkeybot --help\n```\n\nUpgrade later with `uv tool install --reinstall --overrides \u002Ftmp\u002Fmonkeybot-overrides.txt monkeybot-cli`.\n\n**Do not** tell day-1 users to clone `human-plus-machine\u002Fmonkeybot` unless they are contributing to the harness itself (see Contributing below).\n\n### 3. Skill-only users\n\nIf the user arrived via skills.sh:\n\n```bash\nnpx skills add human-plus-machine\u002Fmonkeybot --skill monkeybot\n```\n\n…they have **this skill only**. Walk them through Tier 0: install `uv` → `uv tool install --overrides \u002Ftmp\u002Fmonkeybot-overrides.txt monkeybot-cli` (write `pillow>=13` into that file first) → verify `monkeybot --help`. Then continue to Tier 1.\n\n## How config works (tell the user this first)\n\n- **CLI scaffolds, YAML customizes, then validate.** `monkeybot new` copies packaged defaults from the `monkeybot-cli` package (`monkeybot_cli.scaffold_defaults`) and sets `model.provider` \u002F `model.name`. After that, customization happens by editing `monkeybot_config\u002Fmonkeybot.yaml` and `.env`, then re-running `monkeybot validate --json`.\n- **Three config surfaces:**\n  - `monkeybot_config\u002Fmonkeybot.yaml` — non-secret settings (model, paths, gateway, behavior).\n  - `.env` — secrets and machine-local paths (API keys, GCP project, DB URL).\n  - sidecars: `monkeybot_config\u002FAGENT.md` (system prompt), `mcp.json` (MCP servers), `command_allowlist.yaml`.\n- **Precedence — important:** environment variables and `.env` win over `monkeybot.yaml` except `model.*` (provider, name, sampling, context window, summarization model, max turns, cache retention), which is YAML-only. If a user edits YAML but nothing changes, suspect a stale `.env` shadowing it (the YAML→env mapping lives in `runtime_env.py:ENV_MAP`).\n- **Defaults are fine on day one.** Most first-time users only touch `model`, `.env` credentials, and `AGENT.md`.\n\n## Running CLI commands\n\nAfter Tier 0, every command below uses `monkeybot` on PATH.\n\n## Tier 1 — Get it talking\n\nThe minimum path to one successful chat turn. Do this for every new user.\n\n### 1. Quick interview\n\nAsk (or infer):\n\n- Bot purpose \u002F name → goes in `AGENT.md`\n- Provider + model (see provider table below)\n- Optional features (postgres, sandbox, observability, …) → `--with` or interactive menus\n\n### 2. Scaffold\n\n```bash\nmonkeybot new --dest \u002Fpath\u002Fto\u002Fbot --provider openai --yes\n# Interactive (menus for provider + extras):\n# monkeybot new --dest \u002Fpath\u002Fto\u002Fbot\n# Non-interactive extras:\n# monkeybot new --dest \u002Fpath\u002Fto\u002Fbot --provider openai --with postgres,sandbox --yes\n```\n\nCreates `monkeybot_config\u002F`, read-only `skills\u002F`, writable `workspace\u002F`,\n`memory\u002F`, `.env.example`, a Dockerfile, and an agent `pyproject.toml`.\nUse `--force` only when overwriting is explicitly requested.\n\nThen:\n\n```bash\ncd \u002Fpath\u002Fto\u002Fbot\nuv sync\n```\n\n### 3. Credentials + system prompt\n\n- Copy `.env.example` → `.env` and fill in the keys for your provider (table below).\n- Edit `monkeybot_config\u002FAGENT.md` with the bot's system prompt. **Never put secrets in YAML.**\n\n### Provider table\n\n| YAML `model.provider` | `.env` credentials (any one) | Add to agent `pyproject.toml` deps, then `uv sync` |\n|---|---|---|\n| `gemini` (or `vertex`) | `GEMINI_API_KEY`, or `GOOGLE_APPLICATION_CREDENTIALS`, or `GCP_PROJECT_ID` \u002F `GOOGLE_CLOUD_PROJECT` (ADC) | `monkeybot[gemini]` |\n| `openai` | `OPENAI_API_KEY` | `monkeybot[openai]` |\n| `anthropic` | `ANTHROPIC_API_KEY` | `monkeybot[claude]` |\n| `vertex-claude` | `GCP_PROJECT_ID` \u002F `GOOGLE_CLOUD_PROJECT` \u002F `ANTHROPIC_VERTEX_PROJECT_ID` (ADC) | `monkeybot[vertex-claude]` |\n| `aws_bedrock` | `AWS_ACCESS_KEY_ID` \u002F `AWS_PROFILE` + `AWS_REGION` | `monkeybot[bedrock]` |\n| `huggingface` | `HF_TOKEN` (or `HUGGINGFACE_API_KEY`) | `monkeybot[huggingface]` |\n| `ollama-cloud` | `OLLAMA_API_KEY` | `monkeybot[ollama]` |\n| `ollama-local` | None required — `OLLAMA_BASE_URL` (default `http:\u002F\u002Flocalhost:11434`). Requests send `keep_alive` 24h so prefix KV cache survives idle. | `monkeybot[ollama]` |\n| `ollama` | Legacy auto-route (key + blank URL = cloud; explicit URL wins) | `monkeybot[ollama]` |\n\n**Agent-first dependencies.** The CLI is thin — it does **not** install provider\u002Fstorage extras globally. `monkeybot new` scaffolds a `pyproject.toml` with the selected provider (and any `--with` extras). Run plain `uv sync` in the agent directory. `monkeybot run` \u002F `chat` spawn the gateway from that project's interpreter (`.venv\u002Fbin\u002Fpython`, else `uv run python`), and `doctor` checks extras in that same interpreter. For a config-only tree (just `monkeybot_config\u002F`, no `pyproject.toml`) the gateway uses the CLI's interpreter when it already has MonkeyBot 3.x (and MemPalace if memory is on). If memory is enabled and that interpreter cannot import MemPalace, `run` \u002F `chat` provision a cached CLI-managed venv under `~\u002F.cache\u002Fmonkeybot\u002Fruntimes\u002F` holding `monkeybot[memory]` pinned to the running core (never rewrites a `pyproject.toml`). `doctor` reuses that cache when it is already present. Otherwise extras must be installed in the CLI env (`uv tool install --reinstall --overrides \u002Ftmp\u002Fmonkeybot-overrides.txt --with 'monkeybot[\u003Cextra>]' monkeybot-cli`, with `pillow>=13` in that file). A bare `uv tool install` resolves core 3.10.0.\n\n`doctor` is the source of truth for credentials and extras — when in doubt, run it and read the `remediation` field (add `monkeybot[\u003Cextra>]` to agent deps + `uv sync`).\n\n### 4. Validate (loop until clean)\n\n```bash\nmonkeybot validate --json --cwd \u002Fpath\u002Fto\u002Fbot\n```\n\n- Exit `0` + `\"ok\": true` → proceed.\n- On failure: read `checks[]` by stable `id`, apply `remediation`, re-run.\n\n### 5. Doctor\n\n```bash\nmonkeybot doctor --json --cwd \u002Fpath\u002Fto\u002Fbot\n```\n\nConfirms Python version, provider extra installed, credentials present, and port free.\n\n### 6. Smoke test\n\n```bash\nmonkeybot chat --cwd \u002Fpath\u002Fto\u002Fbot\n```\n\nOr split terminals: `monkeybot run --cwd \u002Fpath\u002Fto\u002Fbot` then `monkeybot chat --attach --cwd \u002Fpath\u002Fto\u002Fbot`.\n\nOne successful turn confirms Tier 1.\n\n## Tier 2 — Customize (on demand)\n\nOnly reach for these when the interview surfaces a need. Each maps to a `monkeybot.yaml` section. **For purpose, defaults, examples, and the `validate`\u002F`doctor` check id of every option, read [`references\u002Fconfig-sections.md`](references\u002Fconfig-sections.md).** Don't inline that reference here.\n\nDecision → config map:\n\n| User says… | Change |\n|---|---|\n| \"Run many subagents in parallel\" | `paths.db_url` → Postgres (SQLite locks under concurrency) |\n| \"I have a custom web UI\" | `gateway.cors_allow_origins` |\n| \"Search the web\" | `web_search.backend` + `.env` keys (Tavily\u002FFirecrawl) |\n| \"Run untrusted code\" | `sandbox.enabled` + `SANDBOX_API_KEY` |\n| \"Use specialist agents\" | `subagents.personas` + `monkeybot_config\u002Fagents\u002F*.md` |\n| \"Connect external tools\" | `mcp.json` (`mcpServers` object), then `validate --check-mcp` |\n| \"Control cost \u002F context size\" | `model.*` |\n| \"Restrict dangerous commands\" | `tools.denied_patterns`, `command_allowlist.yaml` |\n| \"Multiple environments\" | top-level `includes:` fragments |\n\n**Subagents (`task` tool):** without `subagent_type`, share the parent `AGENT.md`. With a persona, use that persona's `agent_md`. Relative paths resolve from the bot project root, not `workspace\u002F`. Specialize via `task` \u002F `context` or named personas. For parallel `task` fan-out, prefer Postgres: add `monkeybot[postgres]` to the **agent** `pyproject.toml` dependencies, run `uv sync`, then set `DB_URL=postgresql:\u002F\u002F...` in `.env`.\n\n**Observability** is mostly env + add `monkeybot[observability]` to agent deps + `uv sync` + an OTel collector — not `monkeybot.yaml`. See `docs\u002Fobservability-runbook.md`.\n\n## Contributing \u002F developing the harness\n\nOnly if the user is changing monkeybot itself (not creating an agent):\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fhuman-plus-machine\u002Fmonkeybot.git\ncd monkeybot && uv sync\ncd cli && uv sync\nuv tool install --editable . --overrides src\u002Fmonkeybot_cli\u002Foverrides.txt\n```\n\n## Rules\n\n- **Tier 0 before Tier 1** — verify or install the global CLI before scaffolding a bot.\n- **CLI owns scaffolding** — do not duplicate template files manually.\n- **Secrets in `.env` only** — never commit API keys to `monkeybot.yaml`.\n- **Validate after every edit** — re-run `validate --json` whenever you change config.\n- **Parse JSON** — key off `checks[].id`, not free-form messages.\n- **HTTP\u002FSSE for chat** — the CLI talks to the gateway process; do not import harness gateway code.\n- **No clone for day-1 users** — clone is for harness contributors only.\n\n## Command reference\n\n| Command | Purpose |\n|---------|---------|\n| `new` | Scaffold `monkeybot_config\u002F`, `workspace\u002F`, `memory\u002F`, `skills\u002F`, `pyproject.toml`, `.env.example` |\n| `refresh` | Additive update of packaged YAML defaults on an existing agent (keeps AGENT.md, mcp.json, model) |\n| `validate` | Config + paths + MCP shape (`--check-mcp` for network) |\n| `doctor` | Python, provider extra, credentials, port |\n| `run` | Start SSE gateway subprocess |\n| `chat` | Interactive terminal client (SSE) |\n| `talk` | Realtime WebSocket client (audio\u002Ftext) |\n","# monkeybot\n\nGuide a new user from **only this skill** to a working agent. Installing the skill (`npx skills add …`) gives you these instructions — it does **not** install the monkeybot CLI. **Always run Tier 0 first** unless you already know the toolchain is ready. Day-1 users do **not** need to clone the monkeybot repo.\n\n## Tier 0 — Bootstrap toolchain\n\nRun these checks before anything else. Do not skip to Tier 1 until the CLI probe succeeds.\n\n### 0. Detect what's already installed\n\n```bash\ncommand -v monkeybot && monkeybot --help\n```\n\nIf that works, skip to Tier 1.\n\n### 1. Install prerequisites (only if missing)\n\n| Tool | Check | Install |\n|---|---|---|\n| **uv** | `command -v uv` | `curl -LsSf https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.sh \\| sh` then `export PATH=\"$HOME\u002F.local\u002Fbin:$PATH\"` |\n| **Python 3.11+** | `uv python find 3.11` or `python3 --version` | `uv python install 3.12` |\n\nTell the user what you're installing and why. On macOS\u002FLinux you can run these yourself; on Windows, point them at [uv](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002F).\n\n### 2. Install the global CLI\n\n```bash\n# browser-harness pins Pillow 12. Core 3.12 needs Pillow 13, and\n# `uv tool install` ignores the package override unless this file is passed.\n# Without it the resolver stays on core 3.10.0.\nprintf 'pillow>=13\\n' > \u002Ftmp\u002Fmonkeybot-overrides.txt\nuv tool install --overrides \u002Ftmp\u002Fmonkeybot-overrides.txt monkeybot-cli\nmonkeybot --help\n```\n\nUpgrade later with `uv tool install --reinstall --overrides \u002Ftmp\u002Fmonkeybot-overrides.txt monkeybot-cli`.\n\n**Do not** tell day-1 users to clone `human-plus-machine\u002Fmonkeybot` unless they are contributing to the harness itself (see Contributing below).\n\n### 3. Skill-only users\n\nIf the user arrived via skills.sh:\n\n```bash\nnpx skills add human-plus-machine\u002Fmonkeybot --skill monkeybot\n```\n\n…they have **this skill only**. Walk them through Tier 0: install `uv` → `uv tool install --overrides \u002Ftmp\u002Fmonkeybot-overrides.txt monkeybot-cli` (write `pillow>=13` into that file first) → verify `monkeybot --help`. Then continue to Tier 1.\n\n## How config works (tell the user this first)\n\n- **CLI scaffolds, YAML customizes, then validate.** `monkeybot new` copies packaged defaults from the `monkeybot-cli` package (`monkeybot_cli.scaffold_defaults`) and sets `model.provider` \u002F `model.name`. After that, customization happens by editing `monkeybot_config\u002Fmonkeybot.yaml` and `.env`, then re-running `monkeybot validate --json`.\n- **Three config surfaces:**\n  - `monkeybot_config\u002Fmonkeybot.yaml` — non-secret settings (model, paths, gateway, behavior).\n  - `.env` — secrets and machine-local paths (API keys, GCP project, DB URL).\n  - sidecars: `monkeybot_config\u002FAGENT.md` (system prompt), `mcp.json` (MCP servers), `command_allowlist.yaml`.\n- **Precedence — important:** environment variables and `.env` win over `monkeybot.yaml` except `model.*` (provider, name, sampling, context window, summarization model, max turns, cache retention), which is YAML-only. If a user edits YAML but nothing changes, suspect a stale `.env` shadowing it (the YAML→env mapping lives in `runtime_env.py:ENV_MAP`).\n- **Defaults are fine on day one.** Most first-time users only touch `model`, `.env` credentials, and `AGENT.md`.\n\n## Running CLI commands\n\nAfter Tier 0, every command below uses `monkeybot` on PATH.\n\n## Tier 1 — Get it talking\n\nThe minimum path to one successful chat turn. Do this for every new user.\n\n### 1. Quick interview\n\nAsk (or infer):\n\n- Bot purpose \u002F name → goes in `AGENT.md`\n- Provider + model (see provider table below)\n- Optional features (postgres, sandbox, observability, …) → `--with` or interactive menus\n\n### 2. Scaffold\n\n```bash\nmonkeybot new --dest \u002Fpath\u002Fto\u002Fbot --provider openai --yes\n# Interactive (menus for provider + extras):\n# monkeybot new --dest \u002Fpath\u002Fto\u002Fbot\n# Non-interactive extras:\n# monkeybot new --dest \u002Fpath\u002Fto\u002Fbot --provider openai --with postgres,sandbox --yes\n```\n\nCreates `monkeybot_config\u002F`, read-only `skills\u002F`, writable `workspace\u002F`,\n`memory\u002F`, `.env.example`, a Dockerfile, and an agent `pyproject.toml`.\nUse `--force` only when overwriting is explicitly requested.\n\nThen:\n\n```bash\ncd \u002Fpath\u002Fto\u002Fbot\nuv sync\n```\n\n### 3. Credentials + system prompt\n\n- Copy `.env.example` → `.env` and fill in the keys for your provider (table below).\n- Edit `monkeybot_config\u002FAGENT.md` with the bot's system prompt. **Never put secrets in YAML.**\n\n### Provider table\n\n| YAML `model.provider` | `.env` credentials (any one) | Add to agent `pyproject.toml` deps, then `uv sync` |\n|---|---|---|\n| `gemini` (or `vertex`) | `GEMINI_API_KEY`, or `GOOGLE_APPLICATION_CREDENTIALS`, or `GCP_PROJECT_ID` \u002F `GOOGLE_CLOUD_PROJECT` (ADC) | `monkeybot[gemini]` |\n| `openai` | `OPENAI_API_KEY` | `monkeybot[openai]` |\n| `anthropic` | `ANTHROPIC_API_KEY` | `monkeybot[claude]` |\n| `vertex-claude` | `GCP_PROJECT_ID` \u002F `GOOGLE_CLOUD_PROJECT` \u002F `ANTHROPIC_VERTEX_PROJECT_ID` (ADC) | `monkeybot[vertex-claude]` |\n| `aws_bedrock` | `AWS_ACCESS_KEY_ID` \u002F `AWS_PROFILE` + `AWS_REGION` | `monkeybot[bedrock]` |\n| `huggingface` | `HF_TOKEN` (or `HUGGINGFACE_API_KEY`) | `monkeybot[huggingface]` |\n| `ollama-cloud` | `OLLAMA_API_KEY` | `monkeybot[ollama]` |\n| `ollama-local` | None required — `OLLAMA_BASE_URL` (default `http:\u002F\u002Flocalhost:11434`). Requests send `keep_alive` 24h so prefix KV cache survives idle. | `monkeybot[ollama]` |\n| `ollama` | Legacy auto-route (key + blank URL = cloud; explicit URL wins) | `monkeybot[ollama]` |\n\n**Agent-first dependencies.** The CLI is thin — it does **not** install provider\u002Fstorage extras globally. `monkeybot new` scaffolds a `pyproject.toml` with the selected provider (and any `--with` extras). Run plain `uv sync` in the agent directory. `monkeybot run` \u002F `chat` spawn the gateway from that project's interpreter (`.venv\u002Fbin\u002Fpython`, else `uv run python`), and `doctor` checks extras in that same interpreter. For a config-only tree (just `monkeybot_config\u002F`, no `pyproject.toml`) the gateway uses the CLI's interpreter when it already has MonkeyBot 3.x (and MemPalace if memory is on). If memory is enabled and that interpreter cannot import MemPalace, `run` \u002F `chat` provision a cached CLI-managed venv under `~\u002F.cache\u002Fmonkeybot\u002Fruntimes\u002F` holding `monkeybot[memory]` pinned to the running core (never rewrites a `pyproject.toml`). `doctor` reuses that cache when it is already present. Otherwise extras must be installed in the CLI env (`uv tool install --reinstall --overrides \u002Ftmp\u002Fmonkeybot-overrides.txt --with 'monkeybot[\u003Cextra>]' monkeybot-cli`, with `pillow>=13` in that file). A bare `uv tool install` resolves core 3.10.0.\n\n`doctor` is the source of truth for credentials and extras — when in doubt, run it and read the `remediation` field (add `monkeybot[\u003Cextra>]` to agent deps + `uv sync`).\n\n### 4. Validate (loop until clean)\n\n```bash\nmonkeybot validate --json --cwd \u002Fpath\u002Fto\u002Fbot\n```\n\n- Exit `0` + `\"ok\": true` → proceed.\n- On failure: read `checks[]` by stable `id`, apply `remediation`, re-run.\n\n### 5. Doctor\n\n```bash\nmonkeybot doctor --json --cwd \u002Fpath\u002Fto\u002Fbot\n```\n\nConfirms Python version, provider extra installed, credentials present, and port free.\n\n### 6. Smoke test\n\n```bash\nmonkeybot chat --cwd \u002Fpath\u002Fto\u002Fbot\n```\n\nOr split terminals: `monkeybot run --cwd \u002Fpath\u002Fto\u002Fbot` then `monkeybot chat --attach --cwd \u002Fpath\u002Fto\u002Fbot`.\n\nOne successful turn confirms Tier 1.\n\n## Tier 2 — Customize (on demand)\n\nOnly reach for these when the interview surfaces a need. Each maps to a `monkeybot.yaml` section. **For purpose, defaults, examples, and the `validate`\u002F`doctor` check id of every option, read [`references\u002Fconfig-sections.md`](references\u002Fconfig-sections.md).** Don't inline that reference here.\n\nDecision → config map:\n\n| User says… | Change |\n|---|---|\n| \"Run many subagents in parallel\" | `paths.db_url` → Postgres (SQLite locks under concurrency) |\n| \"I have a custom web UI\" | `gateway.cors_allow_origins` |\n| \"Search the web\" | `web_search.backend` + `.env` keys (Tavily\u002FFirecrawl) |\n| \"Run untrusted code\" | `sandbox.enabled` + `SANDBOX_API_KEY` |\n| \"Use specialist agents\" | `subagents.personas` + `monkeybot_config\u002Fagents\u002F*.md` |\n| \"Connect external tools\" | `mcp.json` (`mcpServers` object), then `validate --check-mcp` |\n| \"Control cost \u002F context size\" | `model.*` |\n| \"Restrict dangerous commands\" | `tools.denied_patterns`, `command_allowlist.yaml` |\n| \"Multiple environments\" | top-level `includes:` fragments |\n\n**Subagents (`task` tool):** without `subagent_type`, share the parent `AGENT.md`. With a persona, use that persona's `agent_md`. Relative paths resolve from the bot project root, not `workspace\u002F`. Specialize via `task` \u002F `context` or named personas. For parallel `task` fan-out, prefer Postgres: add `monkeybot[postgres]` to the **agent** `pyproject.toml` dependencies, run `uv sync`, then set `DB_URL=postgresql:\u002F\u002F...` in `.env`.\n\n**Observability** is mostly env + add `monkeybot[observability]` to agent deps + `uv sync` + an OTel collector — not `monkeybot.yaml`. See `docs\u002Fobservability-runbook.md`.\n\n## Contributing \u002F developing the harness\n\nOnly if the user is changing monkeybot itself (not creating an agent):\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fhuman-plus-machine\u002Fmonkeybot.git\ncd monkeybot && uv sync\ncd cli && uv sync\nuv tool install --editable . --overrides src\u002Fmonkeybot_cli\u002Foverrides.txt\n```\n\n## Rules\n\n- **Tier 0 before Tier 1** — verify or install the global CLI before scaffolding a bot.\n- **CLI owns scaffolding** — do not duplicate template files manually.\n- **Secrets in `.env` only** — never commit API keys to `monkeybot.yaml`.\n- **Validate after every edit** — re-run `validate --json` whenever you change config.\n- **Parse JSON** — key off `checks[].id`, not free-form messages.\n- **HTTP\u002FSSE for chat** — the CLI talks to the gateway process; do not import harness gateway code.\n- **No clone for day-1 users** — clone is for harness contributors only.\n\n## Command reference\n\n| Command | Purpose |\n|---------|---------|\n| `new` | Scaffold `monkeybot_config\u002F`, `workspace\u002F`, `memory\u002F`, `skills\u002F`, `pyproject.toml`, `.env.example` |\n| `refresh` | Additive update of packaged YAML defaults on an existing agent (keeps AGENT.md, mcp.json, model) |\n| `validate` | Config + paths + MCP shape (`--check-mcp` for network) |\n| `doctor` | Python, provider extra, credentials, port |\n| `run` | Start SSE gateway subprocess |\n| `chat` | Interactive terminal client (SSE) |\n| `talk` | Realtime WebSocket client (audio\u002Ftext) |\n",{"name":5,"description":7},"develop","3f4ce06b117cf078c4edf4cd8041134d301404ac","cli\u002Fskills\u002Fmonkeybot",2,"https:\u002F\u002Fgithub.com\u002Fhuman-plus-machine\u002Fmonkeybot","https:\u002F\u002Fgithub.com\u002Fhuman-plus-machine","2026-11-12 05:23:37",{"source":8,"skillName":5,"commands":56,"prompt":65,"zipAvailable":66},[57,59,62],{"tool":27,"command":58},"npx skills add human-plus-machine\u002Fmonkeybot --skill monkeybot",{"tool":60,"command":61},"bunx","bunx skills add human-plus-machine\u002Fmonkeybot --skill monkeybot",{"tool":63,"command":64},"pnpm","pnpm dlx skills add human-plus-machine\u002Fmonkeybot --skill monkeybot","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fhuman-plus-machine\u002Fmonkeybot\u002Fblob\u002Fdevelop\u002Fcli\u002Fskills\u002Fmonkeybot\u002FSKILL.md",true,[68],{"path":69,"resourceType":70,"resourceTypeDesc":71,"sizeBytes":72,"sourceHtmlUrl":73},"references\u002Fconfig-sections.md","REFERENCE","参考文档",10129,"https:\u002F\u002Fgithub.com\u002Fhuman-plus-machine\u002Fmonkeybot\u002Fblob\u002Fdevelop\u002Fcli\u002Fskills\u002Fmonkeybot\u002Freferences\u002Fconfig-sections.md",[75,88,94,107,114,140],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":82,"publishedAt":43},"01M71R6545453TAC4Y71JM2362","browser","Smoke-test browser skill fixture.","https:\u002F\u002Fgithub.com\u002Fhuman-plus-machine\u002Fmonkeybot\u002Fblob\u002Fdevelop\u002Fregression\u002Ft4\u002Fagent\u002Fskills\u002Fbrowser\u002FSKILL.md",[81],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[77,83,84,85,86,31,87],"skill fixture","fixture","test","test browser","Browser Skill",{"skillNo":89,"name":90,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":43},"01M71R63F3CPF727VZAXTPWJNW","plain","https:\u002F\u002Fgithub.com\u002Fhuman-plus-machine\u002Fmonkeybot\u002Fblob\u002Fdevelop\u002Fregression\u002Ffixtures\u002Fskills\u002Fplain\u002FSKILL.md",[],[90],{"skillNo":95,"name":96,"nameZh":6,"description":97,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":100,"publishedAt":43},"01M71R60VVZE567ZPHWTFHM58S","diagnostics","Inspect a failing run and report the first error.","https:\u002F\u002Fgithub.com\u002Fhuman-plus-machine\u002Fmonkeybot\u002Fblob\u002Fdevelop\u002Fregression\u002Ffixtures\u002Fskills\u002Fdiagnostics\u002FSKILL.md",[],[96,101,102,103,104,105,106],"error","first","run","inspect","report","failing",{"skillNo":108,"name":109,"nameZh":6,"description":110,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":111,"categories":112,"keywords":113,"publishedAt":43},"01M71R5Z5JTN6H8NSDE755H9TB","nested","Nested skills must not be discovered.","https:\u002F\u002Fgithub.com\u002Fhuman-plus-machine\u002Fmonkeybot\u002Fblob\u002Fdevelop\u002Fregression\u002Ffixtures\u002Fskills\u002Fa\u002Fnested\u002FSKILL.md",[],[109],{"skillNo":115,"name":116,"nameZh":6,"description":117,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":118,"categories":119,"keywords":123,"publishedAt":43},"01M71R5XACZGNRRQ7DH1CA170Y","image-generator","Generate images with Gemini image models (Nano Banana Pro) and display them in chat.","https:\u002F\u002Fgithub.com\u002Fhuman-plus-machine\u002Fmonkeybot\u002Fblob\u002Fdevelop\u002Fexamples\u002Fskills\u002Fimage-generator\u002FSKILL.md",[120],{"categoryNo":121,"categoryName":122,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000016","图像与多媒体",[124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139],"image","generator","image generator","pro","banana","nano banana","images","models","gemini","nano banana pro","nano","display","chat","with","gemini image","generate",{"skillNo":141,"name":96,"nameZh":6,"description":142,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":143,"categories":144,"keywords":145,"publishedAt":43},"01M71R5VJ9QHZT480VSWGP6B37","Run deployment health checks (env, runtime, computation) and return JSON status.","https:\u002F\u002Fgithub.com\u002Fhuman-plus-machine\u002Fmonkeybot\u002Fblob\u002Fdevelop\u002Fexamples\u002Fskills\u002Fdiagnostics\u002FSKILL.md",[],[96,146,147,103,148,149,150,151,152],"health","runtime","computation","json","deployment","status","env"]