Bookkeeper

Automates invoice intake from Gmail, extracts data via OCR, verifies payment in Stripe, and creates reconciliation-ready accounting entries in Xero.

Security Scan

The skill's stated bookkeeping orchestration mostly matches its instructions, but there are unexplained and potentially high‑privilege requirements (a single MATON_API_KEY that allegedly covers Gmail/Stripe/Xero and an unexplained python3 dependency) that do not align cleanly with the declared purpose.

Purpose & Capability

The skill's name and runtime instructions match the bookkeeping/orchestration purpose (Gmail → OCR → Stripe → Xero). However, requiring a single MATON_API_KEY 'for Gmail, Stripe, Xero through Maton gateway' is not justified or explained and is unusual for these services (which normally use separate OAuth flows or per-service API keys). Also, python3 is required but the SKILL.md contains no Python steps — this is unexplained.

Instruction Scope

The SKILL.md limits behavior to email scanning, attachment OCR, payment verification, and Xero writes. It does not instruct the agent to read arbitrary local files or unrelated environment variables, and it includes safety notes (quality gates, manual-review policy). The skill does instruct the agent to install upstream skills via npx, which will cause additional downloads but is within the stated orchestration scope.

Install Mechanism

This is instruction-only (no install spec), which reduces direct risk. The SKILL.md recommends using 'npx -y clawhub@latest install ...' to install upstream skills; that will cause npx to fetch packages at runtime (moderate risk depending on clawhub's provenance). No direct download URLs or extract steps are present in this skill itself.

Credentials

Only two env vars are declared, but MATON_API_KEY is described as providing access to Gmail, Stripe, and Xero via a gateway — that is a high-privilege, broad-scope credential that is disproportionate without explanation. DEEPREAD_API_KEY is appropriate for OCR. The skill also declares no primary credential even though MATON_API_KEY appears to be the main secret (inconsistency).

Persistence & Privilege

The skill is not marked always:true and does not request modification of other skills' configs. It allows autonomous invocation (disable-model-invocation: false) which is the platform default; there is no indication it would persist beyond normal skill behavior.

What to consider before installing

Before installing or enabling this skill, confirm the following: - Ask the author to explain 'MATON_API_KEY': what is the Maton gateway, which services does it actually control, what scopes/permissions does the key grant, where is it stored, and why is one key used instead of per-service OAuth? A single gateway key that can access Gmail, Stripe, and Xero is high‑impact — prefer per-service OAuth with least privilege. - Ask why python3 is required when the SKILL.md contains no Python steps; verify whether upstream skills (gmail, deepread-ocr, stripe-api, xero) have specific runtime requirements that justify python3 being mandatory. - Request that MATON_API_KEY be declared as the primary credential (or clarify why not) and that the skill document the exact scopes and token rotation/lifecycle. - Audit the upstream skills the meta-skill installs (clawhub install ...). Installing third-party packages via npx will pull remote code — review those package sources and their requested permissions before allowing installation in production accounts. - Insist on least-privilege: ensure the gateway/API token cannot perform actions beyond read/list/write only what is necessary (e.g., read-only Gmail for intake, restricted create only in a specific Xero org). Consider testing in a sandbox Xero/Stripe/Gmail environment first. - Require explicit user confirmation and review policy before any automatic posting of financial records (the SKILL.md's policies are good; ensure enforcement and logging exist). If the author can provide detail on Maton (service homepage, token scope), justify python3, and show that the gateway token does not grant excessive admin power, confidence in this skill would increase. Without that, treat the MATON key as a high‑risk item and proceed cautiously.

Purpose

Automate preparatory bookkeeping from incoming email to accounting records.

Core objective:

1. detect invoice email,
2. extract structured invoice data,
3. verify payment event,
4. create accounting entry and reconciliation status.

This is orchestration logic across upstream tools; it is not a replacement for financial controls.

Required Installed Skills

• gmail (inspected latest: 1.0.6)
• deepread-ocr (inspected latest: 1.0.6)
• stripe-api (inspected latest: 1.0.8)
• xero (inspected latest: 1.0.4)

Install/update:

npx -y clawhub@latest install gmail
npx -y clawhub@latest install deepread-ocr
npx -y clawhub@latest install stripe-api
npx -y clawhub@latest install xero
npx -y clawhub@latest update --all

Required Credentials

• MATON_API_KEY (for Gmail, Stripe, Xero through Maton gateway)
• DEEPREAD_API_KEY (for OCR extraction)

Preflight:

echo "$MATON_API_KEY" | wc -c
echo "$DEEPREAD_API_KEY" | wc -c

If missing, stop before any bookkeeping action.

Inputs the LM Must Collect First

• company_base_currency
• invoice_keywords (default: invoice, rechnung, receipt, quittung)
• vendor_rules (for example AWS -> Hosting expense account)
• date_tolerance_days for matching (default: 3)
• amount_tolerance (default: exact, or configurable small tolerance)
• auto_post_policy (manual-review, auto-if-high-confidence)
• attachment_policy (store-link, attach-binary-if-supported)

Do not auto-post financial records without explicit policy.

Tool Responsibilities

Gmail (gmail)

Use for intake and attachment discovery.

Relevant behavior:

• query messages with Gmail operators (for example has:attachment, subject:invoice, sender filters)
• fetch message metadata and full payload for parsing
• label/update messages after processing (for traceability)

DeepRead OCR (deepread-ocr)

Use for extracting structured fields from invoice PDFs/images.

Relevant behavior:

• async processing (queued -> completed/failed)
• schema-driven extraction
• field-level hil_flag and reason for uncertainty
• webhook or polling modes

Stripe (stripe-api)

Use for payment-side verification.

Relevant behavior:

• query charges/payment_intents/invoices/balance transactions
• verify amount, currency, status, and date proximity

Xero (xero)

Use for accounting record creation and payment/reconciliation visibility.

Relevant behavior:

• create contacts if missing
• create invoices/bills (ACCPAY for payable bills)
• list payments and bank transactions

Canonical Signal Chain

Stage 1: Inbox detection

Scan Gmail for candidate invoice emails.

Recommended query pattern:

• has:attachment (subject:invoice OR subject:rechnung OR subject:receipt OR subject:quittung)
• optional sender constraint for known vendors (for example from:aws)

Output:

• message ID
• sender
• received date
• attachment candidates

Stage 2: Attachment extraction

For each invoice candidate attachment:

1. send file to DeepRead OCR with invoice schema
2. wait for async completion (webhook preferred; polling fallback)
3. parse structured result

Minimum extracted fields:

• vendor
• invoice_date
• invoice_number
• total_amount
• tax_amount
• currency

Quality gate:

• if critical fields have hil_flag=true, route to review queue before posting.

Stage 3: Payment verification

Use Stripe to check whether corresponding payment occurred.

Matching policy:

• amount equals invoice total (within tolerance)
• currency matches
• date within tolerance window
• status is successful/paid

If multiple candidates match, mark as ambiguous_match and require review.

Stage 4: Accounting write

Use Xero for booking.

Default payable flow:

1. ensure vendor contact exists (create if needed)
2. create bill entry (Type: ACCPAY) with line item category (for example Hosting)
3. mark as paid/reconciled state only when Stripe verification is confident
4. include reference fields: invoice number, source message ID, payment reference

Attachment handling:

• if binary attachment endpoint/path is available in the active integration, attach file
• otherwise store durable file reference and include link/reference in description/metadata

Stage 5: Traceability updates

After successful processing:

• apply Gmail processed label
• store processing log (source email, extraction confidence, matching evidence, xero IDs)
• keep idempotency key to avoid duplicate posting

Scenario Mapping (AWS Invoice)

For the scenario "AWS invoice by email -> Xero + card match":

1. Gmail finds AWS email with PDF attachment.
2. DeepRead OCR extracts structured fields (vendor/date/total/tax/invoice number).
3. Stripe check confirms payment event around invoice date and amount.
4. Xero creates payable entry (ACCPAY) under Hosting category.
5. Record is marked paid only after confident match; source PDF linked/attached per policy.

Data Contract

Normalize to one transaction record before posting:

{
  "source": {
    "gmail_message_id": "...",
    "sender": "[e-mail]",
    "attachment_name": "invoice.pdf"
  },
  "invoice": {
    "vendor": "AWS",
    "invoice_number": "INV-123",
    "invoice_date": "2024-05-01",
    "total": 53.20,
    "tax": 0.00,
    "currency": "USD",
    "ocr_confidence_ok": true
  },
  "payment_match": {
    "provider": "stripe",
    "matched": true,
    "transaction_id": "ch_...",
    "amount": 53.20,
    "date": "2024-05-01"
  },
  "accounting": {
    "system": "xero",
    "entry_type": "ACCPAY",
    "category": "Hosting",
    "status": "Paid"
  }
}

Output Contract

Always return:

• IntakeSummary

  • emails scanned, invoice candidates found

• ExtractionSummary

  • extracted fields and hil_flag status

• PaymentVerification

  • matched/not matched + evidence

• AccountingAction

  • created/updated records and IDs

• ReviewQueue

  • any records requiring manual validation

Quality Gates

Before auto-posting:

• vendor identified
• invoice number/date/total present
• no critical hil_flag unresolved
• payment match confidence above policy threshold
• duplicate check passed (same vendor + invoice number + total)

If any gate fails, return Needs Review and do not auto-post.

Guardrails

• Never mark invoice as paid without payment evidence.
• Never silently overwrite existing accounting records.
• Never drop uncertain OCR fields; surface them explicitly.
• Prefer manual review when amount/date ambiguity exists.
• Preserve source audit trail for every booking action.

Failure Handling

• Gmail unavailable: stop intake and report connection issue.
• OCR job failed/timeout: keep email queued for retry.
• Stripe no match: post as unpaid bill or route to review per policy.
• Xero write failed: keep normalized record and retry safely with idempotency key.

Known Limits from Inspected Upstream Skills

• DeepRead OCR is asynchronous and may require webhook/polling orchestration.
• The inspected Xero skill docs emphasize core accounting endpoints but do not fully document attachment upload flow; attachment behavior depends on supported endpoint path in active integration.
• Stripe/Xero matching is orchestration logic here, not a single native "auto-reconcile" endpoint in these inspected skill docs.
• QuickBooks is not part of this researched stack; this meta-skill is Xero-first.

Treat these limits as mandatory operator disclosures.