integrations
Use when connecting to or automating a third-party service/SaaS — its REST API, an MCP server, OAuth/token auth, webhooks, or a recurring sync (usage/billing/ expense trackers, data pushes, scheduled
SKILL.mdskills/integrations/SKILL.md
GitHubIntegrations & Automations
Goal: build integrations with external services that are correct, idempotent, and run where they actually can — and accumulate the per-service quirks so the next one is faster. External writes are outward-facing and often hard to reverse; treat them with care.
Workflow
Follow in order — steps 1, 3, and 4 are hard gates, because each one invalidates all the work built on top of it when skipped.
- Read the per-service quirks first. Check
LEARNINGS.mdbeside this skill, when your copy keeps one (an index over per-service reference files), for the target service's auth model, gotchas, and idempotency approach — most integration pain here has already been paid for once. Then read the provider's API/MCP surface and mirror existing patterns. - Nail the spec with worked examples (section below) — especially anything computing money/metrics. Gate: don't write compute code while a formula, period, denominator, or rounding question is still open.
- Prove the auth path you will SHIP with one real call — before building around it. An interactive MCP session ≠ a usable standalone token (section below). Gate: no pipeline design until the headless/PAT/service-token path has succeeded against the real service once.
- Decide where it runs (section below): deterministic local hook → in-session MCP/slash-command → headless/cloud, constrained by where the data AND the auth actually live. Gate: don't build unattended automation on an auth/data source that only exists in an interactive session.
- Build deterministic compute + idempotent write + state file + once-per-period guard (section below).
- Dry-run on real data, show the numbers, then write with explicit user OK for anything billable/outward-facing — an external write may be visible to a client the moment it lands.
- Verify independently: read the record back through a second channel (e.g. the MCP, a GET) — a 200 on the write proves acceptance, not the state you intended (sends can queue-then-suppress; edits can partially apply).
- Record what you learned (protocol at the bottom).
Nail the spec before you build (esp. anything computing money/metrics)
This is the #1 time-saver. For any calculation-driven integration, pin down the exact formula, the period/cadence, the denominator, and the edge cases before writing code.
- Use worked examples on the user's real data to confirm the model — show the actual numbers, not a description. Surprising results ("this seems too high", "starting later bills more") surface the right model far better than prose.
- Use AskUserQuestion for genuine forks (which denominator, which cost basis, which rounding/period, what the markup means when it changes). Don't guess on money.
- Expect to iterate the model, not just the code. If you've rewritten the compute engine 3+ times, the lesson is "clarify the spec earlier," not "code faster."
- Make every assumption a single editable config knob (rate, multiplier, tax, start date, period), so re-tuning is a one-line change, not a refactor.
Reality-check the auth path you will SHIP — early (gate)
An authenticated MCP session ≠ a usable standalone token. The MCP may work interactively while the token-based path you intend to automate fails.
- Test the actual auth you'll deploy (PAT / service token / headless) against a real write early, before building everything around it — discovering the token path is blocked after the pipeline is built means rebuilding the pipeline.
- Interactively-authenticated MCP servers may be absent in headless/cron runs — don't design unattended automation that silently depends on an interactive MCP.
- Watch for org policy blocks: SSO-enforced accounts can 401 token API calls with a
policy message even when the token is valid. Read the error text, don't assume "bad
token" (a worked case:
LOCAL.mdbeside this skill, when your copy keeps one — SSO token-block worked case).
Run automation where the data and the auth actually are
- If the source data is local (e.g. local files/transcripts/DB), the job must run locally — a cloud agent can't see it.
- Beware self-referential cost: an LLM-driven job that measures usage consumes the thing it measures. Prefer a deterministic script for the compute and reserve the LLM/MCP for the one step that needs it.
- Decision order for "run it daily": deterministic local hook (zero-token, best) → in-session MCP / slash-command (when only the MCP auth works) → headless/cloud (only if data + auth are both reachable there).
Make external writes idempotent (gate)
Recurring jobs must not create duplicates — a re-run that re-creates is a bug the user discovers on their invoice/board/inbox, not in your tests.
- Track a stable target id in a small local state file; re-runs update that id, they don't re-create.
- Prefer recompute-from-source each run (re-derive the whole current value) over incremental deltas — it's self-healing and drift-free.
- Add a once-per-period guard (e.g.
last_run_date == today → no-op) so multiple triggers in a day don't double-write. - If the provider offers an idempotency/external key, use it; if not, the state-file id is the fallback. Know the provider's lock semantics (e.g. records freeze once invoiced/finalized) and branch on them — a PATCH against a locked record fails or, worse, silently no-ops.
- Append-only surfaces (comments, sends) can't be updated — gate them behind a flag and a stated intent, since idempotency-by-update is unavailable.
Secrets & confidential economics
- Keep tokens out of the repo (e.g. a secrets manager or a tool-specific private
configuration directory); support an env-var override. Never echo secret
values; redact them in any
--status/debug output. - Pasting a secret into chat persists it in the transcript — prefer the user enters it into the config themselves, and recommend a least-scoped, revocable token.
- Any field written to an outward-facing record is client-visible (a billable expense's "notes" can land on the invoice). Keep internal economics out of it — markup/margin, cost basis, your own rates. Put the full breakdown in a local log, send a minimal client-safe value (e.g. just a label + date).
- Beware derivable secrets: showing the cost basis and the share/quantity alongside the billed total lets a client back out the markup by division (worse when the underlying price is public). Omit the inputs, not just the markup factor.
Don't let an automation break the host
- A hook/automation must never crash the thing that runs it: catch everything, exit 0, run detached/async, log to a file. A failed external call should be a logged no-op — the session/host matters more than the sync.
Close the loop upstream
When the provider's API/MCP forced a workaround (missing field, no idempotency key, confusing error), submit feedback to that provider (most MCPs expose a feedback tool) framed as a concrete feature request. Future integrations get easier.
Common failure modes
- Building the whole pipeline on interactive-MCP auth, then discovering the headless path 401s — step 3 exists to catch this on day one.
- Blind re-create on every run (no state file / no period guard) → duplicate expenses, double comments, repeated sends.
- Trusting the write's 200: a queued send can still be suppressed/undeliverable; always read state back (step 7).
- Leaking economics or secrets into outward-facing fields or logs — notes, debug output, error messages that interpolate a token.
- Guessing a money formula instead of confirming with worked examples on real data.
- An automation that can crash its host — un-caught errors in a hook, foreground blocking, unlogged failures.
- Assuming the identifier scheme (email-as-id, key-independent tokens) — verify the provider's actual keying before lookups; error text like "invalid key" can point at the wrong credential.
Before you call this done
- Read the service's LEARNINGS/reference entries before building.
- Spec confirmed with worked examples; every assumption is a config knob.
- The SHIPPED auth path proven with a real call (not just the MCP session).
- Writes are idempotent: state file + once-per-period guard + lock-semantics handling.
- No secret or internal economics in any outward-facing field, log, or transcript.
- Dry-run shown; outward/billable writes made only with explicit user OK.
- Result verified through a second channel (read-back), not just the write's response.
- New quirks recorded per the protocol below.
Related skills
- security-and-hardening: a new integration or inbound webhook is a security trigger path; secrets handling follows that skill.
- code-quality: the hard rules every client, webhook handler and automation diff meets — one responsibility per file, readable by a junior engineer, and one rhythm per kind of work.
Capturing learnings (session-handoff protocol)
Accumulate per-service quirks, auth notes, and reusable patterns in LEARNINGS.md beside
this skill, when your copy keeps one (an index over per-service/theme reference files). On
handoff / "update skills" / after integration work: record the service, its auth model, gotchas,
idempotency approach, and any feedback submitted — append under a new ## section in the
most relevant reference file (not the index). Dedupe/merge, tag by service. Read it
before starting work on that service.