bbc-skill-tool

Builds, manages, and troubleshoots WhatsApp bots using the BuilderBot Cloud (BBC) MCP Tool v2.0. Covers bot creation for businesses needing appointment booki...

Security Scan

The skill's instructions and artifacts are generally consistent with a BuilderBot Cloud (BBC) MCP tool for building WhatsApp bots, but there are a few omissions and data-flow risks you should understand before installing.

Purpose & Capability

The name/description match the SKILL.md: it documents creating, updating, validating, and deploying BBC WhatsApp bots and references builderbot_* tool calls. One minor mismatch: the skill never declares required BBC/API credentials or environment variables even though it references cloud operations (create/deploy/validate). That could be fine if the agent platform provides the builderbot tool bindings, but it's an omission worth clarifying.

Instruction Scope

Instructions are detailed and generally scoped to bot lifecycle, safety gates, verification, and recovery. They also describe patterns that capture user data and send it to external HTTP endpoints (add_http), and instruct scraping website content into the bot's knowledge base (scrapeUrl). These behaviors are expected for bot integrations but do enable transmitting user conversation data and scraped content to arbitrary endpoints—review webhook URLs and data handling policies before use.

Install Mechanism

Instruction-only skill with no install spec and no code files — low install risk. Nothing is downloaded or written to disk by the skill package itself.

Credentials

The skill declares no required env vars or credentials. That is proportionate only if the runtime environment/agent already supplies the BBC builderbot tools and credentials. If those are not provided by the platform, the lack of declared credentials is confusing. Also, the documented add_http and scrapeUrl patterns imply sending captured user data to external endpoints — such webhooks may require secrets or auth and can exfiltrate PII if misconfigured.

Persistence & Privilege

No special persistence requested (always: false). Model-invocation is allowed (platform default). The skill does not request to modify other skills or system-wide settings in the provided files.

Assessment

This skill appears to be what it says: a detailed instruction set for using the BBC MCP Tool to build WhatsApp bots. Before installing, ask the publisher/platform: (1) Where do the referenced builderbot_* tools run and how are BBC/API credentials provided? (2) Which endpoints (webhooks/scrape targets) will the skill actually call in your environment? The SKILL.md shows patterns that capture user data and POST it to arbitrary URLs and that scrape websites into the bot knowledge base — both can transmit sensitive data. If you will use webhooks, lock them to trusted endpoints, audit what data is captured (PII risk), and enforce explicit user confirmation for destructive actions (the skill already recommends gating). If you want lower risk, restrict autonomous invocation for this skill until you confirm platform bindings and webhook policies. Finally, verify that deployments (deploy/delete/reboot) act only on your intended BBC projects and that proper RBAC/credentials are in place.

BBC MCP Tool v2.0 — Safe-by-Default WhatsApp Bot Builder

CORE PHILOSOPHY

v2.0 = v1 + Safety. Same tools, same BBC API, but with mandatory patterns that prevent the silent failures, accidental deletions, and unvalidated deploys that plagued v1.

Three pillars:

1. VERIFY — After every mutating operation, call the corresponding list_* to confirm
2. GATE — Before every destructive operation, show impact and require explicit "yes"
3. RECOVER — When something fails, diagnose why and propose a fix, never just stop

---

TOOL REFERENCE (Quick)

Tool	Purpose	Mutating?
builderbot_list_projects	List all projects	No
builderbot_create_project	Create project	Yes
builderbot_list_flows	List flows in project	No
builderbot_create_flow	Create flow with keywords	Yes
builderbot_update_flow	Update flow config	Yes
builderbot_delete_flow	Delete flow + all answers	Yes (DESTRUCTIVE)
builderbot_list_answers	List answers in flow	No
builderbot_create_answer	Add answer to flow	Yes
builderbot_update_answer	Update answer content	Yes
builderbot_delete_answer	Delete single answer	Yes (DESTRUCTIVE)
builderbot_validate_bot	Health check before deploy	No
builderbot_deploy	Deploy/status/QR/reboot/delete	Yes (some actions)

---

MANDATORY PATTERNS

Pattern 1: VERIFY after every mutation

After ANY create/update/delete, call the corresponding list_* tool to confirm:

create_flow(projectId, ...) → list_flows(projectId) → search for the new flow
create_answer(...)          → list_answers(projectId, flowId) → search for new answer
update_answer(...)          → list_answers(projectId, flowId) → confirm content changed
delete_flow(...)            → list_flows(projectId) → confirm flow is gone

If verification fails: STOP, report the discrepancy, diagnose, and propose recovery.

Pattern 2: GATE before destructive actions

Before delete_flow, delete_answer, or deploy(action='delete'):

1. Show what will be affected (flow name, answer count, references)
2. Show a clear warning: "⚠️ This cannot be undone"
3. Wait for explicit user confirmation
4. After execution, VERIFY the deletion
5. Run validate_bot to check for broken references

Pattern 3: RECOVER on failure

When any operation fails or verification shows a discrepancy:

1. Diagnose: Check limits (flow count), conflicts (duplicate keywords), permissions
2. Report: Tell user exactly what went wrong
3. Propose: Offer concrete fix (delete unused flow, rename keyword, retry)
4. Execute: Fix with user approval, then VERIFY

---

FLOW CREATION RULES

create_flow parameters

projectId:        UUID (from list_projects)
name:             "Human Readable Name" (Title Case, user's language)
label:            "snake_case_slug" (lowercase, no spaces)
keywords:         ["keyword1", "keyword2"] or ["EVENTS.WELCOME"]
listenKeywords:   false (ALWAYS false unless EVENTS.VOICE_NOTE)
transcribeAudio:  true only for EVENTS.VOICE_NOTE
interpretImage:   true only for EVENTS.MEDIA
analyzeDocument:  true only for EVENTS.DOCUMENT

CRITICAL RULES

• listenKeywords MUST be false for ALL flows EXCEPT EVENTS.VOICE_NOTE
• A new flow has 0 answers — the bot will NOT respond until you add answers
• Always add answers IMMEDIATELY after creating a flow
• Text keywords must be UNIQUE across all flows
• System events (EVENTS.*) must not be mixed with text keywords
• Each EVENTS.* can appear in only ONE flow

System Events Reference

Event	Use case	Required flags
EVENTS.WELCOME	Catch-all / fallback	listenKeywords: false
EVENTS.VOICE_NOTE	Voice message handler	listenKeywords: true, transcribeAudio: true
EVENTS.MEDIA	Image handler	interpretImage: true
EVENTS.DOCUMENT	Document handler	analyzeDocument: true
EVENTS.LOCATION	Location shared	—
EVENTS.ACTION	Button/list response	—

---

ANSWER TYPES REFERENCE

add_text — Simple text message

type: "add_text"
message: "Your text here"  ← MAX 160 chars for WhatsApp

add_chatpdf — AI-powered assistant (Pattern 2)

type: "add_chatpdf"
message: ""  ← MUST be empty string

CRITICAL: NEVER mix add_chatpdf with add_text in the same flow. Both fire on every message → broken double-response loop. A flow with add_chatpdf must contain ONLY the add_chatpdf answer.

After creating, configure via update_answer with assistant field:

assistant: {
  instructions: "You are a helpful assistant for [business]...",
  model: "gpt-5.4-nano"  (optional)
}

add_image / add_video / add_doc / add_voice_note — Media

type: "add_image"
message: ""
options: { media: { url: "https://public-url.com/image.jpg" }, gotoFlow: {} }

add_http — HTTP webhook/API call

type: "add_http"
message: ""
plugins: {
  http: {
    url: "https://api.example.com/endpoint",
    method: "GET" | "POST",
    headers: { "Content-Type": "application/json" },  // optional
    body: { key: "value" },  // optional, for POST
    rules: []  // REQUIRED — always include, even if empty
  }
}

CRITICAL: plugins.http.rules is REQUIRED. Omitting it causes backend rejection.

add_mute — Mute contact (human handoff)

type: "add_mute"
plugins: { mute: { status: true, gapTime: 60 } }
options: { gotoFlow: { flowId: "farewell-flow-uuid" } }

Mutes the INDIVIDUAL contact, not the whole bot. gapTime = minutes until auto-unmute.

add_intent — AI semantic routing

type: "add_intent"
plugins: {
  intent: {
    rules: [{
      conditionRule: "The user wants to talk to a human",
      conditionFlowId: "<target-flow-uuid>",
      condition: "",
      conditionValue: ""
    }]
  }
}

Capture rule

options.capture = true → bot waits for user reply, passes it to NEXT answer. NEVER set capture=true on the LAST answer of a flow — value is silently lost.

Redirect

options.gotoFlow = { flowId: "<target-flow-uuid>" } → redirect after this answer.

---

DECISION TREE: Which Pattern to Use

User request → What type of business?
├── Needs appointments/citas/availability → Pattern 2 (AI) ★ RECOMMENDED
├── Needs Q&A about products/services    → Pattern 2 (AI)
├── Needs order tracking/status          → Pattern 2 (AI) + HTTP
├── Simple info (hours, location, menu)  → Pattern 1 (keyword-based) OK
├── Lead generation / qualification      → Pattern 2 (AI) + capture
└── Human handoff / escalation           → Pattern 2 (AI) + mute

DEFAULT: Pattern 2 (AI-powered with add_chatpdf) for 80% of real cases. Only use pure keyword → text flows for very simple, static information.

---

PATTERN TEMPLATES BY VERTICAL

Salon / Beauty / Services

• WELCOME: add_chatpdf with instructions about services, prices, availability
• AI instructions must include: services list, hours, booking guidance, escalation trigger
• Escalation flow: add_mute + human handoff
• Knowledge base: scrape website with assistant.scrapeUrl

Restaurant / Food

• WELCOME: add_chatpdf with menu, hours, delivery info
• Order flow: capture address + items via AI
• Location flow: add_text with Google Maps link

E-commerce / Store

• WELCOME: add_chatpdf with catalog, pricing, shipping
• Order status: add_http to check order API
• Support escalation: add_mute

Content Creator / Digital Products

• WELCOME: add_chatpdf with product catalog, pricing
• Purchase flow: redirect to payment link
• Support: AI handles FAQ, escalates complex issues

Forum / Event

• WELCOME: add_chatpdf with event details, schedule, registration
• Registration: capture data + add_http to registration API

---

COMPLETE WORKFLOW: Building a Bot

Step 1: Get or Create Project

list_projects()
├── Project exists → use its projectId
└── Need new → create_project(name) → list_projects() → VERIFY

Step 2: Plan Flows

Before creating anything, plan all flows and share the plan with user:

📋 Bot Plan: [Business Name]
├── welcome (EVENTS.WELCOME) — AI assistant with business context
├── escalation (keyword: "agente", "humano") — Human handoff
├── [additional flows based on business needs]
└── Total: N flows

Step 3: Create Flows (one at a time)

For EACH flow:

1. create_flow(projectId, name, label, keywords, ...)
2. list_flows(projectId) → VERIFY flow exists, get flow_id
3. create_answer(projectId, flowId, type, message, ...)
4. list_answers(projectId, flowId) → VERIFY answer exists
5. [If add_chatpdf] update_answer(answerId, assistant: { instructions: "..." })
6. list_answers(projectId, flowId) → VERIFY instructions set

NEVER create all flows first then add answers. Create flow → add answers → verify → next flow.

Step 4: Validate

validate_bot(projectId)
├── criticalCount = 0 → Ready to deploy
└── criticalCount > 0 → Fix issues first
    ├── Dead ends → add answers to empty flows
    ├── Long messages → shorten to ≤160 chars
    ├── Dangling capture → remove capture from last answer
    └── Missing WELCOME → create welcome flow

Step 5: Deploy (with GATE)

1. validate_bot(projectId) → MUST pass (criticalCount = 0)
2. Show deployment summary to user:
   ┌─────────────────────────────┐
   │ 📤 DEPLOY SUMMARY          │
   │ Project: [name]            │
   │ Flows: N                    │
   │ Answers: M                  │
   │ Validation: ✅ PASS        │
   │ Confirm? [yes/no]          │
   └─────────────────────────────┘
3. Wait for user confirmation
4. deploy(projectId, action: "create")
5. deploy(projectId, action: "status") → check status
6. If READY_TO_SCAN → deploy(projectId, action: "qr") → show QR

---

ERROR HANDLING FRAMEWORK

Common Failures & Recovery

Error	Diagnosis	Recovery
Flow created but not in list	Silent failure / API lag	Retry create, verify again
"Limit reached"	50/50 flows used	List flows, find unused, offer to delete
Duplicate keyword	Keyword conflict	list_flows to find conflict, rename
Answer > 160 chars	WhatsApp truncation	Shorten message, verify
Deploy fails	Validation issues	Run validate_bot, fix all criticals
add_chatpdf + add_text in same flow	Double-response bug	Delete the add_text answer
capture=true on last answer	Dangling capture	Remove capture or add follow-up answer

Batch Operations: Sequential with Verification

When creating multiple flows, ALWAYS do them sequentially:

FOR EACH flow in plan:
  1. create_flow → VERIFY
  2. create_answer(s) → VERIFY each
  3. [configure AI if needed] → VERIFY
  THEN next flow

NEVER batch-create all flows then batch-add answers. This hides partial failures.

---

FINAL REPORT FORMAT

After completing bot creation, always provide:

📊 BOT REPORT: [Project Name]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Project ID: [uuid]

✅ Flows Created:
  1. [flow_name] (id: [uuid]) — [N] answers — [type summary]
  2. ...

⚠️ Issues Fixed:
  • [description of any issues encountered and resolved]

🔍 Validation: [PASS/FAIL]
  • Criticals: 0
  • Warnings: [N]

📤 Deploy Status: [DEPLOYED / NOT YET / READY_TO_SCAN]

🔗 Tool Call Trace:
  [list of all tool calls made in order]

---

ANTI-PATTERNS (Never Do These)

1. ❌ Creating a flow without immediately adding answers
2. ❌ Reporting success without verification (list_*)
3. ❌ Deleting without showing impact and getting confirmation
4. ❌ Deploying without running validate_bot first
5. ❌ Mixing add_chatpdf and add_text in the same flow
6. ❌ Setting listenKeywords: true on non-VOICE_NOTE flows
7. ❌ Setting capture: true on the last answer of a flow
8. ❌ Batch-creating all flows before adding answers
9. ❌ Ignoring validation warnings about message length (>160 chars)
10. ❌ Creating add_http answers without plugins.http.rules: []

---

REFERENCES

For vertical-specific templates and advanced patterns, read:

• references/verticals.md — Detailed bot templates per business type
• references/advanced-patterns.md — HTTP integrations, multi-flow routing, knowledge base setup