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

gotchas.md

204 lines · small-business/skills/build-agent/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 that produce a skill nobody uses, or one that does damage unattended.
4
5---
6

Gotchas

Failure modes that produce a skill nobody uses, or one that does damage unattended.

Raw lines 1 to 6
7## Gotcha: re-interviewing about a task they just walked through
8
9**Why it matters:** The owner spent twenty minutes doing the task with you. Opening with "so tell me about your process" says none of it was being paid attention to.

Gotcha: re-interviewing about a task they just walked through

Why it matters: The owner spent twenty minutes doing the task with you. Opening with "so tell me about your process" says none of it was being paid attention to.

Raw lines 7 to 10
11### Bad
13```
14Owner: "That was great — can you remember how to do that?"
15Claude: "Sure! Let's start by understanding your workflow. What systems do
16 you use for commission data?"
17```

Bad

Owner: "That was great — can you remember how to do that?"
Claude: "Sure! Let's start by understanding your workflow. What systems do
        you use for commission data?"
Raw lines 11 to 18
19### Good
21```
22Claude: "Here's what I think this is: [the sequence, the rules picked up from
23 the corrections]. Right?"
24```
26The transcript is the specification. The corrections are the business rules.
28---

Good

Claude: "Here's what I think this is: [the sequence, the rules picked up from
        the corrections]. Right?"

The transcript is the specification. The corrections are the business rules.

Raw lines 19 to 29
30## Gotcha: hardcoding the example
32**Why it matters:** A skill built around last Tuesday works exactly once. The owner runs it next month, gets nonsense, and never opens it again.

Gotcha: hardcoding the example

Why it matters: A skill built around last Tuesday works exactly once. The owner runs it next month, gets nonsense, and never opens it again.

Raw lines 30 to 33
34### Bad
36```
37Pull the Continental commission file for June and match against the
3834 policies booked.
39```

Bad

Pull the Continental commission file for June and match against the
34 policies booked.
Raw lines 34 to 40
41### Good
43```
44Pull the current month's carrier commission file from the statement email.
45Match every line against policies booked in the CRM for that period.
46```
48Fixed: the sequence, the sources, the rules. Varies: the month, the carrier, the counts.
50---

Good

Pull the current month's carrier commission file from the statement email.
Match every line against policies booked in the CRM for that period.

Fixed: the sequence, the sources, the rules. Varies: the month, the carrier, the counts.

Raw lines 41 to 51
52## Gotcha: gating every step
54**Why it matters:** A skill that asks nine times is slower than doing the task manually. The owner stops running it and cannot articulate why.

Gotcha: gating every step

Why it matters: A skill that asks nine times is slower than doing the task manually. The owner stops running it and cannot articulate why.

Raw lines 52 to 55
56### Bad
58Approval before pulling the file, before matching, before flagging, before drafting, before each email.

Bad

Approval before pulling the file, before matching, before flagging, before drafting, before each email.

Raw lines 56 to 59
60### Good
62Gate the sends and the ambiguous judgment calls. Let reading, matching, computing, and drafting run:
64```
656 chase emails, one per carrier, USD 2,340 in discrepancies, from your address.
66Send them?
67```
69One gate, at the consequential moment.
71---

Good

Gate the sends and the ambiguous judgment calls. Let reading, matching, computing, and drafting run:

6 chase emails, one per carrier, USD 2,340 in discrepancies, from your address.
Send them?

One gate, at the consequential moment.

Raw lines 60 to 72
73## Gotcha: a vague gate
75**Why it matters:** "Ready to proceed?" asks the owner to approve something invisible. The first time it goes wrong, every gate in the plugin loses credibility.

Gotcha: a vague gate

Why it matters: "Ready to proceed?" asks the owner to approve something invisible. The first time it goes wrong, every gate in the plugin loses credibility.

Raw lines 73 to 76
77### Bad
79```
80I've prepared the emails. Ready to proceed?
81```

Bad

I've prepared the emails. Ready to proceed?
Raw lines 77 to 82
83### Good
85State the count, the recipients, the amounts, and the account it sends from. Consent needs to be informed to be worth anything.
87---

Good

State the count, the recipients, the amounts, and the account it sends from. Consent needs to be informed to be worth anything.

Raw lines 83 to 88
89## Gotcha: skipping the test run
91**Why it matters:** An owner who hasn't seen the skill reproduce a known-good answer will check its output manually every time. That saves nothing, and eventually they stop running it.

Gotcha: skipping the test run

Why it matters: An owner who hasn't seen the skill reproduce a known-good answer will check its output manually every time. That saves nothing, and eventually they stop running it.

Raw lines 89 to 92
93### Bad
95Build it, register it, tell them it's ready.

Bad

Build it, register it, tell them it's ready.

