@hailer/mcp 0.0.1

package/.claude/skills/list-workflows-minimal-skill/SKILL.md

@@ -0,0 +1,992 @@
+---
+name: list-workflows-minimal-skill
+description: Complete guide to using the list_workflows_minimal tool to efficiently list workflows with minimal output to avoid token limits
+---
+
+# List Workflows Minimal Skill
+
+Complete guide to using the `list_workflows_minimal` tool to efficiently list workflows with minimal output, perfect for finding workflows by name or avoiding token limits.
+
+## Table of Contents
+- [Quick Reference](#quick-reference)
+- [Overview](#overview)
+- [Core Concepts](#core-concepts)
+- [Basic Usage](#basic-usage)
+- [Filtering and Search](#filtering-and-search)
+- [Pagination](#pagination)
+- [Common Scenarios](#common-scenarios)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+- [Integration with Other Tools](#integration-with-other-tools)
+- [Additional Resources](#additional-resources)
+
+## Quick Reference
+
+### List all workflows (minimal output)
+```javascript
+list_workflows_minimal()
+```
+
+### Search workflows by name
+```javascript
+list_workflows_minimal({
+  search: "task"
+})
+```
+
+### List starred workflows only
+```javascript
+list_workflows_minimal({
+  starredOnly: true
+})
+```
+
+### Paginate results (first 10)
+```javascript
+list_workflows_minimal({
+  limit: 10,
+  offset: 0
+})
+```
+
+### Combine filters
+```javascript
+list_workflows_minimal({
+  search: "customer",
+  starredOnly: true,
+  limit: 20
+})
+```
+
+## Overview
+
+The `list_workflows_minimal` tool lists workflows with minimal output (only id, name, workspace, activity count, and starred status). This is designed to avoid token limits when you have many workflows or just need to find specific workflows without loading full schema details.
+
+**Key capabilities:**
+- Lists workflows with minimal data (id, name, count, starred)
+- Avoids token limits (unlike full workflow listing)
+- Search workflows by name (case-insensitive)
+- Filter by starred workflows
+- Pagination support (limit and offset)
+- Filter by workspace
+
+**What you get:**
+- Workflow ID
+- Workflow name
+- Workspace ID
+- Activity count
+- Starred status
+
+**What you DON'T get:**
+- Fields
+- Phases
+- Activity links
+- Permissions
+- Full schema details
+
+**When to use this tool:**
+- Finding a workflow by name
+- Getting a quick list of all workflows
+- Working with workspaces that have many workflows (50+)
+- Avoiding token limits
+- Checking if a workflow exists
+
+**When to use full listing instead:**
+- Need field information
+- Need phase information
+- Need to analyze workflow structure
+- Working with few workflows (<20)
+
+## Core Concepts
+
+### Minimal Output
+
+This tool returns only essential information:
+
+```javascript
+{
+  id: "_0001",
+  name: "Tasks",
+  workspaceId: "workspace-id",
+  activityCount: 150,
+  isStarred: true
+}
+```
+
+**vs full workflow listing:**
+```javascript
+{
+  id: "_0001",
+  name: "Tasks",
+  workspaceId: "workspace-id",
+  activityCount: 150,
+  isStarred: true,
+  fields: [...],        // 20-50 fields
+  phases: [...],        // 5-10 phases
+  activityLinks: [...], // 0-10 links
+  permissions: {...},   // Permission details
+  // ... and more
+}
+```
+
+### Token Optimization
+
+**Problem:** Full workflow listing can use 10,000+ tokens with many workflows.
+
+**Solution:** Minimal listing uses ~100-500 tokens for the same data.
+
+**Example:**
+- 100 workflows with full data: ~50,000 tokens
+- 100 workflows with minimal data: ~2,000 tokens
+
+### Search and Filtering
+
+Four ways to filter workflows:
+
+1. **By name** - Case-insensitive partial match
+2. **By starred** - Only show starred workflows
+3. **By workspace** - Filter to specific workspace
+4. **By pagination** - Limit results and skip entries
+
+### Pagination
+
+Control output size:
+- **limit** - Max number to return
+- **offset** - Number to skip
+
+**Example:**
+```javascript
+// Page 1: First 20
+list_workflows_minimal({ limit: 20, offset: 0 })
+
+// Page 2: Next 20
+list_workflows_minimal({ limit: 20, offset: 20 })
+
+// Page 3: Next 20
+list_workflows_minimal({ limit: 20, offset: 40 })
+```
+
+## Basic Usage
+
+### List all workflows
+
+```javascript
+list_workflows_minimal()
+```
+
+**Output:**
+```
+📋 Workflows Found
+
+Total: 25
+Showing: 25
+
+⭐ **Tasks**
+  ID: `_0001`
+  Activities: 150
+
+**Projects**
+  ID: `_0002`
+  Activities: 48
+
+**Customers**
+  ID: `_0003`
+  Activities: 203
+
+💡 Next Steps:
+- Use `get_workflow_schema` with workflow ID to see fields
+```
+
+### Get first 10 workflows
+
+```javascript
+list_workflows_minimal({
+  limit: 10
+})
+```
+
+**Output:**
+```
+📋 Workflows Found
+
+Total: 25
+Showing: 10
+
+⭐ **Tasks**
+  ID: `_0001`
+  Activities: 150
+
+**Projects**
+  ID: `_0002`
+  Activities: 48
+
+...
+(8 more workflows)
+```
+
+## Filtering and Search
+
+### Search by name
+
+```javascript
+// Find workflows with "task" in name
+list_workflows_minimal({
+  search: "task"
+})
+```
+
+**Matches:**
+- "Tasks"
+- "Task Manager"
+- "Project Tasks"
+- "Subtasks"
+
+**Case-insensitive** - Searches both "task", "Task", "TASK"
+
+### Show only starred workflows
+
+```javascript
+list_workflows_minimal({
+  starredOnly: true
+})
+```
+
+**Output:**
+```
+📋 Workflows Found
+
+Total: 3
+Showing: 3
+
+⭐ **Tasks**
+  ID: `_0001`
+  Activities: 150
+
+⭐ **Projects**
+  ID: `_0002`
+  Activities: 48
+
+⭐ **Customers**
+  ID: `_0003`
+  Activities: 203
+```
+
+### Filter by workspace
+
+```javascript
+list_workflows_minimal({
+  workspace: "workspace-id"
+  // or workspace: "Workspace Name"
+})
+```
+
+### Combine filters
+
+```javascript
+// Find starred workflows with "customer" in name
+list_workflows_minimal({
+  search: "customer",
+  starredOnly: true
+})
+```
+
+## Pagination
+
+### Basic pagination
+
+```javascript
+// First page: 10 workflows
+list_workflows_minimal({
+  limit: 10,
+  offset: 0
+})
+
+// Second page: Next 10 workflows
+list_workflows_minimal({
+  limit: 10,
+  offset: 10
+})
+
+// Third page: Next 10 workflows
+list_workflows_minimal({
+  limit: 10,
+  offset: 20
+})
+```
+
+### Skip first N workflows
+
+```javascript
+// Skip first 5, show rest
+list_workflows_minimal({
+  offset: 5
+})
+```
+
+### Combine pagination with search
+
+```javascript
+// First 20 workflows matching "task"
+list_workflows_minimal({
+  search: "task",
+  limit: 20,
+  offset: 0
+})
+```
+
+### Large workspace strategy
+
+For workspaces with 100+ workflows:
+
+```javascript
+// Get first batch
+const page1 = list_workflows_minimal({
+  limit: 50,
+  offset: 0
+})
+
+// Get second batch
+const page2 = list_workflows_minimal({
+  limit: 50,
+  offset: 50
+})
+
+// Get remaining
+const page3 = list_workflows_minimal({
+  limit: 50,
+  offset: 100
+})
+```
+
+## Common Scenarios
+
+### Scenario 1: Find Specific Workflow by Name
+
+You know the workflow name but not the ID:
+
+```javascript
+// Find "Tasks" workflow
+list_workflows_minimal({
+  search: "tasks"
+})
+```
+
+**Result:**
+```
+📋 Workflows Found
+
+Total: 1
+Showing: 1
+
+⭐ **Tasks**
+  ID: `_0001`
+  Activities: 150
+```
+
+**Next:** Use the ID to get full schema:
+```javascript
+get_workflow_schema({
+  workflowId: "_0001"
+})
+```
+
+### Scenario 2: Quick Inventory of All Workflows
+
+Get overview without overwhelming token usage:
+
+```javascript
+list_workflows_minimal()
+```
+
+**Use case:**
+- New workspace exploration
+- Documenting existing workflows
+- Understanding workspace structure
+- Generating workflow reports
+
+### Scenario 3: Find Unused Workflows
+
+Identify workflows with zero activities:
+
+```javascript
+// List all workflows
+const workflows = list_workflows_minimal()
+
+// Filter output manually for activityCount: 0
+// Or look through the list for workflows with 0 activities
+```
+
+**Example output showing unused workflow:**
+```
+**Legacy System**
+  ID: `_0015`
+  Activities: 0    ← Unused workflow
+```
+
+### Scenario 4: Working with Large Workspaces
+
+Workspace with 200+ workflows - avoid token limits:
+
+```javascript
+// ❌ Bad: Full listing could exceed token limits
+// get_all_workflows()  // 50,000+ tokens
+
+// ✅ Good: Minimal listing
+list_workflows_minimal({
+  limit: 50  // Manageable chunks
+})
+```
+
+### Scenario 5: Find Related Workflows
+
+Search for workflow family:
+
+```javascript
+// Find all HR-related workflows
+list_workflows_minimal({
+  search: "hr"
+})
+```
+
+**Matches:**
+- "HR Onboarding"
+- "HR Requests"
+- "HR Documents"
+- "Employee HR Records"
+
+### Scenario 6: Interactive Workflow Selection
+
+Build a workflow picker for users:
+
+```javascript
+// 1. Get all workflows
+const all = list_workflows_minimal()
+
+// 2. Let user search
+const filtered = list_workflows_minimal({
+  search: userInput
+})
+
+// 3. User selects from filtered list
+// 4. Get full schema for selected workflow
+get_workflow_schema({
+  workflowId: selectedId
+})
+```
+
+### Scenario 7: Audit Workflow Usage
+
+Generate usage report:
+
+```javascript
+// Get all workflows with activity counts
+list_workflows_minimal()
+
+// Analyze output:
+// - Which workflows are most used? (high activity count)
+// - Which are unused? (activity count: 0)
+// - Which are starred? (important workflows)
+```
+
+### Scenario 8: Paginated Browse Experience
+
+Implement "load more" pattern:
+
+```javascript
+let offset = 0;
+const pageSize = 20;
+
+// Load first page
+list_workflows_minimal({
+  limit: pageSize,
+  offset: offset
+})
+
+// User clicks "load more"
+offset += pageSize;
+
+// Load next page
+list_workflows_minimal({
+  limit: pageSize,
+  offset: offset
+})
+```
+
+## Best Practices
+
+### 1. Use Minimal Listing for Large Workspaces
+
+```javascript
+// ❌ Avoid: Full listing when you have many workflows
+// get_all_workflows()  // Could use 50,000 tokens
+
+// ✅ Better: Minimal listing
+list_workflows_minimal({
+  limit: 50
+})
+```
+
+### 2. Search Before Loading Full Schema
+
+```javascript
+// Efficient workflow:
+
+// 1. Find workflow by name (minimal tokens)
+list_workflows_minimal({
+  search: "customers"
+})
+
+// 2. Get ID from results: "_0003"
+
+// 3. Only then load full schema (more tokens)
+get_workflow_schema({
+  workflowId: "_0003"
+})
+```
+
+### 3. Use Starred Filter for Important Workflows
+
+```javascript
+// Show only important/frequently used workflows
+list_workflows_minimal({
+  starredOnly: true
+})
+```
+
+### 4. Paginate for Better Performance
+
+```javascript
+// Better performance with pagination
+list_workflows_minimal({
+  limit: 25  // Manageable chunk size
+})
+
+// vs loading all 200 workflows at once
+list_workflows_minimal()  // Could be slow
+```
+
+### 5. Case-Insensitive Search
+
+```javascript
+// All equivalent:
+list_workflows_minimal({ search: "task" })
+list_workflows_minimal({ search: "Task" })
+list_workflows_minimal({ search: "TASK" })
+
+// Use lowercase for consistency
+list_workflows_minimal({ search: "task" })
+```
+
+### 6. Combine Filters Strategically
+
+```javascript
+// Narrow down efficiently
+list_workflows_minimal({
+  search: "project",     // Match name
+  starredOnly: true,     // Only important ones
+  limit: 10              // First 10 results
+})
+```
+
+### 7. Document Workflow IDs
+
+After finding workflows, document them:
+
+```javascript
+// Find key workflows once
+const tasks = list_workflows_minimal({ search: "tasks" })
+// ID: "_0001"
+
+const projects = list_workflows_minimal({ search: "projects" })
+// ID: "_0002"
+
+// Document in code comments or config:
+const WORKFLOW_IDS = {
+  TASKS: "_0001",
+  PROJECTS: "_0002"
+};
+```
+
+## Troubleshooting
+
+### No Workflows Found
+
+**Problem:** Empty results.
+
+**Possible causes:**
+1. No workflows in workspace
+2. Search term too specific
+3. starredOnly: true but no starred workflows
+4. Workspace filter excluding all workflows
+
+**Solution:**
+```javascript
+// 1. Try without filters
+list_workflows_minimal()
+
+// 2. Broaden search
+list_workflows_minimal({
+  search: "a"  // More general search
+})
+
+// 3. Remove starredOnly filter
+list_workflows_minimal({
+  starredOnly: false
+})
+```
+
+### Search Returns Nothing
+
+**Problem:** No results for search term.
+
+**Solution:**
+```javascript
+// Try partial matches
+list_workflows_minimal({ search: "task" })  // Broader
+// vs
+list_workflows_minimal({ search: "task manager v2" })  // Too specific
+
+// Try different terms
+list_workflows_minimal({ search: "project" })
+list_workflows_minimal({ search: "customer" })
+```
+
+### Too Many Results
+
+**Problem:** Hundreds of workflows returned.
+
+**Solution:**
+```javascript
+// Use pagination
+list_workflows_minimal({
+  limit: 25,
+  offset: 0
+})
+
+// Or use more specific search
+list_workflows_minimal({
+  search: "customer service"  // More specific
+})
+
+// Or filter to starred only
+list_workflows_minimal({
+  starredOnly: true
+})
+```
+
+### Need Full Schema After Minimal List
+
+**Problem:** Need field details after finding workflow.
+
+**Solution:**
+```javascript
+// 1. Find workflow
+const result = list_workflows_minimal({
+  search: "tasks"
+})
+// Found: ID "_0001"
+
+// 2. Get full schema
+get_workflow_schema({
+  workflowId: "_0001"
+})
+```
+
+### Offset Beyond Total Count
+
+**Problem:** Offset larger than total workflows.
+
+**Example:**
+```javascript
+// Only 50 workflows exist
+list_workflows_minimal({
+  limit: 20,
+  offset: 100  // Beyond total count
+})
+```
+
+**Result:** Empty results.
+
+**Solution:**
+```javascript
+// Check total count first
+list_workflows_minimal({ limit: 1 })
+// Shows: "Total: 50"
+
+// Then use appropriate offset
+list_workflows_minimal({
+  limit: 20,
+  offset: 40  // Within range
+})
+```
+
+### Starred Filter Returns Nothing
+
+**Problem:** starredOnly: true returns no workflows.
+
+**Cause:** No workflows are starred in the workspace.
+
+**Solution:**
+```javascript
+// Remove starred filter
+list_workflows_minimal()
+
+// Or star important workflows in Hailer UI first
+```
+
+## Integration with Other Tools
+
+### With `get_workflow_schema`
+
+Find workflow first, then get details:
+
+```javascript
+// 1. Find workflow ID (minimal tokens)
+list_workflows_minimal({
+  search: "customers"
+})
+
+// Result shows: ID "_0003"
+
+// 2. Get full schema (more tokens)
+get_workflow_schema({
+  workflowId: "_0003"
+})
+```
+
+### With `install_workflow`
+
+Check if workflow name already exists:
+
+```javascript
+// Before creating new workflow, check if name exists
+list_workflows_minimal({
+  search: "tasks"
+})
+
+// If no match, safe to create:
+install_workflow({
+  id: '_0010',
+  name: 'Tasks',
+  fields: [...]
+})
+```
+
+### With `remove_workflow`
+
+Find workflow to remove:
+
+```javascript
+// 1. Find unused workflow
+list_workflows_minimal()
+
+// Output shows:
+// **Old System**
+//   ID: `_0015`
+//   Activities: 0    ← Unused
+
+// 2. Remove it
+remove_workflow({
+  workflowId: '_0015'
+})
+```
+
+### With `create_insight`
+
+Find workflows for SQL queries:
+
+```javascript
+// 1. Find relevant workflows
+list_workflows_minimal({
+  search: "sales"
+})
+
+// Output:
+// **Sales Leads**
+//   ID: `_0005`
+//
+// **Sales Orders**
+//   ID: `_0006`
+
+// 2. Create insight joining these workflows
+create_insight({
+  name: 'Sales Pipeline',
+  sql: `
+    SELECT
+      l.name as lead_name,
+      o.total as order_total
+    FROM _0005 l
+    LEFT JOIN _0006 o ON o.leadId = l._id
+  `
+})
+```
+
+### With `create_app`
+
+Find workflow IDs for app configuration:
+
+```javascript
+// 1. Find workflow your app needs
+list_workflows_minimal({
+  search: "products"
+})
+
+// Output: ID "_0008"
+
+// 2. Create app with workflow config
+create_app({
+  name: 'Product Manager',
+  url: 'http://localhost:3000',
+  config: {
+    workflowId: '_0008'
+  }
+})
+```
+
+### With `update_workflow_field`
+
+Find workflow to update:
+
+```javascript
+// 1. Find workflow
+list_workflows_minimal({
+  search: "tasks"
+})
+
+// Output: ID "_0001"
+
+// 2. Get full schema to see fields
+get_workflow_schema({
+  workflowId: "_0001"
+})
+
+// 3. Update field
+update_workflow_field({
+  workflowId: '_0001',
+  fieldId: '_1000',
+  updates: { label: 'Task Name' }
+})
+```
+
+## Additional Resources
+
+### Related Skills
+- **install-workflow-skill** - Create new workflows
+- **remove-workflow-skill** - Delete workflows
+- **update-workflow-field-skill** - Modify workflow fields
+- **create-insight-skill** - Create SQL insights over workflows
+- **create-app-skill** - Create apps that use workflows
+
+### Related Tools
+- `get_workflow_schema` - Get full workflow details (fields, phases, etc.)
+- `install_workflow` - Create new workflows
+- `remove_workflow` - Delete workflows
+- `update_workflow_field` - Modify workflow fields
+
+### When to Use Which Tool
+
+| Goal | Tool to Use | Reason |
+|------|-------------|--------|
+| Find workflow by name | `list_workflows_minimal` | Fast, minimal tokens |
+| Get all workflows (small workspace) | Full workflow listing | Complete details in one call |
+| Get all workflows (large workspace) | `list_workflows_minimal` | Avoid token limits |
+| See workflow fields | `get_workflow_schema` | Need full schema |
+| Check if workflow exists | `list_workflows_minimal` | Fast lookup |
+| Generate workflow report | `list_workflows_minimal` | Efficient for many workflows |
+| Debug workflow structure | `get_workflow_schema` | Need field/phase details |
+
+### Search Patterns
+
+| Search Term | Matches |
+|-------------|---------|
+| `"task"` | "Tasks", "Task Manager", "Subtasks" |
+| `"customer"` | "Customers", "Customer Service", "CRM Customers" |
+| `"hr"` | "HR", "HR Onboarding", "Employee HR Records" |
+| `""` (empty) | All workflows |
+| `"a"` | Any workflow with "a" in name |
+
+### Pagination Patterns
+
+```javascript
+// Pattern 1: Fixed page size
+const PAGE_SIZE = 20;
+list_workflows_minimal({ limit: PAGE_SIZE, offset: 0 })
+list_workflows_minimal({ limit: PAGE_SIZE, offset: 20 })
+list_workflows_minimal({ limit: PAGE_SIZE, offset: 40 })
+
+// Pattern 2: Load all in chunks
+let offset = 0;
+const CHUNK_SIZE = 50;
+while (hasMore) {
+  list_workflows_minimal({ limit: CHUNK_SIZE, offset: offset })
+  offset += CHUNK_SIZE;
+}
+
+// Pattern 3: Infinite scroll
+let loaded = 0;
+const onScrollBottom = () => {
+  list_workflows_minimal({ limit: 20, offset: loaded })
+  loaded += 20;
+}
+```
+
+### Output Format
+
+```javascript
+list_workflows_minimal({ search: "task" })
+```
+
+**Returns:**
+```
+📋 Workflows Found
+
+Total: 3          ← Total matching workflows
+Showing: 3        ← Number displayed (after pagination)
+Offset: 0         ← Current offset (if > 0)
+
+⭐ **Tasks**      ← Star if starred
+  ID: `_0001`     ← Workflow ID
+  Activities: 150 ← Number of activities
+
+**Project Tasks**
+  ID: `_0007`
+  Activities: 45
+
+**Task Templates**
+  ID: `_0012`
+  Activities: 0
+
+💡 Next Steps:
+- Use `get_workflow_schema` with workflow ID to see fields
+```
+
+### Performance Comparison
+
+| Workspace Size | Full Listing | Minimal Listing | Savings |
+|----------------|--------------|-----------------|---------|
+| 10 workflows | ~5,000 tokens | ~500 tokens | 90% |
+| 50 workflows | ~25,000 tokens | ~2,000 tokens | 92% |
+| 100 workflows | ~50,000 tokens | ~3,500 tokens | 93% |
+| 200 workflows | ~100,000 tokens | ~7,000 tokens | 93% |
+
+### Workflow Discovery Strategies
+
+1. **Broad search first:**
+   ```javascript
+   list_workflows_minimal({ search: "customer" })
+   ```
+
+2. **Then narrow down:**
+   ```javascript
+   list_workflows_minimal({ search: "customer service" })
+   ```
+
+3. **Or browse by importance:**
+   ```javascript
+   list_workflows_minimal({ starredOnly: true })
+   ```
+
+4. **Or paginate through all:**
+   ```javascript
+   list_workflows_minimal({ limit: 25, offset: 0 })
+   ```