create-config

Create timestamped configuration files for the sports poetry multi-agent workflow using interactive conversation and pre-built utility functions.

Table of Contents

• When to Use This Skill
• Quick Start Example
• Available Utilities
• Conversation Flow
• CRITICAL: Always Create Both Files
• Common Usage Patterns
• Validation & Error Handling
• Troubleshooting
• Configuration Parameters Reference
• File Structure
• Testing
• See Also
• Dependencies

When to Use This Skill

Use this skill when the user:

• Asks to "create a config" or "set up configuration"
• Wants to configure sports poetry generation
• Provides a list of sports and generation preferences
• Needs help understanding configuration options

Quick Start Example

User: "Create a config for basketball, soccer, and tennis"

You: I'll create a configuration for you.
     [Use skill_helpers.py utilities to create both files]

     ✓ Created output/configs/config_20251115_120000.json
     ✓ Created output/configs/generate_config_20251115_120000.py

     Ready to run: python3 orchestrator.py --config output/configs/config_20251115_120000.json

Available Utilities

This skill uses pre-built functions from skill_helpers.py. Import and USE these directly rather than reimplementing:

from skill_helpers import (
    check_api_key,           # Check env vars + .claude/claude.local.md
    create_generator_script, # Generate executable Python script
    get_setup_instructions   # Get API key setup help
)

Key principle: Use these utilities to save tokens and ensure consistency. Don't reimplement their logic.

Conversation Flow

High-Level Steps

1. Collect sports (3-5 required)

   • Validate count using config_builder.with_sports()
   • Normalize to lowercase, check for duplicates
   • config_builder handles validation automatically

2. Ask for generation mode (template or llm)

   • Default: template (fast, no API key needed)
   • If user wants LLM: proceed to step 3
   • If template mode: skip to step 5

3. Check API key (LLM mode only)

   • Use check_api_key(provider) from skill_helpers
   • If found: proceed to step 4
   • If not found: use get_setup_instructions(provider) and offer to switch to template mode

4. Confirm LLM settings (LLM mode only)

   • Provider: "together" or "huggingface" (default: together)
   • Model: Use provider-specific defaults unless user specifies
   • Together.ai default: meta-llama/Llama-3.3-70B-Instruct-Turbo-Free
   • HuggingFace default: meta-llama/Meta-Llama-3-8B-Instruct

5. Ask about retry behavior (optional)

   • Default: true (recommended)
   • Accept: yes/no, true/false, enable/disable

6. Show configuration summary

   • Display all settings before creating files
   • Ask for confirmation: "Proceed? [yes/no]"

7. Create BOTH files (CRITICAL - see below)

   • Config JSON: output/configs/config_{timestamp}.json
   • Generator script: output/configs/generate_config_{timestamp}.py
   • Make generator script executable: chmod +x

CRITICAL: Always Create Both Files

Every successful skill execution MUST create TWO files:

File 1: Configuration JSON

output/configs/config_{timestamp}.json

Created by: config_builder.save(config_path)

File 2: Generator Script

output/configs/generate_config_{timestamp}.py

Created by: create_generator_script() from skill_helpers Made executable with: chmod +x

Failure to create BOTH files is incomplete execution of this skill.

The generator script provides:

• Reproducibility (re-run to create same config with new timestamp)
• Auditability (shows exactly how config was created)
• Self-documentation (includes all parameters in header)

Common Usage Pattern

This example shows both template mode (fast, no API key) and LLM mode (requires API key):

from skill_helpers import check_api_key, get_setup_instructions, create_generator_script
from config_builder import ConfigBuilder
from pathlib import Path
from datetime import datetime
import os, stat

# Configuration
sports_list = ["basketball", "soccer", "tennis"]
use_llm_mode = False  # Set to True for LLM-generated poems
provider = "together"
model = "meta-llama/Llama-3.3-70B-Instruct-Turbo-Free"

# Initialize builder
builder = ConfigBuilder.load_default()
builder.with_sports(sports_list)

# Configure mode-specific settings
if use_llm_mode:
    # Check for API key
    api_key = check_api_key(provider)
    if not api_key:
        print(get_setup_instructions(provider))
        print("\nFalling back to template mode...")
        use_llm_mode = False
    else:
        builder.with_generation_mode("llm")
        builder.with_llm_provider(provider)
        builder.with_llm_model(model)

# Create timestamped config file
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
config_path = Path(f"output/configs/config_{timestamp}.json")
config_path.parent.mkdir(parents=True, exist_ok=True)
builder.save(str(config_path))

# Create generator script (required for reproducibility)
mode = "llm" if use_llm_mode else "template"
script = create_generator_script(
    sports=sports_list,
    mode=mode,
    provider=provider,
    model=model,
    retry=True,
    timestamp=timestamp
)

script_path = Path(f"output/configs/generate_config_{timestamp}.py")
script_path.write_text(script)
os.chmod(script_path, os.stat(script_path).st_mode | stat.S_IEXEC)

print(f"✓ Created {config_path}")
print(f"✓ Created {script_path}")
print(f"\nNext: python3 orchestrator.py --config {config_path}")

Validation & Error Handling

config_builder.py handles all validation automatically:

• Sports count (3-5): Error raised immediately in with_sports()
• Duplicates: Detected and rejected
• Empty strings: Not allowed
• Generation mode: Must be "template" or "llm"
• LLM settings: Required if mode="llm"

You don't need to duplicate validation logic. Just call the builder methods and let them validate.

Error message example:

ConfigValidationError: Must specify at least 3 sports (got 2)

These messages are already helpful - just pass them to the user.

Troubleshooting

Sports Count Validation Error

When config_builder raises a sports count error, provide friendly suggestions:

You provided 2 sports, but we need 3-5.
Suggestions: tennis, volleyball, baseball, hockey, swimming

API Key Issues

For LLM mode API key problems, use check_api_key(provider) and get_setup_instructions(provider) from skill_helpers (see Pattern 2 example), or offer to switch to template mode.

Configuration Parameters Reference

Required

• sports (list, 3-5 items): Sport names for poem generation
• generation_mode (string): "template" or "llm"

Conditional (LLM mode only)

• llm.provider (string): "together" or "huggingface"
• llm.model (string): Model identifier

Optional

• retry_enabled (boolean, default: true): Retry failed agents

Auto-Generated (by orchestrator at runtime)

• session_id: Unique session identifier
• timestamp: ISO 8601 timestamp

File Structure

.claude/skills/create_config/
├── SKILL.md                    # This file
└── skill_helpers.py            # Pre-built utility functions

Testing

After using this skill, verify:

✅ Both files exist:

• output/configs/config_{timestamp}.json
• output/configs/generate_config_{timestamp}.py

✅ Config is valid JSON with required fields

✅ Generator script is executable:

ls -l output/configs/generate_config_*.py
# Should show -rwxr-xr-x (executable)

✅ Generator script can be run:

./output/configs/generate_config_{timestamp}.py
# Should create new config with new timestamp

Multi-Model Validation

This skill has been validated across all Claude models:

• Claude Opus: Full testing with complex configurations
• Claude Sonnet: Primary development and testing model
• Claude Haiku: Lightweight execution validation

All models successfully execute the skill with consistent behavior across template and LLM modes.

See Also

• skill_helpers.py - Utility functions (check API keys, create scripts, etc.)
• tests/test_create_config_skill.py - Evaluation tests and acceptance criteria
• config_builder.py - Python API for config creation and validation
• config.default.json - Default configuration template
• README.md - Project overview and quick start guide

Dependencies

• config_builder.py - Configuration builder with validation
• skill_helpers.py - Utility functions for this skill
• Python 3.7+ - For f-strings and pathlib