Creates user-specific one-click action templates that execute email operations when clicked in the chat interface. Use when user wants reusable actions for their specific workflows (send payment reminder to ACME Corp, forward bugs to engineering, archive old newsletters from specific sources).
Creates user-specific one-click action templates that execute email operations when clicked in the chat interface. Use when user wants reusable actions for their specific workflows (send payment reminder to ACME Corp, forward bugs to engineering, archive old newsletters from specific sources).
allowed-tools
Write, Edit, Read, Glob
Action Creator
Creates TypeScript action template files that define reusable, user-specific operations users can execute with one click in the chat interface.
When to Use This Skill
Use this skill when the user wants to:
Create reusable actions for their specific workflows ("I often need to send payment reminders to ACME Corp")
Set up one-click operations for their vendors/customers ("Forward bugs to engineering team")
Automate repetitive email tasks with their specific context ("Archive newsletters from TechCrunch/Morning Brew")
Build personalized email management tools for their business processes
Key difference from listeners: Actions are user-triggered (clicked in chat), while listeners are event-triggered (automatic).
How Actions Work
Actions are TypeScript files in agent/custom_scripts/actions/ that:
Export a config object defining the template metadata and parameter schema
Export a handler function that executes the operation with given parameters
Use ActionContext methods to perform operations (email API, send emails, call AI, etc.)
The agent creates action instances during conversation by providing specific parameters to these templates, which appear as clickable buttons in the chat.
Creating an Action Template
1. Understand User-Specific Workflow
Parse the user's request to identify:
User context: Who are their specific vendors/customers/teams?
Operation: What specific action do they need? (send to ACME Corp, forward to engineering team, etc.)
Parameters: What varies per execution? (invoice number, priority level, days old)
Frequency: How often will they use this?
2. Write the Action Template File
Create a file in agent/custom_scripts/actions/ with this structure:
Idempotency: Design handlers to be safely re-runnable when possible
Logging: Use context.log() for debugging and audit trail
Parameter Schema Guidelines
Define parameters using JSON Schema:
parameterSchema: {
type: "object",
properties: {
// String parameteremailId: {
type: "string",
description: "Email ID to process"
},
// Number parameter with defaultdaysOld: {
type: "number",
description: "Number of days old",
default: 30
},
// Enum parameter (dropdown)priority: {
type: "string",
description: "Priority level",
enum: ["P0 - Critical", "P1 - High", "P2 - Medium", "P3 - Low"]
},
// Boolean parametersendNotification: {
type: "boolean",
description: "Send notification when complete"
}
},
required: ["emailId", "priority"] // List required params
}
Creating the File
When the user requests an action template:
Clarify user-specific context:
Who are their vendors/customers/teams?
What are their specific workflows?
What parameters vary per execution?
Write the TypeScript file in agent/custom_scripts/actions/
Use Write tool to create the file with:
Proper imports from "../types"
User-specific config (not generic)
Parameter schema with all required fields
Handler with error handling
Clear success/failure messages
Test parameters: Ensure all required parameters are defined
Confirm with user that the action matches their workflow
Common Patterns
1. Send Email to Specific Recipient
User-specific → Compose email with template → Send → Return result
const body = `Hi ${recipientName},
Your invoice ${invoiceNumber} for ${amount} is ${daysPastDue} days past due...`;
await context.sendEmail({
to: "accounts.payable@acmecorp.com",
subject: `Payment Reminder: Invoice ${invoiceNumber}`,
body
});
2. Bulk Email Operation
Search emails → Filter → Apply operation to each → Return count
importtype { ActionTemplate, ActionContext, ActionResult } from"../types";
// ActionTemplate: Template metadata and parameter schema// ActionContext: Runtime context with all capabilities// ActionResult: Return type for handler function
How Users Trigger Actions
After you create an action template:
Agent discovers template: During conversation, agent reads available actions
Agent creates instance: Agent provides specific parameters for user's situation
User sees button: Action instance appears as clickable button in chat
User clicks: Action executes with pre-filled parameters
Result appears: Success/failure message shown in chat
Example flow:
User: "I need to follow up on the ACME invoice"
Agent: [searches emails, finds Invoice #2024-001 is 15 days overdue]
Agent: Creates action instance with parameters:
{
templateId: "send_payment_reminder_acme",
params: { invoiceNumber: "INV-2024-001", amount: "$5,000", daysPastDue: 15 }
}
User: [sees button "Send payment reminder to ACME Corp for Invoice #2024-001"]
User: [clicks button]
Action: Executes, sends email, returns "Payment reminder sent to ACME Corp"
Reference
Full specification: See project root ACTIONS_SPEC.md for complete details on:
