Agent-Skills.md

Agent Skills: Agent Spec Generator

Design and generate Glean Agent specifications. Use when creating new agents, speccing out agent requirements, or generating JSON for Agent Builder import. Triggers on: 'create an agent', 'design an agent', 'agent spec', 'build an agent for [use case]'.

UncategorizedID: ken-cavanagh-glean/fieldkit/agent-spec-generator

Repository

ken-cavanagh-glean/fieldkit
ken-cavanagh-glean
3

Install this agent skill to your local

pnpm dlx add-skill https://github.com/ken-cavanagh-glean/fieldkit/tree/HEAD/plugins/agent-builder/skills/agent-spec-generator

Skill Files

Browse the full folder contents for agent-spec-generator.

Download Skill

Loading file tree…

plugins/agent-builder/skills/agent-spec-generator/SKILL.md

Skill Metadata

Name
agent-spec-generator
Description
"Design and generate Glean Agent specifications. Use when creating new agents, speccing out agent requirements, or generating JSON for Agent Builder import. Triggers on: 'create an agent', 'design an agent', 'agent spec', 'build an agent for [use case]'."

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.