airtable

Files (5)

• SKILL.md
• airtable.cjs
• scenarios.json · evals/
• schema.json · fixtures/
• index.cjs

SKILL.md (first lines)

# 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:

```bash
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
   current task.
7. Pass `--operator-grant` only after explicit approval or an approved F14
   escalation.
8. Prefer table ids and field ids over names for durable automation. Table names
   work but are rename-sensitive.
9. When deleting records, use exact record ids only.

## Command Contract

Run the colocated helper with Node:

```bash
node skills/airtable/airtable.cjs --help
```

Plan a natural-language request without contacting Airtable:

```bash
node skills/airtable/airtable.cjs plan "Update the status field on this Airtable task"
```

List bases:

From HybridAIOne/hybridclaw, MIT.

More from HybridAIOne/hybridclaw