fill-sheet— agent skill

Purpose

The sheet-filler server manages objects (rows) with fields (columns). It prevents overwriting existing values, making it safe for incremental data collection.

Workflow

Setup (if needed)

#### Authenticate to Google Sheets

If not authenticated, use the device code flow:

# 1. Check status
filler_google_auth({ action: "status" })
→ { status: "Not authenticated. Use start_auth to begin authentication." }

# 2. Start auth
filler_google_auth({ action: "start_auth" })
→ { verification_url: "https://www.google.com/device", user_code: "ABCD-EFGH", device_code: "xyz123", instructions: "Visit ... and enter code: ABCD-EFGH" }

# 3. Tell user to visit URL and enter code, wait for confirmation

# 4. Complete auth
filler_google_auth({ action: "complete_auth", device_code: "xyz123" })
→ { status: "Authenticated to Google Sheets" }

#### Initialize a New Sheet

If the spreadsheet doesn't have data and fields tabs yet, create them:

filler_init()
→ { success: true, fieldsTab: "fields", dataTab: "data", keyField: "name" }

This creates both tabs with their header rows. Errors if either tab already exists.

#### Switch to a Different Sheet

To work with a different Google Sheet:

filler_use_sheet_id({ sheet_id: "1ABC...xyz" })
# or with full URL:
filler_use_sheet_id({ sheet_id: "https://docs.google.com/spreadsheets/d/1ABC...xyz/edit" })

Main Workflow

#### 1. Understand the Schema

First, get the field definitions to understand what data to collect: filler_list_fields().

Fields with auto: true are candidates for auto-filling. Each field has:

• name - field identifier
• type - validation type (string, number, date, url, email, json, enum:...)
• instructions - how to collect this value
• example - example value

#### 2. Get an Object

Two options for retrieving objects:

Option A: Get the next object with missing fields

filler_get_next_missing_fields_objects({ limit: 1 })

Returns objects with missing auto fields (default limit 1). If found: false, all objects are complete.

Pass skip_filled_fields: true to omit already-filled values from object.values, reducing response size for sheets with many columns.

Option B: Get specific objects by name

filler_get_objects_by_name({ names: ["Acme Corp"] })

Returns objects with their missing auto fields. Useful when you know which objects to work on.

Option A returns { found, objects, count, remain }. Option B returns { objects: [{ found, object, missing }] }. Both provide object data and fields that need filling.

#### 3. Collect Values

For each missing field, follow the instructions to collect the value. Ensure values match the field type:

#### 4. Save Values

Save collected values (won't overwrite existing data):

filler_save_objects_no_overwrite({
  objects: [{
    name: "Acme Corp",
    values: {
      "website": "https://acme.com",
      "founded": "1990"
    }
  }]
})

Check the result for each field:

• saved - value was stored
• skipped_already_set - field already has a value (not overwritten)
• rejected_unknown_field - field not in schema
• rejected_invalid_type - value failed type validation

#### 5. Repeat

Continue with step 2 until no missing auto fields remain.

Creating New Data

Add Fields

filler_add_fields({
  fields: [{
    name: "revenue",
    description: "Annual revenue",
    type: "number",
    auto: true,
    instructions: "Find the company's annual revenue in USD",
    example: "1000000"
  }]
})

Add Objects

filler_add_objects_by_name({ names: ["New Company"] })

Example Session

# 1. Check schema
filler_list_fields()
→ fields: [name, website (auto), email (auto), founded]

# 2. Get object
filler_get_next_missing_fields_objects({ limit: 1 })
→ { found: true, objects: [{ object: { name: "Acme Corp" }, missing: [{ name: "website", type: "url", instructions: "Find official website" }] }], count: 1, remain: 0 }

# 2b. Or get a specific object
filler_get_objects_by_name({ names: ["Acme Corp"] })
→ { objects: [{ found: true, object: { name: "Acme Corp" }, missing: [{ name: "website", ... }] }] }

# 3. Collect and save
filler_save_objects_no_overwrite({ objects: [{ name: "Acme Corp", values: { website: "https://acme.com" } }] })
→ result: { website: "saved" }

## Key Rules

1. **Never guess values** - only save data you have verified
2. **Check field types** - ensure values match the expected format before saving
3. **Trust the no-overwrite** - the server protects existing data, but don't rely on this as a crutch
4. **Follow instructions** - each field's `instructions` describe how to collect that specific value
5. **Handle rejections** - if a value is rejected, check the type and fix accordingly