Creating Custom Skills

This guide teaches you how to create custom Agent Skills for StudioBrain. Skills are YAML files that define AI agent capabilities for content generation, analysis, and narrative assistance.

Understanding Skill Structure

File Location

Skills are stored in the _Skills/ directory at your project root:

YourProject/
  _Skills/
    character_writer.yml
    location_writer.yml
    your_custom_skill.yml  # Your custom skills go here

Basic Structure

A skill file is a YAML document with the following required and optional fields:

# Required Fields
skill_id: unique_identifier
name: Display Name
description: What this skill does
applies_to: Target entity or document type
category: Classification category
 
# Optional Fields (with defaults)
version: "1.0"
capabilities:
  - capability_one
  - capability_two
prompts:
  system: |
    System prompt for AI behavior
tags:
  - tag1
  - tag2
min_tier: free

Field Reference

Creating a New Skill from Scratch

Step 1: Define the Skill ID

Choose a unique, descriptive skill_id:

• Use lowercase letters and underscores
• No spaces or special characters
• Follow naming conventions: {purpose}_{type}

skill_id: my_custom_validator

Step 2: Add Basic Metadata

name: My Custom Validator
description: Validates content against custom business rules
applies_to: DOC_GAME_MECHANICS
category: validation

Step 3: Define Capabilities

List the specific capabilities this skill provides:

capabilities:
  - rule_validation
  - consistency_check
  - edge_case_detection

Common capability patterns:

• Generation: content_generation, outline_creation, section_expansion
• Validation: rule_validation, consistency_check, quality_assessment
• Analysis: pattern_detection, trend_analysis, gap_identification
• Transformation: format_conversion, style_adjustment, length_optimization

Step 4: Write the System Prompt

The system prompt guides AI behavior. It should:

• Define the AI’s role and expertise
• Specify the approach and methodology
• Include examples when helpful
• Set expectations for output quality

prompts:
  system: |
    You are a game mechanics validator with expertise in balancing,
    edge case detection, and rule consistency. Your role is to review
    game mechanics documentation and identify:
    
    1. Inconsistent rule definitions
    2. Unbalanced mechanics
    3. Missing edge case handling
    4. Contradictions with other systems
    
    When reviewing, provide specific feedback with line references
    and concrete suggestions for improvement.

Step 5: Add Tags and Tier

tags:
  - validation
  - game-mechanics
  - quality-assurance
min_tier: indie

Complete Example

Here’s a complete custom skill file:

skill_id: game_mechanics_validator
name: Game Mechanics Validator
description: Validates game mechanics documentation for consistency and balance
version: "1.0"
capabilities:
  - rule_validation
  - consistency_check
  - edge_case_detection
  - balance_assessment
prompts:
  system: |
    You are a game mechanics validator with expertise in balancing,
    edge case detection, and rule consistency. Your role is to review
    game mechanics documentation and identify:
    
    1. Inconsistent rule definitions
    2. Unbalanced mechanics
    3. Missing edge case handling
    4. Contradictions with other systems
    
    When reviewing, provide specific feedback with line references
    and concrete suggestions for improvement.
applies_to: DOC_GAME_MECHANICS
category: validation
tags:
  - validation
  - game-mechanics
  - quality-assurance
min_tier: indie

Advanced Skill Configuration

Adding Custom Prompts

Skills can have multiple prompt types beyond system:

prompts:
  system: |
    You are a specialized agent for [purpose].
  
  task: |
    Specific task instructions for the AI to follow.
  
  output_format: |
    Define the expected output format (JSON, markdown, etc.).
  
  examples: |
    Provide few-shot examples of desired behavior.

Defining Parameters

Skills can accept runtime parameters:

parameters:
  max_tokens: 500
  temperature: 0.7
  context_window: 2000
  include_analysis: true
  strict_mode: false

These parameters can be configured when the skill is used.

Adding Skill Definitions

The definition field can contain structured skill configuration:

definition:
  rules:
    - rule_id: required_fields
      fields:
        - name
        - description
        - status
    - rule_id: field_types
      validations:
        - field: age
          type: number
          min: 0
  workflows:
    - name: basic_validation
      steps:
        - validate_required
        - check_types
        - verify_consistency

Using Skills in AI Generation

Skill Discovery

When generating content, StudioBrain automatically:

1. Scans the _Skills/ directory
2. Loads all valid skill files
3. Filters skills by applies_to matching the current content type
4. Applies enabled skill prompts to the AI generation

