Agent skill

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]'.

View SKILL.md on GitHub Repository
Stars 3
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/ken-cavanagh-glean/fieldkit/tree/main/plugins/agent-builder/skills/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):

markdown
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

json
{
  "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

json
{
  "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

json
{
  "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

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

Respond Config

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

Action Examples

json
// 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.

json
{
  "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.

json
{
  "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.

json
{
  "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.

json
{
  "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).

json
{
  "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

json
{
  "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)

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

2. Markdown Documentation

markdown
# 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

json
{
  "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.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

ken-cavanagh-glean/fieldkit

brief

Get a pre-meeting briefing for any account. Usage: /brief {account name}. Returns checklist progress, hours remaining, last interaction, missed comms, and open to-dos.

3 0
Explore
ken-cavanagh-glean/fieldkit

browser-automation

Guidance for effective browser automation with dev-browser plugin. Use for testing local development, verifying UI changes, debugging visual issues, and automating browser tasks.

3 0
Explore
ken-cavanagh-glean/fieldkit

glean-mcp

Your work knowledge agent. Use Glean chat to answer any question about the user's company, accounts, colleagues, meetings, documents, or work history. Glean synthesizes across 100+ enterprise apps and always cites sources.

3 0
Explore
ken-cavanagh-glean/fieldkit

context-engineering-collection

A comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.

3 0
Explore
ken-cavanagh-glean/fieldkit

tool-design

Design tools that agents can use effectively, including when to reduce tool complexity. Use when creating, optimizing, or reducing agent tool sets.

3 0
Explore
ken-cavanagh-glean/fieldkit

memory-systems

Design and implement memory architectures for agent systems. Use when building agents that need to persist state across sessions, maintain entity consistency, or reason over structured knowledge.

3 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results