---
name: sheets
description: Use Agent Sheets as an external-agent spreadsheet runtime. Use when reading, editing, validating, debugging, versioning, or automating workbooks through the CLI/API instead of the in-app agent.
defaultEnabled: false
---

# Agent Sheets

Use this skill when working with Agent Sheets workbooks from an external coding agent.

## Workflow

1. Start the local app server if it is not already running.
2. Use `sheets status` to verify the global Agent Sheets store and server.
3. Use `sheets list` to find an existing workbook, or `sheets create "<title>"` to create one. Creation returns the browser URL.
4. Read context with `sheets context <workbook>`.
5. Use targeted reads before edits:
   - `sheets read <workbook> <sheet> <range> --mode summary`
   - `sheets cell <workbook> <sheet> <range>`
   - `sheets deps <workbook>`
6. Apply workbook changes through structured operations:
   - `sheets preview-patch <workbook> patch.json`
   - `sheets apply-patch <workbook> patch.json --summary "..."`
   - `sheets run-script <workbook> script.js --summary "..."`
   - `sheets run-function <workbook> <name> --args '{"key":"value"}'`
7. Run `sheets check <workbook>` after substantive edits.
8. Use `sheets history <workbook>` and `sheets revert <workbook> <version>` for workbook versioning.

## Tool Surface

The CLI mirrors the in-app workbook tools:

- `get_workbook_context`
- `check_workbook`
- `read_range`
- `get_cell_context`
- `debug_formula`
- `create_sensitivity_table`
- `preview_patch`
- `apply_patch`
- `run_workbook_script`
- `run_sheet_function`
- `inspect_dependencies`
- `native_primitives`

For any tool not covered by a friendly command, use:

```bash
sheets tool <workbook> <toolName> args.json
```

## CLI Output

Use default output for normal agent loops. It is concise JSON and omits noisy history payloads.

- Add `--brief` when you only need ids, URLs, status, or pass/fail summaries.
- Add `--verbose` when you need the full raw API response, including history and diff samples.
- Prefer `sheets create`, `sheets list`, and `sheets url` over raw `/api/workbooks` calls.
- Do not inspect Agent Sheets source files unless the user is asking to change Agent Sheets itself.

## Editing Rules

- Do not edit `~/.agent-sheets/data/sheets.db` directly.
- Do not mutate workbook state by editing React/server internals.
- Prefer named ranges, tables, checks, and semantic sheet organization over brittle raw A1-only models.
- Prefer `run_workbook_script` for large repetitive operation arrays.
- Use `debug_formula` before broad formula rewrites when behavior is uncertain.
- Use `native_primitives` before designs that may depend on unsupported spreadsheet functions.
- Keep summaries short and meaningful; they are shown in version history.

## Patch Shape

`apply-patch` accepts either an array of workbook operations or an object:

```json
{
  "summary": "Update assumptions",
  "operations": [
    {
      "type": "set_cell",
      "sheetId": "Sheet1",
      "address": "B2",
      "value": 123,
      "provenance": "agent"
    }
  ]
}
```

Use sheet ids or display names as accepted by the workbook tools. For newly created sheets in one patch, use `create_sheet.alias` and later references like `"$alias"`.

## Validation

Treat `check_workbook` like a build:

- formula errors are failures
- sanity check failures are failures
- non-finite numbers are failures
- missing required table values are failures
- clipped text, missing units, and warning markers are actionable warnings

If warnings remain, report them explicitly.