hexbee/saas-agent-toolkit

SaaS Agent Toolkit

Overview

Use this skill when a user asks how to make a SaaS product "agent-usable" rather than only human-usable.

This skill reframes product capabilities into a stable execution model:

1. Connectors layer: auth and event plumbing
2. Tools layer: six reusable tool shapes
3. Policy layer: permissions, approvals, and reliability guardrails

Workflow

1. Scope target SaaS domain and entities.
2. Define the 3-layer architecture.
3. Map capabilities into the six tool shapes.
4. Add guardrails (auth, allowlists, idempotency, audit).
5. Produce a concrete rollout plan and KPI set.

Step 1: Scope Domain

Capture:

• Product/system (for example Zendesk, Salesforce, Jira, Notion)
• Core entities (ticket, contact, issue, page, deal, order)
• High-risk actions (payment, delete, external publish, permission change)
• Success outcome (speed, quality, cost, reliability)

Step 2: Build 3-Layer Architecture

Design these layers explicitly:

1. Connectors: OAuth/API key, webhook ingestion, identity mapping, optional SCIM.
2. Tools: Search, Summarize, Draft, Update, Notify, Approve.
3. Policy & Guardrails: RBAC, budgets, rate limits, PII controls, logging, retries.

Design principle: Prefer predictable, auditable, rollback-safe operations over "smart but opaque" behavior.

Step 3: Define Tool Contracts

Use six stable tool contracts:

1. Search: locate entities and relationships.
2. Summarize: produce structured, citation-backed takeaways.
3. Draft: generate submit-ready drafts without auto-sending.
4. Update: write bounded, idempotent changes back to systems.
5. Notify: close loops with owners/watchers/approvers.
6. Approve: enforce human gating for high-risk operations.

Read references/tool-contracts.md for function templates and I/O expectations.

Step 4: Add Mandatory Guardrails

Apply all of the following:

• Explicit error taxonomy (401, 403, 404, empty, conflict, timeout)
• Idempotency key for mutating actions
• Field allowlist for Update (no unrestricted patch)
• Citation requirement for Summarize
• Dry-run and draft-only defaults for user-facing output
• Approval gates for high-risk categories
• Full audit trail: who requested, who approved, what changed, when, result

Read references/approval-and-audit.md for standard approval and audit schema.

Step 5: Produce Deliverables

Return output in this structure:

1. Domain scope and entities
2. 3-layer architecture
3. Tool contract table (six tools)
4. Guardrail design
5. Example end-to-end workflow
6. Rollout plan (0-30, 31-90, 90+ days)
7. KPI table
8. Top unresolved risk

KPI minimums:

• task completion rate
• first-call success
• API success rate
• p95 latency
• integration lead time
• unit outcome cost

Example Workflow Patterns

Use references/workflow-patterns.md for ready-to-adapt flows:

• customer support triage and response
• sales follow-up automation
• incident assistant with approval-gated external updates