BAML Code Generation Skill

Version: 1.2.0 Status: Production (Two-Phase MCP Validation) Token Budget: ~3800 tokens (validated)

Overview

Generate production-ready BAML applications by querying official BoundaryML repositories through MCP servers. This skill extracts patterns, validates syntax, and synthesizes complete solutions including types, functions, tests, and integrations.

Activation Triggers

Keywords: BAML, LLM, structured output, code generation, extraction, classification
User requests to generate BAML code
Questions about BAML syntax or patterns

Prerequisites

Required MCP Servers:

baml_Docs: Core BAML repository access
baml_Examples: Production pattern examples (optional)

Validation: Check MCP availability before proceeding. If unavailable, use embedded fallback cache.

Core Capabilities

1. Pattern Recognition

Algorithm: Multi-stage pattern detection

INPUT: Natural language requirement
OUTPUT: Pattern category + matched examples

STEPS:
1. Tokenize requirement text
2. Match trigger keywords:
   - extraction: [extract, parse, structure, data]
   - classification: [classify, categorize, label]
   - rag: [search, retrieve, context, citation]
   - agents: [agent, plan, execute, tool]
3. Score categories (frequency + position weighting)
4. Select primary category (threshold > 0.5)
5. **EXECUTE MCP QUERIES** (Critical for freshness):
   - mcp__baml_Examples__search_baml_examples_code("{category} extension:baml")
   - Fetch top 2-3 results via mcp__baml_Docs__fetch_generic_url_content
   - Parse types, functions, prompts from real examples
   - VALIDATE: Query baml_Docs to verify syntax is current (not deprecated)
   - Output: "🔍 Found {X} patterns from BoundaryML/baml-examples"
   - Fall back to cache only if MCP unavailable

2. Code Synthesis Pipeline

Template-Based Generation:

PHASE 1: Type Inference
- Extract entities from requirements
- Map to BAML types (class, enum, primitive)
- Generate type definitions with @description

PHASE 2: Function Generation
- Determine function signature
- Select appropriate client/model
- Synthesize prompt template
- Inject ctx.output_format

PHASE 3: Client Configuration
- Match model to use case:
  * Multimodal → vision model
  * Classification → fast model (GPT-5-mini)
  * Complex → reasoning model (GPT-5)
- Generate client block with options

PHASE 4: Validation
- Syntax check (BAML grammar)
- Type safety (all refs defined)
- Completeness (all components present)

3. MCP Query Patterns

Available Tools:

mcp__baml_Docs__fetch_baml_documentation:
  Purpose: Fetch complete README
  Use: General context, fallback
  Cost: ~3000 tokens

mcp__baml_Docs__search_baml_documentation:
  Purpose: Semantic search
  Use: Find specific features
  Cost: 200-1000 tokens

mcp__baml_Docs__search_baml_code:
  Purpose: GitHub code search
  Use: Find implementation examples
  Cost: ~500 tokens (30 results/page)

mcp__baml_Docs__fetch_generic_url_content:
  Purpose: Fetch specific file
  Use: Detailed reference
  Cost: 500-2000 tokens

Query Strategy:

Check session cache first (15 min TTL)
Check persistent cache (7 day TTL)
Query MCP if cache miss
Validate with commit hash

4. BAML Syntax Reference

Core: class, enum, function, client | Types: string, int, float, bool, Type[], Type?, Type|Type Key Patterns: @description("..."), {{ param }}, {{ ctx.output_format }} Providers: openai, anthropic, gemini, vertex, bedrock

Query MCP for complete syntax: mcp__baml_Docs__search_baml_documentation("syntax")

5. Optimization Strategies

Token Reduction:

Remove redundant @description attributes
Apply symbol tuning to prompts
Consolidate similar types
Use @alias for long identifiers
Target: 50-70% reduction vs baseline

Performance:

Cache frequently used patterns
Batch related MCP queries
Preload top 10 patterns on activation
Target: <5s simple, <30s complex

6. Validation Pipeline

5-Layer Validation:

Syntax: Parse with BAML grammar
Types: All references defined, no cycles
Semantics: Prompt coherence check
Tests: 100% function coverage
Performance: Token count, cost estimate

Success Criteria:

First-time compilation: >95%
Type safety: 100% (guaranteed)
Test pass rate: >90%

Workflow

User Request
    ↓
[1] Analyze Requirements
    - Parse text
    - Identify pattern (extraction/classification/rag/agents)
    - Extract entities and constraints
    ↓
[2] Pattern Matching **🔍 MCP REQUIRED**
    - Execute: mcp__baml_Examples__search_baml_examples_code
    - Fetch: mcp__baml_Docs__fetch_generic_url_content
    - Parse: Extract types/functions/prompts from real code
    - Rank by similarity (>0.7 threshold)
    - Select top 3 candidates
    - Output: "🔍 Found {X} patterns from BoundaryML/baml-examples"
    ↓
