Skills
skills/ken-cavanagh-glean/fieldkit/agent-spec-generator

agent-spec-generator

SKILL.md

Agent Spec Generator

Generate complete, importable specifications for Glean Agent Builder.

What This Skill Does

  1. Interview — Gather requirements through structured questions
  2. Design — Map requirements to agent architecture (steps, tools, fields)
  3. Generate — Output valid JSON matching Glean's export schema
  4. Document — Create human-readable markdown spec

Quick Start

When the user asks to create an agent, follow this flow:

Phase 1: Discovery

Ask these questions to understand the agent (use the AskUserQuestion tool to guide the user):

1. **Purpose**: What problem does this agent solve? What task does it complete?
2. **Audience**: Who will use this agent? (Role, department)
3. **Trigger**: How should it start? (Manual form, scheduled, Slack command, webhook)
4. **Inputs**: What information does the user provide? (Text fields, dates, file uploads, entity selections)
5. **Data Sources**: What does the agent need to read? (Gong, Slack, Email, Salesforce, specific docs)
6. **Process**: What steps should it take? Walk me through the workflow.
7. **Output**: What should the final response look like? (Report, summary, table, action taken)
8. **Actions**: Should it take actions? (Send Slack DM, create Jira ticket, draft email)

Phase 2: Architecture

Map requirements to agent structure:

  1. Decompose into steps — Each distinct operation becomes a step
  2. Identify dependencies — Which steps need output from previous steps?
  3. Select tools — Match each step to the right tool (see Tools Catalog)
  4. Define fields — Map inputs to field types
  5. Configure triggers — Set up the trigger type

Phase 3: Generate

Output two artifacts:

  1. JSON Specification — Valid rootWorkflow object for import
  2. Markdown Documentation — Human-readable spec for review

JSON Schema Reference

See references/schema.md for the complete schema.

Minimal Agent Structure

{
  "rootWorkflow": {
    "name": "Agent Name",
    "description": "What this agent does",
    "icon": {
      "backgroundColor": "var(--theme-brand-light-blue-50)",
      "color": "#333",
      "iconType": "GLYPH",
      "name": "rocket-2"
    },
    "schema": {
      "goal": "High-level objective",
      "steps": [],
      "fields": [],
      "modelOptions": {
        "llmConfig": {
          "provider": "OPEN_AI",
          "model": "GPT41_20250414"
        }
      },
      "trigger": {
        "type": "INPUT_FORM",
        "config": {
          "inputForm": {
            "scheduleConfig": {}
          }
        }
      }
    }
  }
}

Step Types

Type When to Use Key Config
TOOL Execute a single tool or action toolConfig[]
AGENT Call another agent as a sub-workflow runAgentConfig, agent ID
BRANCH Conditional logic (if/else) branchConfig: { branches[], default }
LOOP Iterate over a collection loopConfig: { inputStepDependency }
PARALLEL Multiple tools in one step Multiple toolConfig entries

Step Template

{
  "id": "unique-step-id",
  "instructionTemplate": "Prompt with [[variable]] or [[previous-step-id]] references",
  "type": "TOOL",
  "stepDependencies": ["previous-step-id"],
  "toolConfig": [
    {
      "id": "Tool Name",
      "respondConfig": { "temperature": "FACTUAL" }
    }
  ],
  "modelOptions": {
    "llmConfig": {
      "provider": "VERTEX_AI",
      "model": "GEMINI_3_0"
    }
  },
  "memoryConfig": "ALL_DEPENDENCIES"
}

Field Types

Type JSON Use Case
Text { "type": "TEXT" } Freeform input
Select { "type": "SELECT" } + options[] Dropdown
Multi-Select { "type": "MULTI_SELECT" } Multiple choices
Number { "type": "NUMBER" } Numeric input
Date { "type": "DATE" } Date picker
Boolean { "type": "BOOLEAN" } Toggle
File { "type": "FILE" } File upload
Entity { "type": "ENTITY" } Person/Team autocomplete

Field Template

{
  "name": "field_name",
  "displayName": "Display Name",
  "description": "Help text for the user",
  "defaultValue": "optional default",
  "type": { "type": "TEXT" },
  "options": [
    { "value": "option1", "label": "Option 1" }
  ]
}

Trigger Types

Type Config Use Case
INPUT_FORM scheduleConfig: {} Manual form submission
INPUT_FORM + schedule scheduleConfig: { enabled: true } Scheduled execution
WEBHOOK Webhook endpoint External HTTP trigger
SLACK_COMMAND Slash command config Slack integration
CONTENT_TRIGGER Content filters Document change detection

