Skill is install-location independent: SKILL_DIR concept (loaded-from folder) replaces project-root assumption; all command forms use %USERPROFILE%\.agent\skills\h3-plan-gate; generated files go to the working folder; README install section rewritten for global skills dirs (.clinerules/.cline kept as repo-workspace extras)

This commit is contained in:
Z User 2026-10-31 00:49:45 +00:00
parent eb1b626648
commit dc8d9fab81
2 changed files with 43 additions and 36 deletions

View File

@ -319,18 +319,20 @@ output).
grammar-constrained JSON if the server supports it. Each scene turn is ≈5k tokens, so
ctx 16384 is comfortable; 128k runs the whole workflow many times over.
### Running the skill inside Cline (VS Code + llama.cpp)
### Installing the skill (any agent harness, any working folder)
1. Clone this repo and open the **repo root** as the workspace — Cline loads `.clinerules/`
and `.cline/skills/` from the workspace root only.
2. Provider: **OpenAI Compatible**, Base URL `http://localhost:8080/v1` (your
`llama-server`), any Model ID, context 32768 or more (`-c 131072` is comfortable).
3. Ask for a plan normally (`.clinerules` routes the agent to `h3-plan-gate/SKILL.md`), or
type `/h3-plan` with the story and scene count — the workflow in
`.clinerules/workflows/h3-plan.md` runs the skill end to end, including the
outline-approval pause.
4. `.cline/skills/h3-plan-gate/` is a stub that registers the skill with Cline's skill
system; the real procedure stays in `h3-plan-gate/SKILL.md` (single source of truth).
5. Approvals: enable auto-approve for reading files and executing commands (local model,
nothing to spend), or approve each call — the skill pauses by itself at the
outline-approval step either way.
Copy the whole `h3-plan-gate/` folder into the harness's skills directory — Windows:
`%userprofile%\.agent\skills\h3-plan-gate\`; macOS/Linux: `~/.agent/skills/h3-plan-gate/`.
The folder is self-locating: `SKILL.md` resolves its own scripts, prompt files and worked
examples from wherever it is installed (SKILL_DIR), while all generated files
(`outline.json`, `scene_*.json`, `plan.json`) are written to the working folder. Updating
the skill = `git pull` in a clone, then re-copy the folder.
The `.clinerules/` and `.cline/skills/` folders in this repo are only for working inside a
clone of the repo itself (workspace-level rules and the `/h3-plan` slash workflow). They
are not needed once the skill is installed globally — just ask for a plan in plain chat.
Local models in Cline: provider **OpenAI Compatible**, Base URL `http://localhost:8080/v1`
(your `llama-server`), any Model ID, context 32768 or more (`-c 131072` is comfortable).
Enable auto-approve for reading files and executing commands (local model, nothing to
spend) — the skill still pauses by itself at the outline-approval step.

View File

