Script Structural Breakdown Skill

English | 中文

A portable skill for turning film, short, episode scene, novel fragment, or story text into a structured production-ready breakdown.

What this skill does

script-structural-breakdown-skill runs a four-stage pipeline:

1. Unit Script — split the source text into continuous, producible narrative units.
2. Rhythm Curve — build tension start/end, primary emotion, turning points, and pacing for each unit.
3. Beat Segmentation — cut beats only when goal, action, relation, information, emotion, or spatial state changes.
4. Beat Detail Completion — fill directing, performance, camera, lighting, blocking, gaze, spatial continuity, editing pace, and sound for every beat.

The skill is resumable: it supports partial results, retry of single stages, and retry of individual beats.

Repository layout

Path	Purpose
skill.yaml	Machine-readable skill manifest
SKILL.md	Execution rules and quality checks
schemas/	JSON Schema for input and output
prompts/	Four stage prompts
examples/	Sample input and partial output
scripts/	Helper scripts for packaging and validation
tests/	Basic pytest tests

Quick start

# Build a prompt package from an input file
python3 scripts/build_prompt_package.py examples/sample_input.json > prompt_package.json

# Validate an output JSON
python3 scripts/validate_output.py examples/sample_output_partial.json

# Run tests
pytest

Skill platform compatibility

This repository follows the common skill conventions:

• skill.yaml declares name, version, entry, input_schema, output_schema, and prompts.
• SKILL.md is the human-readable skill contract.
• schemas/input.schema.json and schemas/output.schema.json define the JSON interface.
• Each prompt in prompts/ corresponds to one stage of the pipeline.

Any skill scanner that reads skill.yaml and the adjacent schema files should recognize this package.

Capabilities

• script_unitization
• rhythm_analysis
• beat_segmentation
• beat_detail_completion
• partial_resume
• stage_retry

Input / Output

• Input: at least script_text. See schemas/input.schema.json.
• Output: structured breakdown with status, stages, unit_script, rhythm_curve, beats, progress, warnings, and source_integrity. See schemas/output.schema.json.

License

MIT License — see LICENSE for details.

---

中文说明

将电影、短片、剧集单场、小说片段或故事文本转换为结构化、可制作的剧本拆解结果。

功能

script-structural-breakdown-skill 执行四阶段流水线：

1. 单元剧本 — 把原文拆分为连续、可制作的叙事单元。
2. 节奏曲线 — 为每个单元建立张力起止、主情绪、转折点和节奏速度。
3. 节拍切分 — 仅在目标、行动、关系、信息、情绪或空间状态发生实质变化时切分节拍。
4. 逐拍补全 — 为每拍补全导演、表演、摄影、灯光、走位、视线、空间连续性、剪辑节奏和声音。

本 Skill 支持断点续跑：可返回部分结果、单独重做某一阶段、或只补全指定节拍。

仓库结构

路径	用途
skill.yaml	机器可读的 Skill 清单
SKILL.md	执行规则与质量检查
schemas/	输入、输出 JSON Schema
prompts/	四阶段提示词
examples/	示例输入与部分输出
scripts/	打包与校验脚本
tests/	pytest 测试

快速使用

# 从输入文件构建提示包
python3 scripts/build_prompt_package.py examples/sample_input.json > prompt_package.json

# 校验输出 JSON
python3 scripts/validate_output.py examples/sample_output_partial.json

# 运行测试
pytest

Skill 平台识别

本仓库遵循通用 Skill 约定：

• skill.yaml 声明 name、version、entry、input_schema、output_schema 和 prompts。
• SKILL.md 是人类可读的 Skill 合约。
• schemas/input.schema.json 与 schemas/output.schema.json 定义 JSON 接口。
• prompts/ 下的每个提示词对应流水线的一个阶段。

任何读取 skill.yaml 及相关 Schema 文件的 Skill 扫描器都应能识别本包。

能力标签

• script_unitization
• rhythm_analysis
• beat_segmentation
• beat_detail_completion
• partial_resume
• stage_retry

输入 / 输出

• 输入：至少包含 script_text。详见 schemas/input.schema.json。
• 输出：结构化拆解，包含 status、stages、unit_script、rhythm_curve、beats、progress、warnings 和 source_integrity。详见 schemas/output.schema.json。

许可证

MIT License — 详见 LICENSE。