---
title: SlugKit Quick Start Guide (Agent Guide)
description: Get started with SlugKit in 5 minutes for AI agents! Generate human-readable IDs, slugs, and structured content.
slug: agent-quick-start-guide
audience: llm
created_at: 2025-09-11T00:00:41.781095+0000
last_modified: 2025-10-15T14:28:23.413707+0000
content_type: markdown
author: SlugKit Team
tags: 
    - mcp-help
    - llm-docs
---
# SlugKit Quick Start Guide (Agent Guide)

**Get started with SlugKit in 5 minutes for AI agents! Generate human-readable IDs, slugs, and structured content.**

## Step 1: Check Your Access (30 seconds)

Before you begin, verify your API key and subscription limits:

```
📋 Use: limits()
→ Shows your organization's features and quotas
→ Missing fields = feature unavailable
→ -1 = unlimited

📋 Use: key_info()
→ Shows your API key capabilities and scopes
```

**Example:**
```
limits()
→ {
  "forge_enabled": true,
  "max_forge_per_request": 100,
  "mint_enabled": true,
  "series_create": true,
  ...
}
```

## Step 2: Understand the Basics (30 seconds)

SlugKit uses **patterns** - templates with placeholders that generate random but readable content:

```
{adjective}-{noun}           → "fast-server"
{verb} {adjective} {noun}    → "deploy amazing platform" 
Error {number:3d}: {noun}    → "Error 404: database"
```

**Key Point**: Anything outside `{}` is kept exactly as written. Anything inside `{}` gets replaced.

## Step 3: Validate Your First Pattern (1 minute)

**Before creating a pattern** always start your session with obtaining actual available dictionary and tag data (`dictionary_info()`, `dictionary_tags()`)
**Always start with validation** to check syntax and see what you'll get:

```
📚 Use: validate_pattern(pattern)
```

**Try these examples:**

```
✅ validate_pattern("{adjective}-{noun}")
→ Capacity: 708M combinations, max length: 55 chars

✅ validate_pattern("user-{number:4d}@example.com") 
→ Capacity: 10K combinations, max length: 25 chars

❌ validate_pattern("{adjective<6}-{noun}")
→ Invalid: constraints go INSIDE braces after a colon: {adjective:<6}
```

**Advanced Analysis:**

```
🔍 Use: analyze_pattern(pattern)
→ Detailed breakdown of pattern complexity, capacity, and components

🔍 Use: compare_patterns([pattern1, pattern2, ...])
→ Side-by-side comparison with sample outputs
```

## Step 4: Generate Content (2 minutes)

### Option A: Custom Generation (`forge`)
Perfect for one-off generation or custom patterns:

```
🔨 forge(pattern, count=5, seed="test")
```

**Examples:**
```
forge("{adjective}-{noun}", count=3, seed="demo")
→ ["smart-server", "fast-database", "secure-platform"]

forge("deploy {noun} to {adjective} environment", count=2)
→ ["deploy webapp to staging environment", "deploy api to production environment"]
```

### Option B: Series Generation (`mint`)
Perfect for production apps needing guaranteed unique IDs:

```
⚡ mint(count=5, series_slug="your-series")
```

**First, check available series:**
```
series_list()
→ {"hotly-curly-gouge-d4ac": "Production IDs", "wanly-final-adobo-b55f": "Test IDs", ...}

series_info("hotly-curly-gouge-d4ac")  
→ Pattern: "{adjective:<8}-{noun:<8}-{number:3d}"
→ Capacity: 38.8 billion combinations
→ Generated: 1,234 IDs
```

**Then mint from series:**
```
mint(count=3, series_slug="hotly-curly-gouge-d4ac")
→ ["soupy-stoop-142", "bobtail-ousting-083", "imposed-gramps-024"]
```

**Preview before minting:**
```
slice(count=3, series_slug="hotly-curly-gouge-d4ac")
→ Preview what the next 3 IDs would be without consuming them
```

