Add SKILL.md: Agent Skills entry point for the h3-plan-gate folder
The h3-plan-gate directory is now a drop-in skill for Cline (.cline/skills/ or ~/.cline/skills/) and any Agent-Skills-compatible agent. SKILL.md carries the full agent procedure (outline -> one fragment per turn with per-turn validation -> build_plan.py merge -> delivery notes) plus the condensed craft rules; the prompt .md files remain the deep reference and worked examples stay bundled. README files table updated.
This commit is contained in:
parent
63a4469315
commit
b9b0e41469
@ -13,6 +13,7 @@ scenes can be regenerated without touching the rest.
|
||||
|
||||
| File | Role |
|
||||
|---|---|
|
||||
| `SKILL.md` | Agent Skills entry point — this whole folder is a skill. Cline: copy it to `.cline/skills/h3-plan-gate/` (workspace) or `~/.cline/skills/` (global); any Agent-Skills-compatible agent (Claude Code, Cursor, OpenCode, Codex) can load it too |
|
||||
| `h3_scene_agent_system_prompt.md` | Stage 1 + 2 system prompts: **PROMPT A** (outline planner) and **PROMPT B** (one-scene-per-turn writer with a `_handoff` chain) |
|
||||
| `h3_plan_assembler_system_prompt.md` | Stage 3 LLM merge prompt — only when you cannot run scripts |
|
||||
| `h3_plan_json_system_prompt.md` | Single-pass variant (whole plan in one turn) — fastest for 2–4 scene stories |
|
||||
|
||||
148
h3-plan-gate/SKILL.md
Normal file
148
h3-plan-gate/SKILL.md
Normal file
@ -0,0 +1,148 @@
|
||||
---
|
||||
name: h3-plan-gate
|
||||
description: Turn a story idea into a validated plan_json_input JSON for the MiniMax H3
|
||||
Production Plan node (ComfyUI-MiniMaxH3-Context-Loop). Use when the user wants to plan
|
||||
scenes/shots for H3 video generation, write or extend a scene plan, regenerate one scene,
|
||||
or validate an existing H3 plan JSON. Runs a 3-stage agent workflow (outline → one scene
|
||||
fragment per turn → deterministic merge) and validates every artifact with the bundled
|
||||
node-rule replica before anything is delivered.
|
||||
---
|
||||
|
||||
# H3 Plan Gate
|
||||
|
||||
You are producing the `plan_json_input` JSON for the "Production Plan" node
|
||||
(`MiniMax H3 Context Loop Plan` / `MiniMax H3 Plan (Modern)`) in
|
||||
ComfyUI-MiniMaxH3-Context-Loop. You write the JSONs yourself following the shapes below;
|
||||
the bundled scripts validate and merge them. Never deliver a plan that did not pass
|
||||
`build_plan.py --check`.
|
||||
|
||||
`<skill_dir>` below means the folder containing this SKILL.md. Run every command from your
|
||||
workspace folder, calling the scripts by path. Write generated files into the workspace:
|
||||
`outline.json`, `scene_01.json`, `scene_02.json`, … (zero-padded), `plan.json`.
|
||||
|
||||
## Procedure
|
||||
|
||||
1. **Outline.** Read the PROMPT A section of `<skill_dir>/h3_scene_agent_system_prompt.md`
|
||||
(its WORKED EXAMPLE is the quality bar). From the user's story idea, write `outline.json`
|
||||
in exactly this shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "short_snake_case_name",
|
||||
"defaults": { "duration_seconds": 10, "steps": 20 },
|
||||
"style_and_cast": {
|
||||
"subjects": ["<Subject 1> — who they are; wardrobe head to toe; build; hair"],
|
||||
"style": "one consistent look: photoreal or otherwise, lighting, palette, camera feel",
|
||||
"soundscape_seed": "the base ambient sound carried across all scenes"
|
||||
},
|
||||
"scenes": [
|
||||
{ "index": 1, "id": "scene_one_name", "duration_seconds": 10,
|
||||
"beat": "one sentence: what happens AND where the scene ends",
|
||||
"dialogue": [] }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
3–12 scenes unless the user names a count (hard max 128). Ids unique lowercase
|
||||
snake_case, never renamed later. Durations whole seconds 2–15 (prefer 5–15). Copy the
|
||||
user's quoted speech EXACTLY into the right scene's `dialogue` array; no quoted speech
|
||||
anywhere means every array stays `[]`. Only the last scene's beat may come to rest.
|
||||
|
||||
2. **Scenes, one per turn.** Before writing scene 1, read the PROMPT B section of the same
|
||||
file. Then write ONE fragment file per scene in story order, in exactly this shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "from the outline row",
|
||||
"duration_seconds": 15,
|
||||
"prompt": [
|
||||
"integrated_multimodal_description: [Shot 1] ...",
|
||||
"overall_soundscape: ...",
|
||||
"non_diegetic_music: N/A"
|
||||
],
|
||||
"_handoff": { "end_state": "...", "soundscape": "...", "dialogue_used": [] }
|
||||
}
|
||||
```
|
||||
|
||||
After each fragment, validate it and fix until it passes:
|
||||
|
||||
```sh
|
||||
python3 <skill_dir>/verify_plan_rules.py fragment scene_01.json --index 1 --total <N>
|
||||
python3 <skill_dir>/verify_plan_rules.py fragment scene_02.json --index 2 --total <N> --prev scene_01.json
|
||||
```
|
||||
|
||||
3. **Merge.** Never write the plan JSON by hand and never edit fragment prose during the
|
||||
merge. Run:
|
||||
|
||||
```sh
|
||||
python3 <skill_dir>/build_plan.py outline.json scene_01.json scene_02.json -o plan.json
|
||||
python3 <skill_dir>/build_plan.py --check plan.json
|
||||
```
|
||||
|
||||
The merger strips `_handoff`, injects `"prompt_prefix": [""]` and `defaults`, and
|
||||
validates everything. Report the delivered frames/seconds it prints. To change a scene,
|
||||
rewrite that one fragment (step 2) and re-merge — never patch the merged plan.
|
||||
|
||||
4. **Deliver.** Tell the user to paste the full contents of `plan.json` into the Plan
|
||||
node's forced STRING input `plan_json_input`. Resolution, context length, audio mode,
|
||||
and `base_seed` stay on the node's widgets (the JSON cannot set them; connect the
|
||||
width/height outputs to the conditioning node and sampler latent or the output can come
|
||||
out square).
|
||||
|
||||
## Craft rules for every fragment (violations fail the validator)
|
||||
|
||||
- Raw JSON only: first char `{`, last char `}`, no markdown fences, no prose, double
|
||||
quotes, no trailing commas, no raw line break inside a string.
|
||||
- The `prompt` array has EXACTLY three lines in this order, each scene rendered as its own
|
||||
single H3 generation, so the bracket number is always `[Shot 1]`:
|
||||
`integrated_multimodal_description:` / `overall_soundscape:` / `non_diegetic_music:`.
|
||||
- The description line is self-sufficient: it re-states `<Subject 1>`, the full wardrobe,
|
||||
and the visual style in EVERY scene — nothing is shared between scenes or from a prefix.
|
||||
- Word budget for the description line: scenes under 10 s aim for ~175 words (never below
|
||||
150); scenes of 10 s or longer carry 200–300. Spend them on blocking, camera path and
|
||||
speed, expression beats, body mechanics, wardrobe behavior, weather on skin and fabric,
|
||||
lighting, and the exact mid-action end point.
|
||||
- Open by continuing the previous `_handoff` end_state ("Continue the same stride",
|
||||
"without resetting the motion", "keep the incoming camera direction"); scene 1 sets the
|
||||
opening. End mid-action except the final scene. No camera cuts inside a scene.
|
||||
- Never compress a change into a stated outcome: a line like "<Subject 1> is now an 18
|
||||
year old man" is FORBIDDEN. Show every transformation (age, wardrobe, weather, lighting,
|
||||
location, size) as a continuous on-screen progression while motion and camera keep
|
||||
flowing.
|
||||
- Soundscape: one or two dense clauses matching the picture, continuing the previous audio
|
||||
bed ("the same rain on glass continues"); diegetic music always named with its in-scene
|
||||
source; `non_diegetic_music: N/A` unless the user asked for a score; sung/spoken words
|
||||
are dialogue and never live in the soundscape line.
|
||||
- Dialogue: silence is the default. Spoken words come only from the outline row or the
|
||||
story, reproduced word for word inside case-sensitive `<d>[English] words</d>` (one space
|
||||
after the marker; other real languages allowed), inside the description line only, with
|
||||
a "silently with mouth {position}" cue before and after every span. Mirror each span in
|
||||
`_handoff.dialogue_used` (words only, no marker); empty array when silent.
|
||||
- `_handoff` must be truthful: `end_state` describes the real final frame (2–3 sentences:
|
||||
pose, motion in progress, camera state); `soundscape` copies the overall_soundscape line
|
||||
character for character.
|
||||
- Keys are exactly `id`, `duration_seconds`, `prompt`, `_handoff`; add `steps` or `seed`
|
||||
only when the user explicitly asked. Every duration 2–15 s.
|
||||
|
||||
## Short stories
|
||||
|
||||
For 2–4 scene stories you may use the single-pass prompt instead
|
||||
(`<skill_dir>/h3_plan_json_system_prompt.md` — one turn produces the whole plan), then run
|
||||
`build_plan.py --check` on it. Use the 3-stage workflow for long stories, per-scene
|
||||
iteration, or when the user wants to revise single scenes.
|
||||
|
||||
## No script execution available
|
||||
|
||||
If you cannot run Python, fall back to the LLM assembler prompt
|
||||
(`<skill_dir>/h3_plan_assembler_system_prompt.md`) for the merge and copy fragments
|
||||
verbatim — and say plainly that the output skipped script validation.
|
||||
|
||||
## Smoke test
|
||||
|
||||
After setup changes, prove the tooling works:
|
||||
|
||||
```sh
|
||||
python3 <skill_dir>/verify_plan_rules.py
|
||||
python3 <skill_dir>/build_plan.py --check <skill_dir>/h3_agent_workflow_examples/plan.json
|
||||
# expect: PLAN OK — 1042 delivered frames = 43.42s
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user