@ -3,8 +3,9 @@ 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. The skill lives in the h3-plan-gate folder of the
project; all commands run from the project root with the project's Python.
or validate an existing H3 plan JSON. The scripts and prompt files live next to this
SKILL.md (the skill's install folder); run them from the user's working folder, where
all generated files are written.
---
# H3 Plan Gate — agent procedure
@ -20,16 +21,20 @@ never compose a scene from a guide the user has not approved.
## Paths and Python (read first — these exact forms prevent most errors)
- Work from the **project root**: the folder that contains `h3-plan-gate/`. Every path below
is relative to it. Do not cd into `h3-plan-gate`, and do not cd out of the project root.
- Write generated files into the project root: `outline.json`, `scene_01.json`,
`scene_02.json`, … , `plan.json`.
- Python command: on Windows run `.venv\Scripts\python.exe`; if the project has no `.venv`,
use `python` instead; if `python` is not on PATH (or opens the Microsoft Store), use
`py -3`. (macOS/Linux: `.venv/bin/python` or `python`.) The scripts need only the Python
standard library — nothing to install.
- **SKILL_DIR** is the folder this SKILL.md was loaded from — the skill's install folder
(default on Windows: `%userprofile%\.agent\skills\h3-plan-gate`; macOS/Linux:
`~/.agent/skills/h3-plan-gate`). The scripts, prompt files and worked examples all live
in SKILL_DIR, not in the working folder. Every command below uses the Windows default
install path; substitute your real SKILL_DIR if it differs.
- Work in the user's **working folder** (the folder open in the editor). Write generated
files there: `outline.json`, `scene_01.json`, `scene_02.json`, … , `plan.json`. Never
write generated files into SKILL_DIR.
- Python command: Windows `py -3` (or `python`); macOS/Linux `python3`. If the working
folder has a `.venv`, its interpreter works too (`.venv\Scripts\python.exe` /
`.venv/bin/python`). The scripts need only the Python standard library — nothing to
install.
- Start every task by running the smoke test under "Before you start". If it fails because
`h3-plan-gate` is missing files, stop and tell the user the folder is incomplete.
SKILL_DIR is missing files, stop and tell the user the skill folder is incomplete.
- **Never read `verify_plan_rules.py` or `build_plan.py`** — run them and work from their
printed output. Cline's read_file is capped by hard-coded budgets that do NOT grow with
the model's context window: about 48,000 characters per read, 2,000 lines per read, and
@ -37,7 +42,7 @@ never compose a scene from a guide the user has not approved.
The ~62 KB validator arrives cut no matter how large `llama-server -c` is. A truncation
notice is Cline's read cap, not repo corruption — do not "fix" truncated files.
- **Never read back one-line JSON files** — `build_plan.py`'s output plan and
`h3_agent_workflow_examples/plan_oneline.json` are one-line JSON (the shipped example is
SKILL_DIR's `h3_agent_workflow_examples/plan_oneline.json` are one-line JSON (the shipped example is
a single 5,807-character line), so a read always ends in `[line truncated]` at character
2,000 and the file looks broken. That is expected. Submit, copy, or move them with a
command; to inspect plan structure, read the pretty-printed `plan.json` in the same
@ -61,8 +66,8 @@ never compose a scene from a guide the user has not approved.
## Before you start (smoke test)
```sh
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check h3-plan-gate/h3_agent_workflow_examples/plan.json
py -3 "%USERPROFILE%\.agent\skills\h3-plan-gate\verify_plan_rules.py"
py -3 "%USERPROFILE%\.agent\skills\h3-plan-gate\build_plan.py" --check "%USERPROFILE%\.agent\skills\h3-plan-gate\h3_agent_workflow_examples\plan.json"
```
Expect the suite to pass and the second command to print
@ -71,7 +76,7 @@ Expect the suite to pass and the second command to print
## Step 1 — Build the scene guide (outline)
The user gives you a story and how many scenes they want. Read **lines 53–156** of
`h3-plan-gate/h3_scene_agent_system_prompt.md` — the PROMPT A section (its ROLE, OUTPUT
SKILL_DIR's `h3_scene_agent_system_prompt.md` — the PROMPT A section (its ROLE, OUTPUT
SHAPE, FIELD RULES, WORKED EXAMPLE and SELF-CHECK are the quality bar); never the whole
~36 KB file. Then write `outline.json` — the guide for every scene — in exactly this
shape:
@ -137,7 +142,7 @@ through the guide first — never straight into a scene file.
## Step 3 — Compose the scenes one at a time
Work only from the approved guide. Before writing scene 1, read **lines 157–568** of
`h3-plan-gate/h3_scene_agent_system_prompt.md` — the PROMPT B section (role, output
SKILL_DIR's `h3_scene_agent_system_prompt.md` — the PROMPT B section (role, output
shape, turn template, SCENE COMPOSITION checklist, craft, audio, dialogue, timing,
worked example, self-check; ~3.6k tokens as a section, versus ~11k for the whole file).
Its SCENE COMPOSITION checklist (subject anchor,
@ -151,8 +156,8 @@ and never summarize. If Cline rejects a scene write with 'Editor input too large
split it with the marker pattern from the rules above.
```sh
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_01.json --index 1 --total 5
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py fragment scene_02.json --index 2 --total 5 --prev scene_01.json
py -3 "%USERPROFILE%\.agent\skills\h3-plan-gate\verify_plan_rules.py" fragment scene_01.json --index 1 --total 5
py -3 "%USERPROFILE%\.agent\skills\h3-plan-gate\verify_plan_rules.py" fragment scene_02.json --index 2 --total 5 --prev scene_01.json
```
(`--total` is the scene count from the outline; `--prev` chains the previous file.)
@ -195,8 +200,8 @@ it write the ONE plan JSON. Never write the plan JSON by hand and never edit fra
prose during the merge. Run:
```sh
.venv\Scripts\python.exe h3-plan-gate/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check plan.json
py -3 "%USERPROFILE%\.agent\skills\h3-plan-gate\build_plan.py" outline.json scene_01.json scene_02.json scene_03.json -o plan.json
py -3 "%USERPROFILE%\.agent\skills\h3-plan-gate\build_plan.py" --check plan.json
```
The merger strips `_handoff`, injects `"prompt_prefix": [""]` and `defaults`, validates
@ -363,7 +368,7 @@ and sampler latent or the video can come out square.
## Short stories (2–4 scenes)
You may use the single-pass prompt instead — read
`h3-plan-gate/h3_plan_json_system_prompt.md` (501 lines: the copyable system prompt is
SKILL_DIR's `h3_plan_json_system_prompt.md` (501 lines: the copyable system prompt is
the text fence spanning lines 30–428; on a limited-context agent read lines 1–230
then 231–501 instead of the whole file), have its rules govern one turn that writes
the whole plan, then run `--check` on the file. The one-turn whole-plan write usually
@ -374,5 +379,5 @@ per-scene iteration, or when the user wants to revise single scenes or the guide
## If you cannot run Python
Fall back to `h3-plan-gate/h3_plan_assembler_system_prompt.md` for the merge, copy fragment
Fall back to SKILL_DIR's `h3_plan_assembler_system_prompt.md` for the merge, copy fragment
text verbatim, and say plainly that the result skipped script validation.