hbg-classical-poem-silk-video: an Agent Skill that keeps classical Chinese poems from being redrawn by the model

The failure mode this skill is written against

Image-to-video models do not animate a painting. They re-render it. A bird becomes three birds, a temple is rebuilt between frames, a willow branch grows a limb it never had, and a horse gains a leg or loses contact with the ground. The README states the problem directly: the point is not that the old painting moves, it is that the old painting does not move wrongly. The skill's stated goal is to keep water ripples, birds, horse hooves, willow branches and robes moving while declaring buildings, mountains, tree trunks, shorelines and human torsos as static anchors. This is aimed at people producing vertical Chinese-art video from classical poems, most likely solo creators and small teams who already have an agent that reads SKILL.md and a Docker runtime that can call an image-to-video model. The repository is Shell, MIT-licensed, and shipped as v0.1.0 on 2026-08-03.

Shot grammar: one verse per scene, two verses per scene for long poems

The parsing stage extracts dynasty, place, season, time, imagery, actions and an emotional arc from the full poem. Scene grouping then follows a fixed rule: four lines or fewer default to one scene per line, longer poems default to two consecutive lines per scene. The README's worked example is Qian Tang Hu Chun Xing, eight lines grouped into four scenes, each roughly nine seconds, joined by three 1.2 second cross dissolves, arriving at 1080x1920, 30fps, H.264 plus AAC, with a final duration of 32.44 seconds. Style is not uniform across those scenes. Under one Chinese-painting quality bar the skill switches channels: ink wash, gongbi, blue-green landscape, figure-and-horse. That is the most interesting design decision in the repository, because it treats style variation as a per-scene parameter rather than a global look, which is the opposite of the usual template that applies one sepia filter to everything.

Four motion rules and the prompt structure that enforces them

The README lists four principles. The camera stays locked, so motion comes from objects inside the painting rather than a post-production push-in. Motion has anchors: wings move around a fixed body centre, ripples spread from a contact point, willow leaves cannot leave the branch. One scene carries one primary action plus one or two environmental secondary actions, because too many simultaneous motions provoke the model to recompose the frame. And the delivered artefact is the encoded MP4, not the browser preview. The action prompt is described as four-part: static anchors, local motion region, a stable ending, and anti-hallucination prohibitions. The prohibitions are concrete: fix the count of subjects and their body centres, forbid duplication, merging, new branches and new silhouettes, restrict a horse to one weight shift or a short step, then check four hooves, ground contact and body consistency. This is the part worth reading even if you never install the skill, because the constraint list reads like a catalogue of specific I2V artefacts rather than generic advice to write better prompts.

Getting it running: installer, Docker contract, and the prerequisite check

Installation has four documented routes. The recommended one is pasting a natural-language block into Codex, Claude Code or another agent that supports SKILL.md, asking it to detect the global skills directory, back up any older version, and verify that SKILL.md, agents, references, scripts and font assets are complete. The scripted route is curl -fsSL https://raw.githubusercontent.com/Mr-funny/hbg-classical-poem-silk-video/main/install.sh | sh, which installs to ${CODEX_HOME:-~/.codex}/skills/classical-poem-silk-video. Adding sh -s -- --claude targets Claude Code instead. Manual installation clones the repository and copies skill/classical-poem-silk-video/ into the same directory. Stills come from the agent's built-in ImageGen, but image-to-video and the optional white-starmark cleanup depend on Mr-funny/hbg-gemini-flow-suite, a Docker container named gemini-flow-suite with the workspace mounted at /workspace and outputs at /data/outputs. The README says to complete a user-controlled authorisation once, following that runtime repository's own instructions, then run skill/classical-poem-silk-video/scripts/check_prerequisites.sh. The runtime contract lives in skill/classical-poem-silk-video/references/runtime-contract.md.

Audio, transitions and the star-mark edge case

