Prompts

Prompt Structure

Prompts in Machina Sports use this YAML format:

prompts:
  - type: "prompt"
    title: "Prompt Title"
    name: "prompt-name"
    description: "Description of the prompt purpose"
    instruction: |
      The actual instruction text sent to the model — persona, responsibilities,
      response rules, and anything it should never do. This is the prompt itself;
      everything else here is metadata around it.
    schema:
      title: "SchemaTitle"
      description: "Schema description"
      type: "object"
      properties:
        # Output schema definition

instruction is required — it's the actual text sent to the model. Studio's prompt editor has a dedicated "Instructions" tab for it, separate from Metadata and Schema. The schema section defines the expected structure of the AI's response, ensuring consistent and properly formatted outputs.

TIP

Quick Action: Create your first prompt in Developer Studio → Prompts → New Prompt and use the schema validator to test output format.

Real-World Examples

Chat Completions Prompt

Use this example for chat completions:

- type: "prompt"
  title: "Chat Completions Prompt"
  name: "chat-completions-prompt"
  description: "This prompt generates a chat completion response to user questions."
  instruction: |
    you are a statistics assistant. provide expert statistical analysis and insights
    to help users understand sports performance and trends.

    key responsibilities:
    - analyze team and player statistics
    - provide performance insights and trends
    - suggest statistical patterns and correlations
    - explain statistical metrics and indicators

    forbidden:
    - guarantee of future outcomes
    - emotional or biased analysis
    - unverified data sources

    remember: provide clear, accurate statistical analysis while maintaining
    objectivity.
    # (trimmed here — the real instruction also covers response rules and content
    # focus in more detail)
  schema:
    title: "ChatCompletions"
    description: "This schema defines the structure for generating chat completion responses."
    type: "object"
    properties:
      choices:
        type: "array"
        description: "List of chat completion choices."
        items:
          type: "object"
          properties:
            index:
              type: "integer" 
            message:
              type: "object"
              properties:
                role:
                  type: "string"
                  description: "The role of the message."
                content:
                  type: "string"
                  description: "The content of the message."
      object:
        type: "string"
        description: "The object of the chat completion."

Team Summary Prompt

Generate NBA team summaries with this example:

- type: "prompt"
  title: "NBA Team Summary Prompt"
  name: "nba-team-summary-prompt"
  description: "This prompt generates a comprehensive NBA team summary with focus on championship history and achievements."
  schema:
    title: "NBATeamSummary"
    description: "This schema defines the structure for generating comprehensive NBA team summaries with focus on championship history."
    type: "object"
    properties:
      snippets:
        type: "array"
        description: "An array of snippets providing detailed analysis of the NBA team."
        items:
          type: "object"
          properties:
            title:
              type: "string"
              description: "The category of team analysis (e.g., 'Team Overview', 'Championship History', 'Notable Achievements')."
            content:
              type: "string"
              description: "Detailed analysis of the team, including history, championships won, championship seasons, and other notable achievements."
            confidence:
              type: "number"
              description: "The confidence score for the accuracy of the team analysis (0.0 to 1.0)."
          required: ["title", "content", "confidence"]
        minItems: 2
        maxItems: 2
    required: ["snippets"]

TIP

Tip: Create a library of reusable schema components to maintain consistency across prompts and speed up development.

Using Prompts in Workflows

Add prompts to workflows as tasks to generate content or process data:

- type: "prompt"
  name: "nba-team-summary-prompt"
  description: "Generate comprehensive NBA team summary with championship history"
  condition: "$.get('team-profile') is not None"
  connector:
    name: "google-genai"
    command: "invoke_prompt"
    model: "gemini-2.5-pro"
    location: "global"
    provider: "vertex_ai"
  inputs:
    team_name: "$.get('team_name')"
    team_full_name: "$.get('team_market') + ' ' + $.get('team_name')"
    championships_won: "$.get('championships_won')"
    championship_seasons: "$.get('championship_seasons')"
  outputs:
    team-summary: "$"
    snippets: |
      [
        {
          'subject': '$.(team_full_name)',
          'text': c.get('content', ''),
          'title': f"$.(team_full_name) - {c.get('title', '')}"
        }
        for c in $.get('snippets', [])
      ]

TIP

Quick Action: Test your prompt in isolation using the "Test" button before integrating it into a workflow.

Schema Components

Basic Types

• string: Text values
• integer: Whole numbers
• number: Decimal numbers
• boolean: True/false values
• array: Lists of items
• object: Nested structures with properties

Constraints

• required: List of required properties
• minItems/maxItems: Limits on array length
• minimum/maximum: Limits on numeric values
• pattern: Regex pattern for string validation

Common Prompt Patterns

Structured Content Generation

Define schemas for generating articles, summaries, or reports with consistent sections.

Conversational Responses

Create prompts for natural dialogue with users, including follow-up questions.

Data Analysis

Design prompts that analyze sports data and extract insights or predictions.

Multi-format Outputs

Generate content that includes different components like titles, body text, and metadata.

TIP

Tip: Start with simple prompts and gradually add complexity as you validate outputs. This approach helps maintain quality as you scale.

Best Practices

• Use descriptive schema property names and descriptions
• Include examples in descriptions to guide the AI
• Define clear constraints to ensure consistent outputs
• Test prompts with various inputs to ensure robust responses
• Use appropriate models for different prompt complexity levels

Next Steps

• Build a Workflow to orchestrate your prompts
• Connect Data Sources to feed your prompts
• Deploy an Agent that uses your prompts
• Test and Refine your prompts with real data