## Step 5: Manage Series (1 minute)

### Create a New Series
```
✨ series_create(name="Production User IDs", pattern="{adjective}-{noun}-{number:4d}")
→ Creates a new series with the specified pattern
→ Returns series slug for future use
```

### Update Existing Series
```
🔄 series_update(series_slug="your-series", name="New Name", pattern="{new}-{pattern}")
→ Updates series (only if not locked)
→ Fails safely if series is in use
```

### Delete Series
```
🗑️ series_delete(series_slug="your-series")
→ Deletes series and all associated API keys
→ Use with caution!
```

## Step 6: Essential Pattern Syntax (2 minutes)

### Basic Placeholders
```
{adjective}    → descriptive words: fast, smart, secure
{noun}         → things: server, database, user  
{verb}         → actions: deploy, connect, analyze
{number:4d}    → 4-digit numbers: 0123, 5678, 9999
```

### Control Output Length
```
{adjective:<8}     → max 7 chars (< 8): "smart", "secure"
{noun:>=4}         → min 4 chars: "server", "platform" 
{noun:==5}         → exactly 5 chars: "users", "login"
```

### Filter by Theme
```
{adjective:+pos}      → positive words: amazing, brilliant
{noun:+device}        → device words: server, database, API
{adjective:+obj-neg}  → objective words, not negative
```

### Control Casing
```
{noun}      → lowercase: "server"
{NOUN}      → UPPERCASE: "SERVER"  
{Noun}      → Title Case: "Server"
{nOuN}      → Mixed case: "SeRvEr"
```

## Step 7: Your First Real Patterns

### Web Development
```
// URL slugs
forge("{adjective:+pos}-{noun:+device}-{number:4d}", count=3)
→ ["amazing-platform-2024", "brilliant-server-1847", "smart-database-9032"]

// API endpoints  
forge("/api/{noun:+person}/{adjective:<6}-{noun:+object}", count=2)
→ ["/api/users/active-session", "/api/data/secure-token"]
```

### User-Friendly IDs
```
// Customer support tickets
forge("TKT-{adjective:+pos}-{number:6d}", count=3, seed="support")
→ ["TKT-amazing-123456", "TKT-brilliant-789012", "TKT-smart-345678"]

// Readable user handles
forge("{adjective:+pos}<6{noun:+animal}<8", count=3)  
→ ["smart<6dolphin<8", "happy<6eagle<8", "bright<6tiger<8"]
```

### Configuration & DevOps
```
// Server names
forge("{adjective:+obj}<6-{noun:+device}<8-{number:2d}", count=3)
→ ["stable<6-database<8-01", "secure<6-webapp<8-02", "active<6-cache<8-03"]

// Environment variables
forge("{ADJECTIVE:+obj}_{NOUN:+device}_CONFIG", count=2)
→ ["STABLE_DATABASE_CONFIG", "SECURE_WEBAPP_CONFIG"]
```

## Common Mistakes to Avoid

### ❌ Wrong Constraint Placement
```
{adjective}<8          → This adds literal "<8" text
{adjective:+obj<8+pos} → Wrong order: length before tags
```

### ✅ Correct Syntax
```
{adjective:<8}         → Correct: max 7 characters  
{adjective:+obj+pos<8} → Correct: tags first, then length
```

### ❌ Using Non-Existent Tags
```
{adjective:+tech}      → Invalid: +tech tag doesn't exist for adjectives
{noun:+professional}   → Invalid: +professional tag doesn't exist
```

### ✅ Use Valid Tags
```
{adjective:+pos}       → Valid: positive adjectives
{adjective:+obj}       → Valid: objective adjectives  
{noun:+device}         → Valid: device nouns
{noun:+artifact}       → Valid: artifact nouns
```

### ❌ Forgetting Validation
```
forge("{adjective-noun}")  → Invalid syntax, will error
```

### ✅ Always Validate First
```
validate_pattern("{adjective}-{noun}")  → Check first!
forge("{adjective}-{noun}")             → Then generate
```

## Next Steps

### Explore Available Words
```
dictionary_info()    → See all word types (adjective, noun, verb, etc.)
dictionary_tags()    → See all available tags (+pos, +obj, +animal, etc.)
```

### Preview Before Using Series
```
slice(count=5, series_slug="your-series")  → Preview without consuming
mint(count=5, series_slug="your-series")   → Actually generate and consume
```

### Check Performance
```
series_info("your-series")  → See capacity and current usage
```

## Advanced Quick Examples

### Multi-line Templates
```
pattern = """server: {adjective:+obj}-{noun:+device}
port: {number:4d}  
status: {adjective:+pos}
debug: {adjective:+obj}"""

forge(pattern, count=1)
→ ["server: secure-database\nport: 5432\nstatus: amazing\ndebug: stable"]
```

### Mixed Casing for Code
```
// PascalCase components
forge("{Adjective}{Noun}Component", count=2)
→ ["SmartDatabaseComponent", "FastServerComponent"]

// camelCase variables  
forge("{adjective}{Noun}Config", count=2)
→ ["smartDatabaseConfig", "fastServerConfig"]
```

### Natural Language
```
forge("The {adjective:+pos} {noun:+animal} {verb} over the {adjective} {noun}", count=2)
→ ["The brilliant dolphin leaps over the rusty fence", 
   "The amazing eagle soars over the broken tower"]
```

## Available Tags Quick Reference

### Adjectives
- `+pos` - Positive words (amazing, brilliant, smart)
- `+neg` - Negative words (broken, failed, error)
- `+obj` - Objective words (stable, secure, active)
- `+det` - Detached words (analytical, systematic)
- `+neut` - Neutral words (standard, normal, basic)
- `+emo` - Emotional words (excited, worried, happy)

### Nouns  
- `+object` - General objects (18K words)
- `+device` - Technical devices (1.6K words)
- `+artifact` - Man-made objects (6.7K words)
- `+person` - People and roles (6.2K words)
- `+animal` - Animals (2.4K words)
- `+location` - Places (880 words)
- `+fantasy` - Fantasy terms (59 words)

### Verbs
- `+change` - Change actions (deploy, update, modify)
- `+act` - General actions (run, execute, process)
- `+travel` - Movement (navigate, move, flow)

### Domains
- `+com` - .com domains
- `+org` - .org domains
- `+tld` - Top-level domains
- `+dev` - .dev domains
- `+io` - .io domains

Use `dictionary_tags()` for the complete list!

## Essential Commands Summary

```
# Check access and limits
limits()                         # See your subscription features
key_info()                       # See your API key details

# Pattern development
validate_pattern("{your-pattern}")        # Check syntax
analyze_pattern("{your-pattern}")         # Detailed analysis
compare_patterns(["{p1}", "{p2}"])        # Compare options

# Generate custom content  
forge("{pattern}", count=N, seed="optional")

# Manage series
series_list()                    # See available series
series_create(name, pattern)     # Create new series
series_info("series-slug")       # Check series details  
series_update(slug, name, pattern)  # Update series
series_delete("series-slug")     # Delete series

# Use series for unique IDs
slice(count=N, series_slug="name")    # Preview
mint(count=N, series_slug="name")     # Generate unique IDs

# Understand your options
dictionary_info()                # Available word types
dictionary_tags(kind="noun")     # Available tag filters for a kind
```

**You're ready! Start with simple patterns like `{adjective}-{noun}` and gradually add constraints and complexity as needed.**

---
📚 **Full Documentation**: Use `get_help_topic("pattern-syntax-reference")` for complete syntax guide
🎯 **More Examples**: Use `get_help_topic("pattern-examples")` for use-case specific patterns