Agent Skills User Guide

What Are Agent Skills?

Agent Skills are specialized AI capabilities that enhance StudioBrain’s content generation and analysis features. Skills define specific competencies that AI agents can use when creating or evaluating content within your projects.

Think of skills as specialized expertise modules that your AI agents can deploy when needed. Each skill has:

• A purpose (what kind of content it helps create)
• Capabilities (specific abilities it brings to the table)
• Prompts (guidance for AI behavior)
• Target content (which entity types or documents it applies to)

Available Skills

Built-in Skills

StudioBrain comes with 5 built-in skills that work out of the box:

1. Character Writer

Skill ID: character_writer
Category: entity
Applies To: Character entities
Min Tier: Free

Description:
Specialized in creating deep, consistent character profiles with rich backstories and authentic voice.

Capabilities:

• backstory_generation - Create compelling character histories
• personality_modeling - Define consistent personality traits
• relationship_mapping - Map character connections and dynamics
• voice_definition - Establish unique character voices
• motivation_analysis - Define character goals and drives

When to Use:

• Creating new characters with depth and consistency
• Enhancing existing characters with backstory
• Ensuring character voice remains consistent across all content
• Developing character arcs and motivations

Example Usage: When generating a character profile, the Character Writer skill ensures:

• Character motivations are specific and personal
• Personality traits are grounded in their history
• Voice is defined through vocabulary, rhythm, and subtext
• Surface goals differ from deeper needs (character complexity)

2. Location Writer

Skill ID: location_writer
Category: entity
Applies To: Location entities
Min Tier: Free

Description:
Specialized in writing immersive location descriptions with atmosphere, history, and sensory detail.

Capabilities:

• atmosphere_creation - Establish mood and ambiance
• spatial_description - Define physical spaces and layouts
• environmental_storytelling - Convey narrative through setting
• point_of_interest_design - Create explorable elements
• lore_integration - Connect locations to broader world

When to Use:

• Creating immersive, lived-in locations
• Writing environmental descriptions that tell stories
• Designing points of interest that reward exploration
• Connecting locations to factions, events, and characters

Example Usage: When describing a location, the Location Writer skill ensures:

• The dominant sensory impression is established first
• Details suggest history and purpose
• Locations feel like they existed before the player arrived
• References to the broader world create connectivity

3. Script Writer

Skill ID: script_writer
Category: document
Applies To: DOC_SCRIPT documents
Min Tier: Free

Description:
Specialized in writing game scripts, dialogue trees, and narrative sequences in industry-standard format.

Capabilities:

• dialogue_writing - Craft natural, character-driven dialogue
• scene_description - Write concise action lines
• cutscene_scripting - Create cinematic sequences
• branching_narrative - Design conditional dialogue trees
• character_voice - Maintain consistent character speech patterns

When to Use:

• Writing game dialogue and conversations
• Creating cutscene scripts
• Designing branching narrative structures
• Documenting interactive narrative sequences

Example Usage: When writing scripts, the Script Writer skill ensures:

• Character names in ALL CAPS before lines
• Stage directions in parentheses
• Natural, purposeful dialogue with subtext
• Proper script formatting for actor readability
• Consideration for how dialogue will feel when voiced

4. GDD Writer

Skill ID: gdd_writer
Category: document
Applies To: DOC_GDD documents
Min Tier: Free

Description:
Specialized in writing Game Design Documents with professional structure and depth.

Capabilities:

• outline_generation - Create structured document outlines
• section_expansion - Expand outlines into full sections
• consistency_check - Ensure design consistency
• mechanics_documentation - Detail game mechanics precisely
• feature_specification - Define feature requirements

When to Use:

• Creating professional Game Design Documents
• Documenting game mechanics and systems
• Writing feature specifications for engineers
• Maintaining design documentation consistency

Example Usage: When writing GDD sections, the GDD Writer skill ensures:

• Clear purpose and design goals are stated
• Detailed mechanics descriptions are provided
• Edge cases are documented
• Player-facing implications are explained
• Use of numbered lists, tables, and clear headers

5. Style Guide Writer

Skill ID: style_guide_writer
Category: document
Applies To: DOC_STYLE_GUIDE documents
Min Tier: Free

Description:
Specialized in writing visual style guides, brand identity documents, and art direction references.

Capabilities:

• visual_language_definition - Define visual systems
• color_palette_documentation - Specify exact color values
• typography_specification - Define font choices and usage
• art_direction - Provide visual direction
• consistency_enforcement - Ensure visual consistency

When to Use:

• Creating visual style guides
• Documenting brand identity systems
• Writing art direction references
• Establishing visual design standards

Example Usage: When writing style guides, the Style Guide Writer skill ensures:

• Color values in hex and RGB are specified
• Typography includes weights, sizes, and spacing
• Visual hierarchy rules are clear
• Do/don’t examples are provided
• No ambiguous directions like “use warm tones”

Installing Skills

Auto-Installation

Many skills are automatically installed when you:

• Create a new project
• Import a template pack that includes skills
• Upgrade to a tier that includes specific skills

Manual Installation

To manually install a skill:

Via API

POST /api/agent-skills/tenant/install
Content-Type: application/json
Authorization: Bearer {your_token}
 
{
  "skill_id": "character_writer",
  "source": "marketplace"
}

Via Admin Panel (Coming Soon)

The admin panel will provide a visual interface for browsing and installing skills from the marketplace.

Installing from Template Packs

Skills can be bundled with template packs. When you import a template pack:

