playbooks

home / skills / hexbee / hello-skills / saas-agent-toolkit

saas-agent-toolkit skill

/skills/saas-agent-toolkit

This skill helps design agent-usable SaaS tool systems by mapping capabilities to six reusable tool shapes and enforcing guardrails.

npx playbooks add skill hexbee/hello-skills --skill saas-agent-toolkit

Review the files below or copy the command above to add this skill to your agents.

Files (6)
SKILL.md
3.3 KB
---
name: saas-agent-toolkit
description: Design agent-usable SaaS tool systems using six reusable tool shapes (Search, Summarize, Draft, Update, Notify, Approve) plus connectors and policy guardrails. Use when turning SaaS features into reliable agent actions with clear contracts, permissions, audit trails, and approval gates.
---

# 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

Overview

This skill frames how to turn a SaaS product into reliable, agent-usable actions using a repeatable three-layer architecture and six reusable tool shapes. It focuses on clear contracts, connectors for auth/events, and policy guardrails so agents operate with predictable permissions, audits, and approval gates. Use it to design safe, testable agent integrations rather than ad-hoc automation.

How this skill works

Inspect the target SaaS domain and map core entities and high-risk actions. Define a connectors layer (auth, webhooks, identity), a tools layer composed of six stable contracts (Search, Summarize, Draft, Update, Notify, Approve), and a policy layer for RBAC, rate limits, and audit trails. Produce concrete deliverables: domain scope, tool contract table, guardrail design, rollout plan, and KPIs for monitoring.

When to use it

  • When you need agents to take actions in a SaaS product rather than only humans.
  • When building secure, auditable automation that must meet compliance and approval requirements.
  • When standardizing agent interactions across multiple integrations or teams.
  • When converting human workflows into predictable API-driven steps.
  • When you need clear rollback, idempotency, and observability for mutating operations.

Best practices

  • Design explicit tool contracts with input/output schemas and error codes.
  • Use connectors to centralize auth, event ingestion, and identity mapping.
  • Enforce guardrails: idempotency keys, field allowlists, error taxonomy, and audit logs.
  • Default to dry-run or draft-only for user-facing mutations; require approval for high-risk actions.
  • Measure and iterate using a small KPI set (completion rate, API success rate, p95 latency).

Example use cases

  • Customer support triage: Search tickets, Summarize history, Draft responses, Notify owners, Approve escalations.
  • Sales follow-up: Search contacts, Draft outreach, Update CRM records, Notify reps on positive signals.
  • Incident response: Search incidents, Summarize impacts with citations, Draft external communications, Approve and publish with audit trail.
  • Billing or permission changes: Gate Update operations behind Approve tool and RBAC with full auditability.

FAQ

What are the six tool shapes and why use them?

Search, Summarize, Draft, Update, Notify, Approve provide a minimal, stable vocabulary for agent actions. They separate read-only discovery, structured summarization, safe content creation, bounded mutations, communication, and human gating for risk control.

How do I handle high-risk mutating actions?

Classify high-risk categories up front, require Approval gates, use idempotency keys, field allowlists, dry-run defaults, and enforce RBAC and audit logs before enabling live mutations.