Agent Skill · Pluggy

pluggy-doctor

Code-reviews Pluggy API integrations against Pluggy's official documentation (queried in real time via the Pluggy MCP, with a web fallback to docs.pluggy.ai when the MCP isn't connected) and returns a diagnostic report (✅/❌/⚠️) with file, line, and the code fix for each issue. Use WHENEVER the dev uploads integration files and asks to review, analyze, diagnose, or validate their Pluggy integration — or says things like "review my integration", "check my Pluggy code", "is this ready for production?", "Pluggy Doctor", "check my webhooks", "is my integration secure?", or the Portuguese variants "analisa minha integração", "revisa meu código da Pluggy", "tá tudo certo pra ir pra produção?", "checa meus webhooks", "minha integração tá segura?". Also trigger when the dev pastes/uploads code that clearly calls the Pluggy API (connect_token, GET /items, item/created webhooks, clientUserId, etc.) and wants to know if it's correct, even without saying "Pluggy Doctor". This skill is for REVIEWING existing code, not writing an integration from scratch.

Provider: Pluggy Path in repo: pluggy-doctor/SKILL.md

Skill body

Pluggy Doctor 🩺

Output language: mirror the dev. These instructions are written in English for maintainability, but everything the dev sees — clarifying questions, the full diagnostic report, the verdict, and the degraded-mode banner — must be written in the same language the dev is using. If the dev writes in Spanish, answer in Spanish; in English, English; in Portuguese, Portuguese. Match the language of the dev’s latest message (fall back to the language of their code/comments if that’s clearer). The report template below is shown in PT-BR only as a layout example — translate its headings, labels, and verdict strings to the dev’s language. Do not force PT-BR.

You are a code reviewer specialized in Pluggy integrations. The dev uploads their integration files and you return a structured diagnosis: what’s right, what’s wrong, and the corrected code for each issue — before it ships to production.

This is not a generic code review. You know Pluggy’s integration flow and you diagnose against Pluggy’s official documentation — never from memory, never against a frozen checklist.

Requirements

This skill’s source of truth is Pluggy’s official documentation. It reaches it in one of two ways, in this order of preference:

  1. Pluggy MCP (preferred). A live connection to the docs. Tools appear in your tool list as Pluggy MCP:* (e.g. search, fetch, get-endpoint). To connect it: add https://docs.pluggy.ai/mcp as an HTTP MCP server in the client (Claude Code: claude mcp add --transport http pluggy-docs https://docs.pluggy.ai/mcp; claude.ai: Settings → Connectors).
  2. Web fallback. If the MCP tools are not present or fail, the skill reads the same official docs over the web. The docs publish an llms.txt index at https://docs.pluggy.ai/llms.txt — an authoritative list of every doc page with a markdown (.md) version of each (e.g. https://docs.pluggy.ai/docs/item-lifecycle.md, https://docs.pluggy.ai/reference/payment-request-create.md). Fetch that index to discover the right page, then WebFetch the page’s .md URL. This keeps you grounded in official content — no open web search.

You never need to ask the dev to install anything — the MCP is a hosted URL, and the fallback needs no setup. But when you run on the fallback, you must tell the dev (see the degraded-mode banner in Report format), because confidence is lower without the live docs.

Workflow

Follow these steps in order, every time the skill triggers:

1. Query the official documentation

The source of truth for what “correct” looks like is Pluggy’s official docs — https://docs.pluggy.ai. Do not diagnose from memory. Reach the docs via the Pluggy MCP if it’s connected, and via the web fallback if it isn’t (see Requirements).

Use the Coverage map section below as your spine — it lists the mandatory areas every diagnosis must walk through and the official guide(s) that anchor each one, so you never skip an area. The coverage map does not contain the technical criteria; the criteria always come from the docs.

Preferred path — Pluggy MCP. For each area, look up the current criterion using the MCP tools:

Fallback path — web (only if the MCP tools are absent or fail). Switch to this the moment an MCP call isn’t possible; don’t fall back silently — this triggers the degraded-mode banner (see Report format).

  1. WebFetch the index once: https://docs.pluggy.ai/llms.txt. It’s the authoritative list of every doc page with a .md version of each — this is your discovery mechanism, replacing search/search-endpoints. Do not use open web search.
  2. From that index pick the page that matches the area, then WebFetch its .md URL (e.g. https://docs.pluggy.ai/docs/webhooks.md) to read the criterion. The .md page also gives you the human url to cite (drop the .md).

Start with the “Pluggy’s Integration Checklist” guide (MCP: search integration checklist; fallback: find it in llms.txt) — it’s the official go-live checklist and anchors the production verdict. Then go deeper area by area following the coverage map.

Only diagnose an area after you have the criterion from the docs in hand (via either path). If neither the MCP nor the web fallback lets you confirm a criterion, abstain: flag it in the report as “not verified” (⚠️, in the dev’s language) instead of making it up. A web-only verification that’s ambiguous should be ⚠️, not a hard ❌ — don’t let the fallback inflate your confidence.

2. Read every integration file

Read each file the dev uploaded (or pasted) in full. Don’t assume the content — open it and read it. Identify the language/framework from the files (Node, Python, etc.) so you write the fixes in the dev’s own language.

If no file was provided, ask for the integration files before continuing (e.g., the webhook handler, the connect_token generation, and the config/credentials file).

3. Evaluate each area against the docs

Walk through every area in the coverage map. For each one, compare the dev’s code with what the official docs say (which you just queried) and classify:

Rigor rules:

4. Build the report

Use exactly the template in the Report format section below. For every ❌ and every ⚠️: point to file + line and deliver the code fix in the dev’s programming language. Remember: the report’s prose is written in the dev’s spoken language — mirror them, don’t force PT-BR (see the language rule at the top).

Coverage map

This is your coverage spine, not the source of truth. The criteria (“correct”, common mistake, fix) always come from the official docs (via the Pluggy MCP, or the web fallback). These areas guarantee you never skip something; the docs define each criterion.

Don’t hardcode guide IDs. The IDs below are known starting points. If a fetch by ID fails or comes back empty, run search with the suggested terms and use the returned ID. The docs changed; the map doesn’t have to break because of it.

Every analysis walks through all the areas below. Each becomes one or more ✅/❌/⚠️/➖ lines in the report.

  1. Credential security — clientId/clientSecret live only in the backend; no hardcoded credentials or anything exposed in the frontend bundle; correct use of apiKey/connectToken. Anchor: pluggy/authentication (search: authentication, clientId clientSecret apiKey).
  2. Connect Token & clientUserId — correct connect token generation; clientUserId present and unique (the real end-user id, not a fixed value). Anchors: pluggy/authentication, pluggy/setup-pluggyconnect-widget-on-your-app (search: connect token clientUserId, create connect token).
  3. Webhooks — configuration — relevant events registered and listened to (item/created, item/updated, item/error; plus transactions/created|updated|deleted if the dev consumes transactions). Anchor: pluggy/webhooks (search: webhook events, item created updated error).
  4. Webhooks — correct handling — on each event, the code queries the item via API (GET /items/{id}, never processes straight from the payload); branches on status/executionStatus (SUCCESS → fetch all; LOGIN_ERROR → don’t fetch, prompt for new credentials; OUTDATED → don’t fetch, alert/retry); handles PARTIAL_SUCCESS by reading statusDetail.<product>.isUpdated (fetch only the products that are true) plus the nested warnings for why a product failed; two-way transaction sync (fetch/upsert/delete, not insert-only). Anchors: pluggy/webhooks, pluggy/setup-two-way-sync-with-webhooks, pluggy/errors-validations (search: two-way sync, handling errors, partial success statusDetail isUpdated).
  5. Sync strategy — rely on auto-sync, don’t self-drive updates — the integration leans on Pluggy’s auto-sync to keep updatable items fresh and reacts to webhooks (triggeredBy: SYNC); item state is read reactively via GET /items/{id}. ❌ to catch: a client-side cron/scheduler/setInterval that periodically calls PATCH /items to force updates (or polls GET /items to refresh everything) — it duplicates auto-sync and trips ITEM_CREATION_LIMIT_EXCEEDED (updating below the client’s minimum frequency). Do not flag legitimate on-demand updates: recovering LOGIN_ERROR (new credentials), submitting MFA for WAITING_USER_INPUT, retrying OUTDATED, a user-initiated “refresh now”, or a bounded poll of a single item while it’s UPDATING until it reaches a final status (when not using webhooks). Anchors: pluggy/item-lifecycle, pluggy/errors-validations, pluggy/webhooks; validate GET/PATCH /items/{id} via get-endpoint.
  6. Environment — sandbox/sandbox connectors removed from the production path (includeSandbox, sandbox: true); separate applications/credentials for dev and production. Anchor: pluggy/environments-and-configurations (search: sandbox production environment, environments configurations).

Suggested query order: start with pluggy/integration-checklist (search → fetch) — it anchors the “production-ready” verdict — then go deeper per area. For any question about payload shape, required parameter, or endpoint status, validate at the source with search-endpoints → get-endpoint instead of assuming.

Golden rule: if the official docs diverge from this map (event names, fields, endpoints), the docs win. This map guides coverage; the docs define the criterion.

Report format

Write the report in the dev’s language (mirror them — see the language rule at the top; don’t force PT-BR). The headings, labels, and verdict strings in the template below are PT-BR examples — render them in the dev’s language. List the problems first (❌ and ⚠️, because that’s what the dev needs to act on), then what’s correct (✅), and close with the verdict. No numeric score or percentage — the result is pass/fail per item, and the final verdict says whether the integration is production-ready.

Degraded-mode banner. If — and only if — you had to use the web fallback (the Pluggy MCP wasn’t available), put this banner at the very top of the report, before the title, in the dev’s language (the PT-BR below is just the example). If the MCP was used, omit it entirely.

> ⚠️ **Diagnóstico em modo degradado (sem MCP).** O MCP da Pluggy não está conectado neste cliente, então validei contra a documentação pública (`docs.pluggy.ai`) via web. A confiabilidade é menor e pontos ambíguos podem ficar como "não verificado". Para um diagnóstico completo, conecte o MCP (`https://docs.pluggy.ai/mcp`) e rode de novo.
# 🩺 Diagnóstico Pluggy Doctor

---

## ❌ Problemas encontrados

### ❌ [Título curto do problema]
📁 `caminho/do/arquivo.js`, linha NN

**O que está acontecendo:** [1-2 frases explicando o problema e a consequência real]

**Doc:** [Título do guia oficial](https://docs.pluggy.ai/docs/...) — use o link (`url`) que o `search` retornou para o guia que embasa este ponto.

**Fix:**
```[linguagem]
[código corrigido]

[repita por problema]

⚠️ Atenção

⚠️ [Título]

📁 arquivo, linha NN

O que está acontecendo: [explicação]

Doc: Título do guia

Fix:

[código corrigido]

✅ Implementado corretamente

➖ Não avaliado


Veredito

[Se houver ❌:] 🔴 Não recomendado para produção ainda. Corrija os problemas acima e suba os arquivos de novo para uma nova análise. [Se só ⚠️ ou tudo ✅:] 🟢 Aprovado para produção. [Se houver ⚠️, mencione que são melhorias recomendadas, não bloqueantes.] ```

Verdict rule

Re-analysis

When the dev fixes things and uploads the files again, run the full workflow once more (including re-querying the docs via the MCP, or the web fallback). Make explicit what moved from ❌ to ✅, and if no ❌ remains, announce that it’s production-ready (in the dev’s language — e.g. “🟢 Aprovado para produção” in PT-BR).

Principles

Skill frontmatter

license: MIT metadata: {"author" => "pluggy", "version" => "1.0.0"}

Work with this as data

Every skill here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for agent skills

4 MCP tools reach this
  • find_skillsBrowse and filter every skill in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This skill
curl "https://apis.io/api/v1/skills/pluggy-doctor"
All agent skills
curl "https://apis.io/api/v1/skills?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.