Raw lines 93 to 96
97### Good
99Run it against the case they walked through, and show both:
101```
102Ran it on June's file — the one you just did by hand.
104Found the same 6 discrepancies, same amounts. It also flagged a 7th at USD 61
105on the Meridian file that you skipped. Was that deliberate, or worth adding
106to the rules?
107```
109That last question is how the skill gets a rule it was missing.
111---

Good

Run it against the case they walked through, and show both:

Ran it on June's file — the one you just did by hand.

Found the same 6 discrepancies, same amounts. It also flagged a 7th at USD 61
on the Meridian file that you skipped. Was that deliberate, or worth adding
to the rules?

That last question is how the skill gets a rule it was missing.

Raw lines 97 to 112
113## Gotcha: generic business language
115**Why it matters:** A skill written in vocabulary the owner doesn't use feels like it belongs to someone else. They won't trust it to run unattended, which was the whole point.

Gotcha: generic business language

Why it matters: A skill written in vocabulary the owner doesn't use feels like it belongs to someone else. They won't trust it to run unattended, which was the whole point.

Raw lines 113 to 116
117### Bad
119```
120Reconcile revenue recognition variances against booked commitments.
121```

Bad

Reconcile revenue recognition variances against booked commitments.
Raw lines 117 to 122
123### Good
125```
126Match the carrier file against what's booked and flag anything off by more
127than USD 5.
128```
130---

Good

Match the carrier file against what's booked and flag anything off by more
than USD 5.
Raw lines 123 to 131
132## Gotcha: a shared skill that sends
134**Why it matters:** A skill that emails customers, run by someone who didn't build it and doesn't know its assumptions, is a genuine hazard. The owner sharing it is not thinking about that.

Gotcha: a shared skill that sends

Why it matters: A skill that emails customers, run by someone who didn't build it and doesn't know its assumptions, is a genuine hazard. The owner sharing it is not thinking about that.

Raw lines 132 to 135
136### Bad
138```
139Shared with your team.
140```

Bad

Shared with your team.
Raw lines 136 to 141
142### Good
144```
145Sharing this with Teri and Marcus. Worth knowing: it sends email from
146whoever runs it, and it assumes the USD 50 skip rule you set.
148Recommend I set it to draft-only for them — they'd review and send rather
149than it going out automatically. Your call.
150```
152---

Good

Sharing this with Teri and Marcus. Worth knowing: it sends email from
whoever runs it, and it assumes the USD 50 skip rule you set.

Recommend I set it to draft-only for them — they'd review and send rather
than it going out automatically. Your call.
Raw lines 142 to 153
154## Gotcha: building a skill that already exists
156**Why it matters:** A duplicate clutters the router, competes for triggers with the shipped skill, and will be maintained by nobody.

Gotcha: building a skill that already exists

Why it matters: A duplicate clutters the router, competes for triggers with the shipped skill, and will be maintained by nobody.

Raw lines 154 to 157
158### Bad
160Build "chase unpaid invoices" from scratch.

Bad

Build "chase unpaid invoices" from scratch.

Raw lines 158 to 161
162### Good
164```
165This is close to what `invoice-chase` already does. Want me to check whether
166it covers your case before we build something new?
167```
169---

Good

This is close to what `invoice-chase` already does. Want me to check whether
it covers your case before we build something new?
Raw lines 162 to 170
Names a skill invoice-chase :165
171## Gotcha: one skill that's really four
173**Why it matters:** A skill covering an entire month-end process breaks in ways that are hard to isolate, and a skill the owner can't debug is one they abandon.

Gotcha: one skill that's really four

Why it matters: A skill covering an entire month-end process breaks in ways that are hard to isolate, and a skill the owner can't debug is one they abandon.

Raw lines 171 to 174
175### Bad
177Accept "automate my month-end" as a single skill.

Bad

Accept "automate my month-end" as a single skill.

Raw lines 175 to 178
179### Good
181Name the split and start with the heaviest piece:
183```
184That's three things: reconciling, chasing the gaps, and writing the summary.
185Want to start with the reconciliation? It's the part that takes longest, and
186the others get easier once it exists.
187```
189---

Good

Name the split and start with the heaviest piece:

That's three things: reconciling, chasing the gaps, and writing the summary.
Want to start with the reconciliation? It's the part that takes longest, and
the others get easier once it exists.
Raw lines 179 to 190
191## Gotcha: no fallback
193**Why it matters:** A skill that requires a connector the owner might lose access to is a skill that breaks silently. This audience changes tools constantly.

Gotcha: no fallback

Why it matters: A skill that requires a connector the owner might lose access to is a skill that breaks silently. This audience changes tools constantly.

Raw lines 191 to 194
195### Bad
197The skill assumes the carrier portal connector exists.

Bad

The skill assumes the carrier portal connector exists.

Raw lines 195 to 198
199### Good
201```
202No connector for your carrier portal. Forward me the monthly statement and
203I'll do the rest — same output, one extra step.
204```

Good

No connector for your carrier portal. Forward me the monthly statement and
I'll do the rest — same output, one extra step.
Raw lines 199 to 204