Img2mo-learn

Overview

Use this skill when the user invokes:

/img2mo-learn <resource-path-or-folder>
img2mo-learn <resource-path-or-folder>

The goal is to turn finished or reference motion assets into reusable project knowledge. Store learned knowledge in the project-level img2mo-knowledge/ folder, never in the installed Codex skill directory during normal work.

Input Resolution

Resolve the argument after img2mo-learn as follows:

1. If it is an existing relative or absolute path, use it directly.
2. If it is a bare name, first try sample\<name>, then output\<name>, then motion\<name>.
3. If it is a folder, inspect likely assets in this order: manifest.json, preview.gif, contact-sheet.*, spritesheet.*, fullframe/, frames/, Spine .json/.atlas/.skel, then videos.
4. If no matching resource exists, report the missing path and ask for the correct path.

Supported resources:

• video files such as .mp4, .mov, .webm;
• PNG frame folders, spritesheets, contact sheets, or GIF previews;
• project outputs from this skill such as output/<action-id>/;
• Spine-style assets such as .json, .atlas, .skel, texture folders;
• local reference-library folders under motion/.

Knowledge Location

Create this structure if missing:

img2mo-knowledge/
|-- index.md
|-- learnings.jsonl
|-- action-patterns.md
|-- style-patterns.md
|-- prompt-patterns.md
`-- failures.md

Append one JSON object per learning session to img2mo-knowledge/learnings.jsonl. Keep Markdown files concise and curated; do not paste huge logs, full prompts, or complete frame listings.

Learning Workflow

1. Identify the resource type.

   • For video: read frame size, fps, duration, and frame count with ffprobe when available.
   • For frame sequences: count frames, inspect canvas sizes, alpha/background, and contact sheet if present.
   • For spritesheets: infer grid/cell count when possible; otherwise describe visible beats.
   • For Spine assets: inspect animation names, bone/slot names, skins, attachments, timeline names, and texture organization without assuming rendered motion if frames are not available.

2. Create review surfaces if useful.

   • For video or frame folders, create temporary or output-side contact sheets and preview GIFs if they do not exist.
   • Do not alter the source resource.
   • Do not store bulky extracted frames in img2mo-knowledge/; store outputs under output/ or tmp/ and reference their paths in JSON.

3. Summarize motion timing.

   • Identify action type: attack, walk, idle, block, suffer, death, born, skill/cast, or other.
   • Record frame count, fps, loop behavior, and major beats.
   • For attacks, prefer beat labels such as guard, anticipation, acceleration, contact, contact hold, follow-through, recovery.
   • Record which frame ranges are most useful as key poses.

4. Summarize pose and topology lessons.

   • Record active limb/feature, weapon or prop owner, anchor limb/surface, facing direction, and stable baseline behavior.
   • Note silhouette expansion, squash/stretch, center drift, foot/bottom baseline, and whether motion needs extra canvas margin.

5. Summarize style lessons.

   • Record line weight, palette, shading, material treatment, outline softness, shape language, effects style, and background/keying considerations.
   • Distinguish character style from detached effects.

6. Summarize prompt lessons.

   • Write reusable prompt clauses that could improve later generation.
   • Keep prompt clauses short and parameterized; avoid overfitting to one character name unless the lesson is character-specific.

7. Summarize failures and constraints.

   • Record what should be rejected: hand swaps, scale popping, bad alpha, cut weapons, over-crowded sheets, text/watermark contamination, or mismatched style.

8. Write project knowledge.

   • Append structured session data to learnings.jsonl.
   • Update the relevant Markdown files with durable, reusable lessons.
   • If the learning is only useful for one output, also write output/<action-id>/retro.md.

JSONL Schema

Each line in img2mo-knowledge/learnings.jsonl should be a compact JSON object:

{
  "id": "learn-YYYYMMDD-HHMMSS-short-name",
  "date": "YYYY-MM-DD",
  "source": "relative/or/absolute/path",
  "resource_type": "video|frame_sequence|spritesheet|spine|output|reference_folder",
  "action_type": "attack|walk|idle|block|suffer|death|born|skill|unknown",
  "fps": 24,
  "frame_count": 14,
  "loop": true,
  "beats": [
    {"name": "anticipation", "frames": "02-04", "notes": "body compresses before strike"}
  ],
  "key_pose_guidance": ["frame 05 should be the clearest contact silhouette"],
  "topology": {
    "active": "screen-left sword hand",
    "anchor": "screen-right hand",
    "weapon_owner": "screen-left hand"
  },
  "style": ["thick dark outline", "warm orange shadow shapes"],
  "prompt_clauses": ["same foot/bottom baseline in every cell"],
  "failure_lessons": ["reject sheets where the weapon hand swaps"],
  "artifacts": ["output/.../contact-sheet.jpg"]
}

Use null for unknown scalar fields and [] for empty lists. Keep one line per session.

Markdown Update Rules

• index.md: list recent learning sessions and high-level tags.
• action-patterns.md: update durable motion timing rules by action type.
• style-patterns.md: update durable visual style observations.
• prompt-patterns.md: update short reusable prompt clauses and anti-clauses.
• failures.md: update rejection checks and known failure modes.

When adding Markdown entries, include the source path and date. Keep entries short enough that /img2motion can read them quickly.

Use During Generation

Later /img2motion work must read img2mo-knowledge/index.md first when it exists. Then read only the relevant knowledge files for the requested action/style:

• action timing: action-patterns.md;
• visual style: style-patterns.md;
• prompt wording: prompt-patterns.md;
• known pitfalls: failures.md;
• detailed recent examples: search learnings.jsonl for matching action_type, source tags, or character style.

Do not let learned knowledge override the current user's explicit request or the current baseline image identity. Treat project knowledge as guidance, not ground truth.