Variable Syntax

Glean uses [[variable]] syntax for references:

  • Input fields: [[field_name]] — References a form input
  • Step outputs: [[step-id]] — References output from a previous step
  • Chaining: Steps can read from multiple previous steps

Example:

instructionTemplate: "Search for [[Account Name]] in [[previous-step-id]] and summarize"

Tools Catalog

See references/tools-catalog.md for the complete list.

Core Tools

Tool ID Config Key Purpose
Glean Search gleanSearchConfig Enterprise search across all apps
Glean Document Reader documentReaderConfig Read specific documents
Respond respondConfig Generate final output
Think thinkConfig Intermediate reasoning (no visible output)
Data Analysis — Process structured data

Glean Search Config

{
  "id": "Glean Search",
  "inputTemplate": [
    { "template": "[[Account]] app:gong" }
  ],
  "gleanSearchConfig": {
    "numResults": 30,
    "enableFullDocumentSnippets": true
  }
}

Respond Config

{
  "id": "Respond",
  "respondConfig": {
    "temperature": "FACTUAL"
  }
}

Action Examples

// Slack DM
{ "name": "slackdirectmessageuser" }

// Create Google Doc
{ "name": "creategdoc" }

// Draft Gmail
{ "name": "googledraftemail" }

// Web Search
{ "name": "googlegeminiwebsearch" }

Common Patterns

Pattern 1: Search → Synthesize

Most common pattern. Search for context, then respond.

{
  "steps": [
    {
      "id": "search",
      "type": "TOOL",
      "toolConfig": [
        { "id": "Glean Search", "inputTemplate": [{ "template": "[[Account]] app:gong" }] },
        { "id": "Glean Search", "inputTemplate": [{ "template": "[[Account]] app:slack" }] },
        { "id": "Glean Search", "inputTemplate": [{ "template": "[[Account]] app:salescloud" }] }
      ],
      "memoryConfig": "ALL_DEPENDENCIES"
    },
    {
      "id": "respond",
      "instructionTemplate": "Based on the context, provide a comprehensive summary...",
      "type": "TOOL",
      "stepDependencies": ["search"],
      "toolConfig": [{ "id": "Respond", "respondConfig": { "temperature": "FACTUAL" } }],
      "memoryConfig": "ALL_DEPENDENCIES"
    }
  ]
}

Pattern 2: Read Documents → Process → Output

Read specific files, process data, generate output.

{
  "steps": [
    {
      "id": "read-data",
      "instructionTemplate": "READ [[Data File]]",
      "type": "TOOL",
      "toolConfig": [{ "id": "Glean Document Reader", "documentReaderConfig": {} }]
    },
    {
      "id": "analyze",
      "instructionTemplate": "Analyze the data...",
      "type": "TOOL",
      "stepDependencies": ["read-data"],
      "toolConfig": [{ "name": "Data Analysis" }],
      "modelOptions": { "llmConfig": { "provider": "VERTEX_AI", "model": "GEMINI_3_0" } }
    },
    {
      "id": "respond",
      "instructionTemplate": "Format the analysis as a report...",
      "type": "TOOL",
      "stepDependencies": ["analyze"],
      "toolConfig": [{ "id": "Respond" }]
    }
  ]
}

Pattern 3: Agent Orchestration

Call another agent as a step.

{
  "id": "run-sub-agent",
  "type": "AGENT",
  "toolConfig": [
    {
      "id": "agent-uuid-here",
      "name": "agent-uuid-here",
      "inputTemplate": [
        { "template": "[[Prospect]]", "name": "Prospect" }
      ],
      "runAgentConfig": {}
    }
  ],
  "memoryConfig": "ALL_DEPENDENCIES"
}

Pattern 4: Conditional Branching

Execute different paths based on conditions.

{
  "id": "branch-step",
  "type": "BRANCH",
  "branchConfig": {
    "branches": [
      {
        "condition": {
          "boolFunction": {
            "id": "Think",
            "inputTemplate": [{ "template": "[[field]] is \"yes\"" }]
          }
        },
        "stepId": "path-a"
      }
    ],
    "default": { "stepId": "path-b" }
  }
}

Pattern 5: Respond + Take Action

Generate response AND perform an action (e.g., Slack DM).