Example: Character Generation

When generating a Character:

1. System finds character_writer.yml (applies_to: “Character”)
2. Loads the system prompt from prompts.system
3. Merges it with the generation prompt
4. AI generates character with Character Writer guidance

Example: Script Generation

When generating a DOC_SCRIPT:

1. System finds script_writer.yml (applies_to: “DOC_SCRIPT”)
2. Applies Script Writer’s formatting and dialogue rules
3. Ensures industry-standard script format

Testing Skills

Manual Testing

1. Install the skill:

   POST /api/agent-skills/tenant/install
   {
     "skill_id": "your_skill_id",
     "source": "local"
   }

2. Enable the skill:

   POST /api/agent-skills/tenant/your_skill_id/enable

3. Generate content: Use the AI Workshop to generate content matching the skill’s applies_to

4. Review output: Check if the skill’s guidance is reflected in the generated content

API Testing

Test skill loading and discovery:

# List all available skills
GET /api/agent-skills
 
# Get specific skill details
GET /api/agent-skills/your_skill_id
 
# Check enabled skills for tenant
GET /api/agent-skills/tenant/enabled

Console Output

When StudioBrain loads skills, it logs discovery:

DEBUG: Discovered 5 skills in _Skills/
INFO: Loading skill: character_writer.yml
INFO: Loading skill: location_writer.yml
INFO: Loading skill: your_custom_skill.yml

Best Practices

1. Clear, Specific Prompts

• Write prompts that define the AI’s role precisely
• Include examples when the task is complex
• Set clear expectations for output quality

2. Meaningful Capabilities

• Use descriptive capability names
• Group related capabilities logically
• Document what each capability does

3. Proper Categorization

• Match category to the skill’s purpose
• Use common categories: entity, document, narrative, validation, generation
• Add relevant tags for discoverability

4. Version Control

• Start with version “1.0”
• Increment version when making breaking changes
• Document changes in version history

5. Tier Appropriateness

• Use free for skills that add value to all users
• Use indie for specialized tools
• Use team/enterprise for advanced features

6. Testing Before Deployment

• Test skill in development environment
• Verify skill loads without errors
• Confirm skill produces expected output
• Check performance impact

Common Patterns

Validation Skills

Validation skills check content against rules:

skill_id: content_validator
name: Content Validator
applies_to: DOC_GAME_MECHANICS
category: validation
capabilities:
  - rule_validation
  - consistency_check
  - quality_assessment
min_tier: indie

Generation Skills

Generation skills help create content:

skill_id: outline_generator
name: Outline Generator
applies_to: DOC_GDD
category: generation
capabilities:
  - outline_creation
  - section_expansion
  - structure_optimization
min_tier: free

Analysis Skills

Analysis skills provide insights:

skill_id: gap_analyzer
name: Gap Analyzer
applies_to: DOC_STYLE_GUIDE
category: analysis
capabilities:
  - pattern_detection
  - gap_identification
  - recommendation_generation
min_tier: indie

Troubleshooting

Skill Not Loading

Problem: Skill file exists but doesn’t appear in skill list

Check:

1. File is in _Skills/ directory
2. File has .yml or .yaml extension
3. File contains skill_id field
4. YAML syntax is valid

Debug:

# Check skill discovery logs
# Look for: "Discovered X skills in _Skills/"

Skill Not Applying

Problem: Skill is enabled but doesn’t affect generation

Check:

1. applies_to matches the entity/document type
2. Skill is enabled for tenant
3. AI generation is using the correct content type

Debug:

# Check enabled skills
GET /api/agent-skills/tenant/enabled
 
# Verify skill applies to content type
# Check skill's applies_to field matches your entity type

YAML Syntax Errors

Problem: Skill fails to load due to YAML errors

Common Issues:

• Indentation errors (use spaces, not tabs)
• Missing colons after keys
• Unclosed quotes
• Invalid characters

Tools:

• Use a YAML linter (e.g., yamllint)
• Test YAML in online validator
• Check indentation carefully

Creating Skills for Template Packs

Skills can be bundled with template packs for distribution:

1. Include skill files in your template pack’s _Skills/ folder
2. Document skill usage in template pack README
3. Test skill integration with template content
4. Version skills appropriately for template updates

Next Steps

• YAML Schema Reference - Complete schema documentation
• API Reference - Manage skills via API
• Plugin Development - Extend with plugins

Resources

• Existing skills in _Skills/ for reference
• Character Writer example
• Location Writer example
• Script Writer example