1. Navigate to Settings → Templates
2. Select Import Template Pack
3. Choose your template pack file
4. The included skills will be automatically installed

Enabling and Disabling Skills

Once installed, skills can be enabled or disabled without uninstalling:

Enable a Skill

POST /api/agent-skills/tenant/{skill_id}/enable
Authorization: Bearer {your_token}

Disable a Skill

POST /api/agent-skills/tenant/{skill_id}/disable
Authorization: Bearer {your_token}

Why Disable Instead of Uninstall?

• Quick toggling: Easily enable/disable during development
• Preserve configuration: Installation metadata is retained
• Reinstall later: Can be re-enabled at any time

Uninstalling a Skill

To completely remove a skill:

DELETE /api/agent-skills/tenant/{skill_id}
Authorization: Bearer {your_token}

Warning: Uninstalling removes all installation metadata. The skill will need to be reinstalled to be used again.

Checking Installed Skills

List All Installed Skills

GET /api/agent-skills/tenant/installed
Authorization: Bearer {your_token}

List Only Enabled Skills

GET /api/agent-skills/tenant/installed?enabled_only=true
Authorization: Bearer {your_token}

Get Enabled Skills with Full Definitions

GET /api/agent-skills/tenant/enabled
Authorization: Bearer {your_token}

This returns skills with their complete definitions merged, making it easy to see what capabilities are active.

Configuration Options

Skill Parameters

Some skills accept configurable parameters. These are defined in the skill’s parameters field and can be customized per-tenant.

Example parameters:

{
  "max_tokens": 500,
  "temperature": 0.7,
  "context_window": 2000
}

Tier Requirements

Skills have min_tier values that determine which subscription tiers can use them:

• free: Available to all users
• indie: Requires Indie tier subscription
• team: Requires Team tier subscription
• enterprise: Requires Enterprise tier subscription

Source Tracking

Skills track their installation source:

• marketplace: Downloaded from the skills marketplace
• template_pack: Included with a template pack
• local: Created locally

This metadata helps with auditing and troubleshooting.

Troubleshooting

Skill Not Found

Error: Skill 'xyz' not found

Possible Causes:

• Skill doesn’t exist in the registry
• Typo in skill_id

Solutions:

1. Verify the skill_id is correct
2. Check /api/agent-skills to see available skills
3. Ensure you’re using the exact skill_id (case-sensitive)

Skill Not Installed

Error: Skill 'xyz' not installed for this tenant

Possible Causes:

• Skill hasn’t been installed yet
• Skill was uninstalled

Solutions:

1. Install the skill first:

   POST /api/agent-skills/tenant/install
   {
     "skill_id": "xyz",
     "source": "marketplace"
   }
2. Check installed skills: GET /api/agent-skills/tenant/installed

Permission Denied

Error: Admin access required

Possible Causes:

• Attempting admin-only operations (registry management)
• Insufficient user role

Solutions:

• For tenant operations: Ensure you have a valid user token
• For registry operations: Use an admin or owner account

Skill Not Working

If a skill isn’t producing expected results:

1. Check if skill is enabled:

   GET /api/agent-skills/tenant/installed?enabled_only=true

2. Verify skill applies to your content:

   • Check the applies_to field in skill definition
   • Ensure your entity type matches

3. Check AI service status:

   GET /api/services/status

4. Review skill definition:

   GET /api/agent-skills/{skill_id}

Common Issues by Skill

Character Writer Issues

• Problem: Characters lack depth

  • Solution: Ensure Character Writer is enabled for character generation
  • Check: Character generation prompts include system instructions

• Problem: Inconsistent character voices

  • Solution: Verify character profiles include voice definition fields
  • Check: Character Writer is applied during generation

Location Writer Issues

• Problem: Locations feel flat

  • Solution: Enable Location Writer for location creation
  • Check: Location generation includes sensory details

• Problem: No environmental storytelling

  • Solution: Ensure location definitions include history and purpose fields

Script Writer Issues

• Problem: Dialogue feels unnatural

  • Solution: Enable Script Writer for script documents
  • Check: Script format follows industry standards

• Problem: Branching not working correctly

  • Solution: Verify branching narrative structure in script definition
  • Check: Conditionals are properly defined

GDD Writer Issues

• Problem: GDD sections are incomplete

  • Solution: Enable GDD Writer for GDD documents
  • Check: Document type is DOC_GDD

• Problem: Inconsistent formatting

  • Solution: Review GDD Writer prompts for formatting rules
  • Check: Template includes proper section structure

Style Guide Writer Issues

• Problem: Vague style descriptions

  • Solution: Enable Style Guide Writer for style guide documents
  • Check: Style guide includes specific values (not just descriptions)

• Problem: Missing visual specifications

  • Solution: Ensure style guide includes color hex values, typography specs
  • Check: Style Guide Writer is applied during creation

Best Practices

1. Install only needed skills: Each skill adds processing overhead. Install skills relevant to your content types.

2. Enable skills per workflow: Disable skills when not needed to reduce AI processing time.

3. Monitor usage: Check usage_count in skill definitions to see how widely skills are used.

4. Review skill definitions: Understand what each skill does before enabling.

5. Test before committing: Disable/enable skills to test different generation approaches.

6. Keep skills updated: Admins should review and update skill definitions regularly.

Next Steps

• API Reference - Full API documentation
• Creating Skills - Developer guide for building custom skills
• _Skills Schema - Complete YAML schema reference

Related Documentation

• AI Workshop - Using AI features in StudioBrain
• Template Authoring - Creating entity templates
• Plugin System - Extending StudioBrain with plugins