Each I2V shot keeps the model's own ambience, and a continuous BGM track can sit under it at low level or be mixed at 100 percent in parallel. Scene joins use xfade on video and acrossfade on the original ambience, with BGM running continuously, which is the mechanism that avoids the black flash and the audio restart that a naive cut produces. There is also a narrow cleanup step: the README says only the white star mark in the lower right is processed, and the traditional red seal is kept as picture content. That distinction is stated as a compliance matter, not just an aesthetic one: the skill processes the white model mark only when the user asks and applicable terms allow it, and deliberate in-frame markings must be preserved. The captions use Ma Shan Zheng, a brush typeface shipped in the skill, laid out in two vertical columns with the right column written first and characters revealed one at a time, with a reserved safe area for vertical inscription planned back at the still-generation stage.

QA runs on the encoded file, not the preview

The QA script is invoked as skill/classical-poem-silk-video/scripts/final_media_qa.sh final.mp4 qa/final. The README lists its outputs: ffprobe.json, blackdetect.log, silencedetect.log, volumedetect.log, frames at 10, 25, 50, 75 and 90 percent plus the last frame, and a contact sheet of the final encode. For targeted checks such as hooves, bird counts or transition midpoints, you supply a TSV of timestamps and labels, for example 8.400 transition-1-mid, and pass it as a third argument. The script's existence is the strongest argument in the repository: it means the acceptance criterion is a re-extracted frame from the encoded video, which is where black frames and audio dropouts actually appear. The README also describes a repair workflow, checking four existing I2V clips for building reconstruction, bird duplication, malformed horse legs, leaf loss, white star marks, caption safe areas and black-frame transitions, and redoing only the failing shots rather than hiding problems behind a post-production push-in.

Where it stops: runtime dependency, stills, and the missing release history

This is not a self-contained tool. Image-to-video lives in a separate repository with its own licence, and the README states plainly that this repository does not redistribute it. The Docker container name, the /workspace and /data/outputs mounts, and the one-time user authorisation are all preconditions; if your container is named differently or mounted elsewhere, the prerequisite script is the first thing that will tell you. Stills are produced by the agent's built-in ImageGen, so the skill is not usable with an agent that lacks it, and the skill does not bundle a still generator of its own. Version history is thin: v0.1.0 is the only release, published at the same timestamp as the last push, so there is no track record of upgrade behaviour and nothing in the material describes a migration path between versions. The install script does back up an existing installation before updating, which is the only upgrade affordance documented. Treat the interface as young: paths, script names and the runtime contract can move before a 1.0.

How it differs from a generic image-to-video workflow

The obvious alternative is a general image-to-video tool such as ComfyUI with an I2V model, or a hosted video generator, driven by hand-written prompts. The difference is not the model. It is that the general workflow gives you one prompt box and one global look, while this skill gives you a fixed shot grammar (one or two verses per scene), a per-scene style channel, a four-part motion prompt with named static anchors and a prohibition list, and a QA script whose blackdetect and silencedetect logs are the acceptance gate. In a hand-rolled setup you would have to invent all of that, and the most likely outcome is the one the README warns about: a slow zoom over a still, with the model quietly rebuilding the temple behind it. The trade-off is that the skill's rules are opinionated. If you want a moving camera, or a style that changes mid-scene, or a poem parsed into scenes that do not follow the one-or-two-line rule, you are working against the skill rather than with it.

Editorial conclusion

Adopt it if you already run the hbg-gemini-flow-suite Docker container and want a repeatable pipeline from poem text to a QA-checked vertical MP4, with the shot grammar and prompt structure already written down. Do not adopt it if you have no Docker I2V runtime, or if you expect the skill to generate stills on its own: stills come from the agent's built-in ImageGen, and image-to-video depends on the separate container. Before committing, verify that check_prerequisites.sh passes against your container name and mounts, and run final_media_qa.sh on one finished clip to confirm the blackdetect and silencedetect output matches what you expect from an xfade and acrossfade edit.

Official sources

1. Issues
2. License: MIT
3. Mr-funny/hbg-classical-poem-silk-video on GitHub
4. README
5. Releases