/action-creator

name: action-creator
description: 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: 1. Export a `config` object defining the template metadata and parameter schema 2. Export a `handler` function that executes the operation with given parameters 3. 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:

import type { ActionTemplate, ActionContext, ActionResult } from "../types";

export const config: ActionTemplate = {
  id: "unique_action_id",                    // kebab-case, user-specific
  name: "Human Readable Name",                // For UI display
  description: "What this action does",       // Explain the operation
  icon: "📨",                                 // Optional emoji icon
  parameterSchema: {
    type: "object",
    properties: {
      paramName: {
        type: "string",                      // or "number", "boolean"
        description: "Parameter description",
        enum: ["option1", "option2"],        // Optional: restrict values
        default: "defaultValue"              // Optional: default value
      }
    },
    required: ["paramName"]                  // List required parameters
  }
};

export async function handler(
  params: Record<string, any>,
  context: ActionContext
): Promise<ActionResult> {
  const { paramName } = params;

  context.log(`Starting action: ${config.name}`);

  try {
    // 1. Perform operations using context methods
    // 2. Use AI for intelligent processing if needed
    // 3. Update emails, send emails, etc.

    context.notify("Action completed successfully", {
      type: "success",
      priority: "normal"
    });

    return {
      success: true,
      message: "Action completed successfully",
      data: { /* optional structured data */ },
      refreshInbox: true  // Optional: refresh inbox after action
    };
  } catch (error: any) {
    context.log(`Action failed: ${error}`, "error");
    return {
      success: false,
      message: `Failed: ${error.message}`
    };
  }
}

3. File Naming Convention

Use kebab-case that reflects the **user-specific** operation:

• `send-payment-reminder-to-acme.ts` (not `send-email.ts`)
• `forward-bugs-to-engineering.ts` (not `forward-email.ts`)
• `archive-newsletters-from-techcrunch.ts` (not `archive-emails.ts`)
• `summarize-weekly-updates-from-ceo.ts` (not `summarize-emails.ts`)

**Important**: Templates should be specific to the user's actual workflows, vendors, teams, and processes.

4. Available Context Methods

The `ActionContext` provides these capabilities:

// Email API operations
const emails = await context.emailAPI.getInbox({ limit: 30, includeRead: false });
const results = await context.emailAPI.searchEmails({ from: "sender@example.com" });
const results = await context.emailAPI.searchWithGmailQuery("from:sender after:2024/01/01");
const emails = await context.emailAPI.getEmailsByIds(["id1", "id2"]);
const email = await context.emailAPI.getEmailById("email-id");

// Direct email operations
await context.archiveEmail(emailId);
await context.starEmail(emailId);
await context.unstarEmail(emailId);
await context.markAsRead(emailId);
await context.markAsUnread(emailId);
await context.addLabel(emailId, "label-name");
await context.removeLabel(emailId, "label-name");

// Send emails
const result = await context.sendEmail({
  to: "recipient@example.com",
  subject: "Email subject",
  body: "Email body content",
  cc: "cc@example.com",           // Optional
  bcc: "bcc@example.com",          // Optional
  replyTo: "reply@example.com"     // Optional
});

// AI-powered processing
const analysis = await context.callAgent<ResultType>({
  prompt: "Analyze this email and extract key info...",
  systemPrompt: "You are an expert at...",  // Optional
  tools: ["Read", "WebSearch"],              // Optional
  maxTokens: 2000                            // Optional
});

// Session messaging (inject into chat)
context.addUserMessage("User said this");
context.addAssistantMessage("Assistant responds");
context.addSystemMessage("System notification");

// Notifications
context.notify("Operation completed", {
  priority: