Skill Tracer
Skills › Knowledge Work Plugins › build-connector › gotchas.md

gotchas.md

237 lines · small-business/skills/build-connector/reference/gotchas.md at 2574e29

Open on GitHub

Most marks come from matching words in the file, so treat them as pointers.

1# Gotchas
2
3Failure modes. Several of these are security issues, and the owner will not be thinking about any of them.
4
5---
6

Gotchas

Failure modes. Several of these are security issues, and the owner will not be thinking about any of them.

Raw lines 1 to 6
7## Gotcha: asking the owner to paste a password
8
9**Why it matters:** The most serious failure in this skill. A password in a conversation is a credential in a place it was never meant to be, and it usually grants far more access than the integration needs.

Gotcha: asking the owner to paste a password

Why it matters: The most serious failure in this skill. A password in a conversation is a credential in a place it was never meant to be, and it usually grants far more access than the integration needs.

Raw lines 7 to 10
11### Bad
13```
14What's your ServiceTrade login? I'll set up the connection.
15```

Bad

What's your ServiceTrade login? I'll set up the connection.
Raw lines 11 to 16
17### Good
19```
20This needs a read-only API token, not your login. Create one under
21Settings → API, then add it through the connector settings — don't paste it
22here.
23```
25Tokens and OAuth only. If a system offers nothing but password auth, say so and let the owner decide with that knowledge rather than working around it.
27Whatever the credential type, it goes into the platform's own credential storage — never into a file, a prompt, or a URL.
29---

Good

This needs a read-only API token, not your login. Create one under
Settings → API, then add it through the connector settings — don't paste it
here.

Tokens and OAuth only. If a system offers nothing but password auth, say so and let the owner decide with that knowledge rather than working around it.

Whatever the credential type, it goes into the platform's own credential storage — never into a file, a prompt, or a URL.

Raw lines 17 to 30
31## Gotcha: using the owner's own login instead of a dedicated integration user
33**Why it matters:** Access tied to the owner's personal login can't be revoked later without locking them out of their own account.

Gotcha: using the owner's own login instead of a dedicated integration user

Why it matters: Access tied to the owner's personal login can't be revoked later without locking them out of their own account.

Raw lines 31 to 34
35### Bad
37Connect the integration using the owner's own username and password, or their personal OAuth session, because it's the account already sitting in front of them.

Bad

Connect the integration using the owner's own username and password, or their personal OAuth session, because it's the account already sitting in front of them.

Raw lines 35 to 38
39### Good
41Where the platform supports it, create a dedicated integration user (or a scoped token tied to one) for the connector instead. Access can be revoked later without touching the owner's own login.
43---

Good

Where the platform supports it, create a dedicated integration user (or a scoped token tied to one) for the connector instead. Access can be revoked later without touching the owner's own login.

Raw lines 39 to 44
45## Gotcha: creating a connector before saying what it reaches
47**Why it matters:** An owner who doesn't know what a connector can see or do before it's created can't meaningfully say yes to it.

Gotcha: creating a connector before saying what it reaches

Why it matters: An owner who doesn't know what a connector can see or do before it's created can't meaningfully say yes to it.

Raw lines 45 to 48
49### Bad
51Connect first, mention the scope only if asked.

Bad

Connect first, mention the scope only if asked.

Raw lines 49 to 52
53### Good
55```
56The Zapier connection needs ServiceTrade connected inside your Zapier
57account. It'll see work orders and customers. It can't change anything or
58see billing.
60Connect it in Zapier under Apps → ServiceTrade — sign in there directly,
61don't paste any password here.
62```
64---

Good

The Zapier connection needs ServiceTrade connected inside your Zapier
account. It'll see work orders and customers. It can't change anything or
see billing.

Connect it in Zapier under Apps → ServiceTrade — sign in there directly,
don't paste any password here.
Raw lines 53 to 65
66## Gotcha: requesting more access than the job needs
68**Why it matters:** A connector with write access to the system of record can do damage the owner has no way to reverse or even notice.

Gotcha: requesting more access than the job needs

Why it matters: A connector with write access to the system of record can do damage the owner has no way to reverse or even notice.

Raw lines 66 to 69
70### Bad
72Request full access because it is simpler than working out the minimum.

Bad

Request full access because it is simpler than working out the minimum.

Raw lines 70 to 73
74### Good
76```
77Read-only is enough for this — it only needs to see work orders. If you later
78want it creating them, that's a separate change and I'd add approval gates.
79```
81Narrow scope, stated in plain terms, before anything is created.
83---

Good

Read-only is enough for this — it only needs to see work orders. If you later
want it creating them, that's a separate change and I'd add approval gates.

Narrow scope, stated in plain terms, before anything is created.

Raw lines 74 to 84
85## Gotcha: building before checking
87**Why it matters:** An hour spent building something that already existed is an hour the owner paid for nothing.

Gotcha: building before checking

Why it matters: An hour spent building something that already existed is an hour the owner paid for nothing.

Raw lines 85 to 88
89### Bad
91Start creating a Zapier connection immediately — or worse, start writing custom code against the tool's REST API.

Bad

Start creating a Zapier connection immediately — or worse, start writing custom code against the tool's REST API.

Raw lines 89 to 92
93### Good
95Check the Claude connector directory and MCP registry first, then Zapier, then scheduled exports. Report the finding, then build — and the build is the Zapier connection, never hand-written API code.
97---

Good

Check the Claude connector directory and MCP registry first, then Zapier, then scheduled exports. Report the finding, then build — and the build is the Zapier connection, never hand-written API code.

Raw lines 93 to 98
Uses an outside tool MCP :95
99## Gotcha: an unbounded scope
101**Why it matters:** "Connect my ERP" has no definition of done. It becomes a project, stalls, and the owner concludes the whole capability doesn't work.

Gotcha: an unbounded scope

Why it matters: "Connect my ERP" has no definition of done. It becomes a project, stalls, and the owner concludes the whole capability doesn't work.

Raw lines 99 to 102
103### Bad
105Accept "connect my ERP" as the requirement.

Bad

Accept "connect my ERP" as the requirement.

Raw lines 103 to 106
107### Good
109```
110What would you do with it first? If it's "see open work orders in my morning
111brief," that's buildable this afternoon. The whole system is a bigger
112conversation.
113```
115Start with one endpoint that unblocks one thing.
117---

Good

What would you do with it first? If it's "see open work orders in my morning
brief," that's buildable this afternoon. The whole system is a bigger
conversation.

Start with one endpoint that unblocks one thing.

Raw lines 107 to 118
119## Gotcha: not checking the plan tier
121**Why it matters:** API access is frequently gated to higher subscription tiers. Building against an API the owner cannot use is a wasted afternoon, and it happens often.

Gotcha: not checking the plan tier

Why it matters: API access is frequently gated to higher subscription tiers. Building against an API the owner cannot use is a wasted afternoon, and it happens often.

Raw lines 119 to 122
123### Bad
125Read the docs, build the connector, discover at test time that the token endpoint returns 403.

Bad

Read the docs, build the connector, discover at test time that the token endpoint returns 403.

Raw lines 123 to 126
127### Good
129```
130One thing before I build: ServiceTrade puts API access on Pro and above.
131Which plan are you on?
132```
134---

Good

One thing before I build: ServiceTrade puts API access on Pro and above.
Which plan are you on?
Raw lines 127 to 135
136## Gotcha: overselling reliability
138**Why it matters:** A custom connector is not a first-party integration. An owner who thinks it is will not investigate when their data quietly goes stale.

Gotcha: overselling reliability

Why it matters: A custom connector is not a first-party integration. An owner who thinks it is will not investigate when their data quietly goes stale.

Raw lines 136 to 139
140### Bad
142```
143All set — ServiceTrade is connected.
144```

Bad

All set — ServiceTrade is connected.
Raw lines 140 to 145
146### Good
148```
149Connected. Worth knowing how this breaks:
150 - The token expires in 90 days. I'll flag it before then.
151 - If they change their API, this stops working. No warning from their side.
152 - If work orders ever show as zero and that seems wrong, it's probably this,
153 not your data.
154```
156The third line is the important one. It teaches the owner to recognize the failure instead of trusting a wrong answer.
158---

Good

Connected. Worth knowing how this breaks:
  - The token expires in 90 days. I'll flag it before then.
  - If they change their API, this stops working. No warning from their side.
  - If work orders ever show as zero and that seems wrong, it's probably this,
    not your data.

The third line is the important one. It teaches the owner to recognize the failure instead of trusting a wrong answer.

Raw lines 146 to 159
160## Gotcha: silent failure
162**Why it matters:** A connector that stops working without saying so produces confidently wrong output. The morning brief shows no open work orders and the owner believes it.

Gotcha: silent failure

Why it matters: A connector that stops working without saying so produces confidently wrong output. The morning brief shows no open work orders and the owner believes it.

Raw lines 160 to 163
164### Bad
166Return an empty result when the fetch fails.

Bad

Return an empty result when the fetch fails.

Raw lines 164 to 167
168### Good
170Distinguish "no records" from "could not fetch," and surface the second:
172```
173Work orders: unavailable — ServiceTrade returned an auth error. This is a
174connector problem, not an empty queue.
175```
177For scheduled exports, check the file's age. If it is older than the expected interval, say so.
179---

Good

Distinguish "no records" from "could not fetch," and surface the second:

Work orders: unavailable — ServiceTrade returned an auth error. This is a
connector problem, not an empty queue.

For scheduled exports, check the file's age. If it is older than the expected interval, say so.

Raw lines 168 to 180
181## Gotcha: a write connector with no approval gate
183**Why it matters:** A connector that can modify the system of record unattended can do damage nobody notices for weeks.

Gotcha: a write connector with no approval gate

Why it matters: A connector that can modify the system of record unattended can do damage nobody notices for weeks.

Raw lines 181 to 184
185### Bad
187Build write access because the owner asked for it, with no gate.

Bad

Build write access because the owner asked for it, with no gate.

Raw lines 185 to 188
189### Good
191Every write is gated, and the gate states what will change:
193```
194This would mark WO-4471 complete and set the close date to today.
195Confirm?
196```
198This holds regardless of what the owner requested. It is not a preference.
200---

Good

Every write is gated, and the gate states what will change:

This would mark WO-4471 complete and set the close date to today.
Confirm?

This holds regardless of what the owner requested. It is not a preference.

Raw lines 189 to 201
202## Gotcha: a surprise Zapier bill
204**Why it matters:** Zapier bills per task. An owner who discovers a USD 70 monthly charge blames the integration, and they are right to.

Gotcha: a surprise Zapier bill

Why it matters: Zapier bills per task. An owner who discovers a USD 70 monthly charge blames the integration, and they are right to.

Raw lines 202 to 205
206### Bad
208Build the Zapier connection, mention nothing about cost.

Bad

Build the Zapier connection, mention nothing about cost.

Raw lines 206 to 209
210### Good
212```
213This runs through Zapier — about 40 tasks a day at your volume, which is
214their USD 30 tier. Fine if it's worth it, but worth knowing first.
215```
217---

Good

This runs through Zapier — about 40 tasks a day at your volume, which is
their USD 30 tier. Fine if it's worth it, but worth knowing first.
Raw lines 210 to 218
219## Gotcha: choosing clever over boring
221**Why it matters:** The owner cannot debug anything. A clever integration that breaks in November is worse than a dull one that never does.

Gotcha: choosing clever over boring

Why it matters: The owner cannot debug anything. A clever integration that breaks in November is worse than a dull one that never does.

Raw lines 219 to 222
223### Bad
225Build a screen-level workaround because it is more automatic than a weekly export.

Bad

Build a screen-level workaround because it is more automatic than a weekly export.

Raw lines 223 to 226
227### Good
229```
230I could automate this by driving their web interface, but it'd break any time
231they change the page and you'd get no warning.
233Can you export the CSV once a week instead? Less clever, still working next
234year.
235```
237Recommending the manual step is often the right call, and owners respect being told which is which.

Good

I could automate this by driving their web interface, but it'd break any time
they change the page and you'd get no warning.

Can you export the CSV once a week instead? Less clever, still working next
year.

Recommending the manual step is often the right call, and owners respect being told which is which.

Raw lines 227 to 237