[2.5] Syntax Validation **🔍 baml_Docs**
    - Query: mcp__baml_Docs__search_baml_documentation("syntax {feature}")
    - Compare: Example syntax vs canonical docs from BoundaryML/baml
    - Modernize: Update deprecated patterns to current spec
    - Output: "✅ Validated against BoundaryML/baml" OR "🔧 Modernized {N} patterns"
    ↓
[3] Code Generation
    - Generate types (classes, enums)
    - Generate function (signature, prompt, client)
    - Generate client configuration
    ↓
[4] Test Generation
    - Happy path tests
    - Edge case tests
    - Error handling tests
    ↓
[5] Integration Generation
    - Python/TypeScript/Ruby client code
    - Framework-specific endpoints
    - Deployment configuration
    ↓
[6] Validation & Optimization
    - Validate syntax and types
    - Optimize for tokens
    - Estimate costs
    ↓
[6.5] Error Recovery **🔧 IF ERRORS**
    - Extract: Parse error message from validation
    - Query: mcp__baml_Docs__search_baml_documentation("{error}")
    - Fetch: Current syntax spec from BoundaryML/baml
    - Fix: Update code to match canonical specification
    - Retry: Re-validate (max 2 attempts)
    - Output: "🔧 Fixed {N} errors using BoundaryML/baml docs"
    ↓
[7] Deliver Artifacts
    - BAML code
    - Test suite
    - Integration code
    - Deployment config
    - Performance metadata

MCP Query Execution

CRITICAL: Always query MCP for fresh patterns during code generation.

Observable Indicators (show user MCP usage):

🔍 "Found {X} patterns from BoundaryML/baml-examples"
✅ "Fetched {file} from BoundaryML/baml"
✅ "Validated against BoundaryML/baml - syntax current"
🔧 "Modernized {N} deprecated patterns from example"
🔧 "Fixed {N} errors using BoundaryML/baml docs"
📦 "Using cached pattern (MCP unavailable)"
⚠️ "MCP unavailable, using fallback templates"

Execution Order:

Check MCP availability first
Execute queries for pattern category
Parse real code examples
Adapt to requirements
Fall back to cache only if MCP fails

Caching Strategy

Multi-Tier Cache:

Tier 1 (Embedded): Core syntax (500 tokens, never expires)
Tier 2 (Session): Recent patterns (15 min TTL, LRU eviction)
Tier 3 (Persistent): Top 20 patterns (7 day TTL)
Tier 4 (MCP): Live queries (no cache, always fresh)

Invalidation:

Session end → Clear Tier 2
7 days → Refresh Tier 3
Commit hash change → Invalidate all
Manual refresh command

Error Handling

MCP Unavailable:

Fall back to Tier 1-3 caches
Use generic templates
Warn user about limited patterns

Pattern Not Found:

Use generic template for category
Request more specific requirements
Suggest similar patterns

Validation Failure:

Auto-query: mcp__baml_Docs__search_baml_documentation("{error}")
Compare: Generated code vs canonical BoundaryML/baml syntax
Auto-fix: Update code to match current specification
Retry: Re-validate with modernized code (max 2 attempts)
Report: "🔧 Fixed {N} issues" or detailed error if unfixable

Generation Timeout:

Show progress indicator
Stream partial results
Allow cancellation

Performance Targets

Simple function (<50 lines): <5s
Complex system (>500 lines): <30s
Compilation success: >95%
Token optimization: >50% reduction
Cost per generation: <$0.02

Output Format

Always include:

BAML Code: Complete .baml files
Tests: pytest/Jest with 100% coverage
Integration: Framework-specific code
Deployment: Docker/K8s configs
Metadata: Pattern used, tokens, optimization, cost

Examples

Extraction

User: "Generate BAML to extract invoice data"
Output: Invoice class, ExtractInvoice function, tests, FastAPI integration

Classification

User: "Create sentiment classifier"
Output: Sentiment enum, ClassifySentiment function, confidence scoring

RAG

User: "Build citation-aware search"
Output: Citation class, SearchWithCitations function, source tracking

Agents

User: "Create planning agent"
Output: Task/Plan types, PlanExecution function, state management

Maintenance

Pattern Updates:

Query latest repository versions dynamically
No manual updates required
MCP provides real-time freshness

Skill Updates:

Monitor token budget (<4000)
Update compression algorithms
Refine validation rules
Add new pattern categories

Token Count: ~3800 tokens (validated) Last Updated: 2025-01-30 Version: 1.2.0 - Two-phase MCP validation (baml_Examples → baml_Docs) Ready for Production: Yes