Update to MarcoPolo

{
  "name": "using-marcopolo-workspace",
  "description": "Orientation for the MarcoPolo remote workspace, what it is, how `/workspace` is laid out, when to use the product MCP data tools versus `workspace_shell`, and how the `connection` CLI fits in. Use this skill whenever MarcoPolo, the marcopolo MCP server, `workspace_shell`, `/workspace`, connections, or `connection` CLI commands come up. Read this first when entering a MarcoPolo session, before reaching for a more specific skill.",
  "included_files": [],
  "skill_md_contents": "---\nname: using-marcopolo-workspace\ndescription: Orientation for the MarcoPolo remote workspace, what it is, how `/workspace` is laid out, when to use the product MCP data tools versus `workspace_shell`, and how the `connection` CLI fits in. Use this skill whenever MarcoPolo, the marcopolo MCP server, `workspace_shell`, `/workspace`, connections, or `connection` CLI commands come up. Read this first when entering a MarcoPolo session, before reaching for a more specific skill.\n---\n\n# Using the MarcoPolo workspace\n\nMarcoPolo is a persistent remote Linux workspace at `/workspace` for working\nwith company data, building dashboards, scheduling jobs, and keeping a durable\ncollection of queries, scripts, and artifacts.\n\n## Two execution surfaces\n\nTwo execution surfaces coexist in a MarcoPolo session:\n\n- `workspace_shell` for all agent-side work: query authoring, analytics, DuckDB\n  joins, workspace files, scripts, git, and cron inside `/workspace`.\n- Product MCP data tools (`connections_list`, `data_query`) for generated code\n  that re-queries live data at view or load time — Remote Artifacts, external\n  web apps, scheduled scripts.\n\nFor all agent analytics, use `workspace_shell`. Reserve `data_query` for\nprogrammatic interfaces, not for the agent's own data exploration.\n\n## Session capability detection\n\nCheck which tools are available in the current session before choosing a path:\n\n- Sessions with `connections_list` and `data_query` (Claude, Cursor, etc.):\n  - Agent analytics → always use `workspace_shell`\n  - Programmatic interfaces (web apps, scripts, dashboards) → use `data_query`\n- Sessions with only `workspace_shell` (ChatGPT, older sessions):\n  - Agent analytics → use `workspace_shell`\n  - Generated artifact code → use bounded `workspace_shell(\"connection query <name> --file <file> --sample-rows <n> --json\")`, noting in the code that it can be upgraded to `data_query` if the session gains that tool\n\n`workspace_shell` is the primary analytics tool in every session. `data_query`\nis an addition for programmatic interfaces, not a replacement for agent work.\n\nWhen using `workspace_shell` for queries, treat results as CLI envelopes:\n\n- rows from `data`, otherwise `preview`\n- `row_count` from `row_count`, otherwise `len(rows)`\n- `run_id` if present\n- `relation_name` if present\n\nIf `row_count` exceeds the length of `preview`, the preview is truncated —\nuse a higher `--sample-rows` value to get more rows, or `--sample-rows -1`\nto get all rows in the payload.\n\n## Two shell environments\n\nTwo shell environments coexist in this session:\n\n- Your built-in shell and filesystem tools act on the client's own environment.\n- `workspace_shell` runs commands inside the MarcoPolo remote workspace at\n  `/workspace`.\n\nYour built-in tools cannot reach the MarcoPolo workspace. They cannot read or\ncreate files there, run the `connection` CLI or `crontab` that only exist there,\nor see git state inside it. Only `workspace_shell` can.\n\nSo for all MarcoPolo workspace work, such as reading files, writing queries,\nrunning scripts, or inspecting git, use `workspace_shell`. Reach for your\nbuilt-in tools only for things outside MarcoPolo.\n\nUser-uploaded files land in `data/uploads/` inside the MarcoPolo workspace.\n`workspace_shell` reads them, not the built-in tools.\n\n## Common `workspace_shell` operations\n\nTreat `/workspace` like a checked-out repo. Common shapes:\n\n- read files: `workspace_shell(\"cat /workspace/RULES.md\")`\n- list and search: `workspace_shell(\"ls connections/\")`,\n  `workspace_shell(\"rg <pattern> connections/\")`\n- write and edit files: `workspace_shell` with heredocs, `sed`, or other shell\n  tools\n- run scripts: `workspace_shell(\"python scripts/<file>.py\")`\n- inspect git state: `workspace_shell(\"git status\")`,\n  `workspace_shell(\"git diff\")`\n\nRead `RULES.md` and the relevant `workflows/` guide before authoring; use git\nas part of normal work.\n\n## MCP tool families\n\nProduct data tools:\n\n- `connections_list` for connection discovery when available\n- `data_query` for bounded governed query execution when available\n\nWorkspace and ext-app tools:\n\n- `workspace_shell(command, timeout=30)` for remote workspace commands\n- `connection_setup(type, intent_text=None)` for credentialed connection setup\n- `install_demo_connection(demo_connection, display_name=None, intent_text=None)`\n  for hosted demo connections\n\nSome sessions may also expose legacy or host-specific tools. Do not rely on\nthem as the primary dashboard or query path unless a more specific skill tells\nyou to.\n\n## The `connection` CLI is the workspace verb surface\n\nFor full reference see the `using-connection-cli` skill. The shape:\n\n```text\nconnection <verb> [args] --json\n```\n\nCommon verbs: `list`, `add`, `test`, `describe`, `query`, `browse`, `download`,\n`upload`. Always pass `--json` so output is structured.\n\n`connection list --json` returns each connection's `capabilities` array. That\nlist is authoritative. Never call `browse`, `download`, or `upload` on a\nconnection unless that verb appears in its capabilities.\n\n## Workspace layout\n\n```text\n/workspace/\n  README.md                       workspace overview\n  RULES.md                        workspace-wide rules and conventions\n  workflows/                      curated guides for recurring tasks\n    README.md\n    setup-connection.md\n    query-and-analyze-data.md\n    build-dashboard.md\n    setup-automation.md\n  connections/                    one subdirectory per visible connection\n    <name>/\n      README.md\n      RULES.md\n      SYNTAX.md\n      queries/\n      metadata/\n      profile/\n      scratch/\n    DUCKDB/\n  scripts/\n  artifacts/\n  data/\n    uploads/\n    downloads/\n    databases/\n  .dv/\n```\n\nAlways read first before authoring:\n\n- `workspace_shell(\"cat /workspace/RULES.md\")`\n- `workspace_shell(\"cat /workspace/workflows/README.md\")`\n- `workspace_shell(\"cat connections/<name>/README.md connections/<name>/RULES.md connections/<name>/SYNTAX.md\")`\n- Before authoring or running any query, also read the `query-and-analyze` and\n  `using-connection-cli` skills — they are prerequisites, not optional\n  further reading.\n\n`RULES.md` files are long-term memory — the workspace-level one holds general\nconventions, and each `connections/<name>/RULES.md` holds connection-specific\nfacts: field quirks, reliable query patterns, naming conventions accumulated\nfrom prior sessions. Read them before authoring queries and update them when\nyou discover new facts.\n\n## DUCKDB is a connection\n\nDUCKDB is the in-workspace analytical connection, backed by\n`.dv/duckdb/workspace.duckdb`. Query it through the `connection` CLI:\n\n```text\nworkspace_shell(\"connection query DUCKDB --file connections/DUCKDB/queries/<file>.sql --json\")\n```\n\nUse it for joins across connections, intermediate tables, and in-workspace\nderived datasets.\n\n## Where to put things\n\n- query files -> `connections/<name>/queries/`\n- metadata snapshots -> `connections/<name>/metadata/`\n- reusable programs -> `scripts/`\n- user-facing outputs -> `artifacts/`\n- scheduled jobs -> the user crontab (`crontab -l`), not a workspace file\n- user-provided data -> `data/uploads/`\n- fetched data -> `data/downloads/`\n- database files -> `data/databases/`\n\nDo not write to `.dv/`; it is runtime-managed.\n\n## Pointers\n\n- adding a connection, installing a demo, fixing credentials -> `setup-connection`\n- querying data, exploring schemas, joining sources -> `query-and-analyze`\n- building a chart or dashboard -> `build-dashboard`\n- building a scheduled data or AI workflow -> `build-scheduled-pipeline`\n- managing an existing recurring job -> `setup-automation`\n- before running any `connection` verb (even routine ones) -> `using-connection-cli`\n"
}