{
  "steps": [
    {
      "id": "generate-report",
      "instructionTemplate": "Generate the daily report...",
      "type": "TOOL",
      "toolConfig": [{ "id": "Respond" }]
    },
    {
      "id": "send-slack",
      "instructionTemplate": "Send me a Slack DM with [[generate-report]]",
      "type": "TOOL",
      "stepDependencies": ["generate-report"],
      "toolConfig": [{ "name": "slackdirectmessageuser", "customisationData": { "skipUserInteraction": true } }]
    }
  ]
}

Model Options

Available Models

Provider Model Best For
OPEN_AI GPT41_20250414 General purpose, strong reasoning
VERTEX_AI GEMINI_3_0 Data analysis, long context

Per-Step Model Override

{
  "modelOptions": {
    "llmConfig": {
      "provider": "VERTEX_AI",
      "model": "GEMINI_3_0"
    }
  }
}

Memory Config

Controls how much context a step receives:

Value Behavior
ALL_DEPENDENCIES Receives output from all dependent steps (default)
NO_MEMORY Fresh context, no previous step outputs

Output Format

When generating specs, provide both:

1. JSON (for import)

{
  "rootWorkflow": {
    // ... complete spec
  }
}

2. Markdown Documentation

# Agent Specification: [Name]

## Overview
- **Purpose:** [What it does]
- **Audience:** [Who uses it]
- **Trigger:** [How it starts]

## Input Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| ... | ... | ... | ... |

## Workflow Steps
1. **[Step Name]** — [What it does]
2. **[Step Name]** — [What it does]

## Data Sources
- [Source 1]
- [Source 2]

## Output
[Description of what the agent returns]

## Testing
| Scenario | Expected Result |
|----------|-----------------|
| ... | ... |

Best Practices

  1. Start simple — Get a working agent, then add complexity
  2. Use meaningful step IDs — search-accounts not step-1
  3. Chain with dependencies — Use stepDependencies to control flow
  4. Set memory config — Usually ALL_DEPENDENCIES for multi-step
  5. Test incrementally — Build and test step by step
  6. Document prompts — Long instructionTemplate values should be clear

Example: Account Status Agent

{
  "rootWorkflow": {
    "name": "Account Status Agent",
    "description": "Pre-meeting briefing for any customer account",
    "icon": {
      "backgroundColor": "var(--theme-brand-light-blue-50)",
      "color": "#333",
      "iconType": "GLYPH",
      "name": "briefcase"
    },
    "schema": {
      "goal": "Provide comprehensive pre-meeting context for customer accounts",
      "steps": [
        {
          "id": "gather-context",
          "type": "TOOL",
          "toolConfig": [
            { "id": "Glean Search", "inputTemplate": [{ "template": "[[Account Name]] app:gong" }] },
            { "id": "Glean Search", "inputTemplate": [{ "template": "[[Account Name]] app:slack" }] },
            { "id": "Glean Search", "inputTemplate": [{ "template": "[[Account Name]] app:gmail" }] },
            { "id": "Glean Search", "inputTemplate": [{ "template": "[[Account Name]] app:salescloud" }] }
          ],
          "memoryConfig": "ALL_DEPENDENCIES"
        },
        {
          "id": "synthesize-briefing",
          "instructionTemplate": "Based on the gathered context, create a pre-meeting briefing with:\n\n1. **Last Meeting** - Date, key points, commitments\n2. **Open To-Dos** - Action items for Glean team\n3. **Missed Communications** - Unresponded messages\n4. **Internal Flags** - Team concerns or notes\n5. **Account Health** - Overall status assessment\n\nBe concise. Cite sources. Flag anything urgent.",
          "type": "TOOL",
          "stepDependencies": ["gather-context"],
          "toolConfig": [{ "id": "Respond", "respondConfig": { "temperature": "FACTUAL" } }],
          "memoryConfig": "ALL_DEPENDENCIES"
        }
      ],
      "fields": [
        {
          "name": "Account Name",
          "displayName": "Account Name",
          "description": "Customer account name (e.g., 'Snap Inc.', 'Northbeam')",
          "type": { "type": "TEXT" }
        }
      ],
      "modelOptions": {
        "llmConfig": { "provider": "OPEN_AI", "model": "GPT41_20250414" }
      },
      "trigger": {
        "type": "INPUT_FORM",
        "config": { "inputForm": { "scheduleConfig": {} } }
      }
    }
  }
}

When generating specs, always validate JSON syntax and ensure all step references are valid.

Weekly Installs
2
Repository
ken-cavanagh-gl…fieldkit
GitHub Stars
3
First Seen
Jan 27, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
Installed on
claude-code2
mcpjam1
kilo1
junie1
windsurf1
zencoder1