/airtable

name: airtable
description: "Search Airtable bases and tables, read records and computed fields, and prepare guarded record CRUD requests with schema-based field validation."
user-invocable: true
requires:
  bins:
    - node
credentials:
  - id: airtable-pat
    kind: bearer
    required: true
    secret_ref:
      source: store
      id: AIRTABLE_PAT
    scope: "api.airtable.com/v0"
    how_to_obtain: "Create an Airtable Personal Access Token or OAuth bearer token with the needed scopes. Set `AIRTABLE_PAT` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set AIRTABLE_PAT \"<token>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set AIRTABLE_PAT \"<token>\"`."
metadata:
  hybridclaw:
    category: productivity
    short_description: "Airtable bases, tables, records, attachments, and safe writes."
    tags:
      - airtable
      - records
      - bases
      - tables
      - attachments
      - formulas
    stakes_tiers:
      green:
        - base-list
        - schema-read
        - record-read
        - formula-field-read
      amber:
        - record-create
        - record-update
        - attachment-update
      red:
        - record-delete
    escalation:
      writes: confirm-each
      route: f14
    cost_measurement:
      system: UsageTotals
      sub_limit_contract: R5.4
      sub_limit_key: airtable

Airtable

Use this skill for Airtable Web API work: base and table discovery, schema inspection, record reads, field-aware record creation and updates, attachment field payloads, formula/lookup/rollup reads, and carefully gated deletes.

Scope

• list accessible bases
• inspect base table schemas, field ids, field names, field types, and select

choices

• list records with pagination, views, field selection, and `filterByFormula`
• fetch a single record by id
• create, update, and delete records only after explicit operator grant
• validate field values against Airtable metadata before writes when schema is

available

• prepare attachment field values from public `http(s)` URLs
• read formula, lookup, rollup, count, autonumber, created time, and last

modified time fields as normal record values

• refuse writes to computed/read-only field types
• measure skill run cost through normal HybridClaw `UsageTotals`

Credential Rules

Airtable uses Personal Access Tokens or OAuth bearer tokens. Store the token in HybridClaw encrypted runtime secrets; never paste it into the prompt.

Recommended setup order:

1. Browser admin: open the active HybridClaw admin URL ending in `/admin/secrets` and set `AIRTABLE_PAT`. 2. Browser `/chat` or TUI fallback: `/secret set AIRTABLE_PAT "<pat-or-oauth-access-token>"`. 3. Local console fallback:

hybridclaw secret set AIRTABLE_PAT "<pat-or-oauth-access-token>"

For live API calls inside HybridClaw, use the helper to build the `http_request` payload wrapper, then pass the emitted inner `httpRequest` object to the built-in `http_request` tool. The helper sets `bearerSecretName: "AIRTABLE_PAT"` on that inner object so the gateway injects the bearer token server-side. Do not use bash/curl for live Airtable calls when `http_request` is available, and do not ask the user to store a HybridClaw gateway token as an Airtable secret.

Do not try to verify `AIRTABLE_PAT` with `bash`, environment inspection, or by asking the model whether the secret exists. The model cannot inspect the gateway secret store. If the operator says the secret was set, attempt the `http_request` call with `bearerSecretName: "AIRTABLE_PAT"`. Only say the secret is missing if the built-in `http_request` tool returns a gateway error that explicitly says `AIRTABLE_PAT` is not set, unavailable, missing, or unresolved. If the error says the secret is blocked by policy, report a policy/runtime configuration problem instead of asking the operator to set the same secret again.

Required Airtable PAT scopes depend on the task:

• base discovery: `schema.bases:read`
• schema inspection: `schema.bases:read`
• record reads: `data.records:read`
• record creates, updates, attachments, and deletes: `data.records:write`

Error Interpretation

• Gateway errors saying `AIRTABLE_PAT` is not set, unavailable, missing, or

unresolved: the active gateway runtime cannot resolve that stored secret. Ask the operator to set it in the same HybridClaw runtime/session in this order: browser admin at the active `/admin/secrets` route, `/secret set AIRTABLE_PAT <pat>` in browser `/chat` or TUI, then local console fallback `hybridclaw secret set AIRTABLE_PAT <pat>`, then start a fresh agent runtime if the gateway was already running.

• Gateway errors saying `AIRTABLE_PAT` is blocked by secret resolution policy:

report that the stored secret exists but policy/runtime access blocked the injection path. Do not ask the operator to set the same secret again.

• Airtable 401 or 403 responses: the gateway injected a token, but Airtable

rejected it or the PAT lacks the needed scopes/base access. Ask the operator to check PAT scopes and base access; do not say the secret is unconfigured.

• Network or Airtable 5xx responses: report the upstream failure and retry only

if the user asks.

Default Workflow

1. Start with base and table discovery unless the base id and table id are already known. 2. If the user asks to list tables and does not provide a base id, first call `list-bases` through `http_request`, then call `schema --base-id ...` for each relevant base returned by Airtable. 3. Read table schema before writes so field ids, field types, select choices, and computed fields are known. 4. Use `plan` for natural-language requests when you need a mutation tier before execution. 5. Use `validate-fields` or `--schema-file` on write payload builders before creating or updating records. 6. For writes, stop unless the operator has granted that exact mutation in the cu