read-screen-play

name	read_screen_play
description	Purpose: Read and review the complete screenplay outline with all scene summaries. Capabilities: Retrieve scene metadata, sort by scene number/date/title, filter by status, optionally include full content. Trigger: When user wants to "review outline", "see all scenes", "check story structure", "read screenplay", or needs context before writing.
tools	[{"screen_play (operation":"outline)"}]

Screenplay Outline Reading Skill

This skill allows the agent to read the complete screenplay outline, which is a structured summary of all scenes in the project. It provides a comprehensive view of the story structure, showing scene summaries in chronological order with key metadata.

Capabilities

• Read the complete screenplay outline containing all scene summaries
• Retrieve scene metadata including titles, loglines, locations, characters, and story beats
• Sort scenes by scene number, creation date, update date, or title
• Filter scenes by status (draft, revised, final, approved)
• Optionally include full scene content for detailed review
• Provide structured overview of the entire story structure

Constraints

• Requires Context: This skill requires a valid ToolContext with access to a screenplay manager
• Requires Screenplay Manager: The project must have an initialized screenplay manager with scenes stored
• Read-Only: This skill only reads scenes and does not modify them
• Empty Outline: If no scenes exist, returns an empty outline list
• Uses Tool: This skill uses the screen_play tool internally with the outline operation

Input Requirements

Use the screen_play tool with operation: "outline":

{
  "type": "tool",
  "tool_name": "screen_play",
  "tool_args": {
    "operation": "outline",
    "include_content": false,
    "sort_by": "scene_number",
    "filter_status": null
  }
}

Parameters:

• include_content (boolean, optional, default: false): Include full scene content (metadata only when false).
• sort_by (string, optional, default: "scene_number"): Sort by "scene_number", "created_at", "updated_at", or "title".
• filter_status (string, optional): Filter by status "draft", "revised", "final", or "approved".

Usage

The skill can be invoked when the screenwriter or director needs to:

• Review the overall story structure
• Understand the scene flow and pacing
• Plan revisions or new scenes
• Identify gaps in the narrative
• Get context before writing specific scenes

How to Call This Skill:

This skill is called via the screen_play tool with operation: "outline". The ReAct agent will automatically use the tool when the user requests to read or review the screenplay.

Best Practices:

• Use include_content=false for quick outline review (faster, less data)
• Use include_content=true when detailed scene content is needed for analysis
• Use sort_by="scene_number" to see the story in chronological order
• Use filter_status to focus on specific workflow stages (e.g., only draft scenes)
• The outline provides essential context for writing connected scenes

Output

Returns a JSON object containing:

• success: Boolean indicating if the operation succeeded
• total_scenes: Total number of scenes in the screenplay
• outline: Array of scene objects, each containing:
  • scene_id: Unique scene identifier
  • title: Scene title
  • scene_number: Scene number in sequence
  • logline: Brief scene summary
  • location: Where the scene takes place
  • time_of_day: Time of day for the scene
  • characters: List of characters in the scene
  • story_beat: Story beat or plot point
  • duration_minutes: Estimated duration
  • status: Workflow status
  • content: Full scene content (only if include_content=true)
  • created_at: Creation timestamp
  • updated_at: Last update timestamp
• filtered_by: Status filter applied (if any)
• sorted_by: Sort order used
• message: Human-readable status message

Error Handling

• Returns error if screenplay manager is not available in context
• Returns empty outline if no scenes exist in the project
• Check the success field in the response to verify the operation completed successfully