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]'.
apm install @ken-cavanagh-glean/agent-spec-generator[](https://apm-p1ls2dz87-atlamors-projects.vercel.app/packages/@ken-cavanagh-glean/agent-spec-generator)---
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):
```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.*