[misc]: import add-model skill stack to .agents/skills/ (hao-ai-lab#1308)

Co-authored-by: Raghav <ragg04@gmail.com>

Author: SolitaryThinker

.agents/skills/add-model-01-prep/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: add-model-01-prep
+description: Use at the start of a FastVideo model port to gather required inputs, inspect/download HF weights, clone and install the official reference repo in the current environment, create a local_tests README skeleton, and produce a handoff before conversion or implementation.
+---
+
+# Add Model Prep
+
+## Goal
+
+Prepare external assets and the shared parity-test environment for a FastVideo
+model port. Stop before writing conversion scripts, model components, pipeline
+code, registry entries, or executable parity tests.
+
+## Ask First
+
+Ask once, then proceed if the HF token is already exported:
+
+```text
+Before prep: (1) official reference repo or Diffusers pipeline URL, (2) HF repo
+id or local weights path and whether it has a root model_index.json, (3) target
+model_family, (4) workload types, (5) which token env var is exported:
+HF_TOKEN, HUGGINGFACE_HUB_TOKEN, or HF_API_KEY, (6) may I stage clone and
+weights under the FastVideo repo root, and (7) may I install official reference
+dependencies into the current FastVideo conda/env for parity tests?
+```
+
+Useful optional inputs: `pipeline_class`, `reference_dir`, `hf_revision`,
+`official_revision`, `reuse_hints`, `download_scope`.
+
+## Rules
+
+- Follow `../add-model/shared/common_rules.md` for token/auth safety, state files,
+  escape hatches, and skip/pass semantics.
+- Run from the FastVideo repo root.
+- Use repo-relative defaults: `<ReferenceDir>/`,
+  `official_weights/<model_family>/`, `converted_weights/<model_family>/`.
+- Install official reference deps into the current FastVideo environment, not a
+  new venv/conda env, so parity tests run both implementations with one shared
+  numeric stack.
+- If the reference is a Diffusers class/package instead of a cloneable repo,
+  record import path and version instead of cloning.
+- Prep may create only the local-test README and `PORT_STATUS.md` skeletons;
+  executable `.py` parity tests belong to `../add-model-02-parity/SKILL.md`.
+
+## Escape Hatches
+
+Follow `../add-model/shared/common_rules.md`. Prep-specific ask cases include
+overwriting an existing clone or weight directory, installing untrusted/private
+deps, choosing between incompatible official references, large downloads outside
+the agreed scope, or missing gated-repo auth setup by env var name.
+
+## Workflow
+
+1. Verify the repo:
+
+```bash
+git rev-parse --show-toplevel
+```
+
+Expected markers: `fastvideo/`, `scripts/checkpoint_conversion/`,
+`scripts/huggingface/download_hf.py`, `fastvideo/registry.py`.
+
+2. Inspect HF or local weight layout:
+
+```bash
+python ".agents/skills/add-model-01-prep/scripts/inspect_hf_layout.py" \
+    "Org/Model" \
+    --revision "<revision>" \
+    --json
+```
+
+For a local path, replace `Org/Model` with `/path/to/weights`. Record
+`source_layout`, `needs_conversion`, `model_index_class`, and
+`components_seen`.
+
+3. Download HF weights if needed:
+
+```bash
+python ".agents/skills/add-model-01-prep/scripts/download_hf_weights.py" \
+    "Org/Model" \
+    "official_weights/<model_family>" \
+    --revision "<revision>"
+```
+
+For selected files, repeat `--file-name`. For partial snapshots, repeat
+`--allow-pattern` or `--ignore-pattern`. If the user provided a local path,
+record it instead of copying large weights by default.
+
+4. Clone the official reference repo if applicable:
+
+```bash
+python ".agents/skills/add-model-01-prep/scripts/clone_reference_repo.py" \
+    "<official_repo_url>" \
+    "<ReferenceDir>" \
+    --branch "<tag-or-branch>" \
+    --commit "<commit-sha>" \
+    --update-gitignore
+```
+
+Omit `--branch`, `--commit`, or `--update-gitignore` when not needed. The
+helper refuses to overwrite existing paths and prints remote/HEAD instead.
+
+5. Keep prep assets ignored. Ensure `.gitignore` includes relevant entries:
+
+```gitignore
+/<ReferenceDir>/
+/official_weights/
+/converted_weights/
+```
+
+6. Follow the official repo's setup instructions in the current environment.
+Inspect dependency files and README install docs before installing anything:
+
+- `README*`, install docs, or model-card instructions.
+- `requirements*.txt`, `pyproject.toml`, `setup.py`, `environment.yml`.
+
+Use the current FastVideo conda/env. Do not create a new env even if upstream
+docs recommend one; translate the needed install commands into the active env.
+Prefer editable/no-deps first so the official source is importable without
+changing shared pins:
+
+```bash
+uv pip install --no-deps -e ./<ReferenceDir>
+```
+
+Then install only missing official deps needed for parity imports. Stop before
+installing requirements that would change FastVideo's core stack. If upstream
+requires private/non-PyPI deps, record that parity needs a local stub helper
+rather than pretending setup is complete.
+
+7. Create the model-family local test skeleton and top-level port state file:
+
+```bash
+mkdir -p tests/local_tests/<model_family>
+cp ".agents/skills/add-model-01-prep/templates/local_tests_readme.md" \
+    tests/local_tests/<model_family>/README.md
+cp ".agents/skills/add-model-01-prep/templates/port_status.md" \
+    tests/local_tests/<model_family>/PORT_STATUS.md
+```
+
+Edit every placeholder in the README and `PORT_STATUS.md`. The README gives
+later review agents enough information to reproduce the shared environment and
+run/review parity work:
+
+- official code URL or import path, local clone path, and commit/version;
+- HF URL or local weight path, revision, access notes, and token env var name
+  only;
+- commands already run and any blocked official dependency installs;
+- shared-env install commands to re-run without changing core pins;
+- expected local parity test paths and pytest commands;
+- private-dependency stubs or known setup gaps;
+- PR/review notes explaining which parity tests are required before handoff.
+
+Do not include raw tokens, absolute cache paths that are not repo-reproducible,
+or large generated outputs. If prep is blocked before imports work, still create
+the README with `official_env_status=blocked` and the exact blocker.
+
+`PORT_STATUS.md` must follow `../add-model/contracts/port_state.md`. Record open
+questions and prep issues immediately, using stable IDs such as `Q001` and
+`I001`. Keep resolved questions/issues in the table with a resolution instead of
+deleting them.
+
+## Handoff
+
+End with the canonical prep handoff contract from
+`../add-model/contracts/prep_handoff.md` and update the shared state files before
+handoff.
+
+## Helper Scripts
+
+- `scripts/inspect_hf_layout.py`: classify HF/local layout.
+- `scripts/download_hf_weights.py`: download HF snapshot or selected files.
+- `scripts/clone_reference_repo.py`: clone reference repo safely.

.agents/skills/add-model-01-prep/scripts/clone_reference_repo.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Clone an official reference repo without overwriting existing paths."""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Clone a reference repo for FastVideo parity tests."
+    )
+    parser.add_argument("repo_url", help="Official reference repository URL")
+    parser.add_argument("target_dir", help="Directory to clone into")
+    parser.add_argument("--branch", help="Branch or tag to clone")
+    parser.add_argument("--commit", help="Commit SHA to check out after clone")
+    parser.add_argument(
+        "--update-gitignore",
+        action="store_true",
+        help="Add the target directory to .gitignore if missing",
+    )
+    parser.add_argument(
+        "--gitignore",
+        default=".gitignore",
+        help="Path to gitignore file when --update-gitignore is used",
+    )
+    return parser.parse_args()
+
+
+def run(command: list[str], check: bool = True) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        command,
+        check=check,
+        text=True,
+        capture_output=True,
+    )
+
+
+def print_existing_repo_info(target: Path) -> int:
+    print(f"target_exists: {target}")
+    if not (target / ".git").exists():
+        print("error: target exists but is not a git repo", file=sys.stderr)
+        return 1
+
+    remote = run(["git", "-C", str(target), "remote", "-v"], check=False)
+    head = run(["git", "-C", str(target), "rev-parse", "HEAD"], check=False)
+    if remote.stdout:
+        print("remote_v:")
+        print(remote.stdout.rstrip())
+    if head.stdout:
+        print(f"head: {head.stdout.strip()}")
+    print("not_overwritten: true")
+    return 0
+
+
+def gitignore_entry_for(target: Path) -> str:
+    root = Path.cwd().resolve()
+    resolved = target.resolve()
+    try:
+        relative = resolved.relative_to(root)
+    except ValueError as exc:
+        raise ValueError(
+            "--update-gitignore requires target_dir to be under the current directory"
+        ) from exc
+
+    text = relative.as_posix().rstrip("/")
+    return "/" + text + "/"
+
+
+def update_gitignore(path: Path, target: Path) -> bool:
+    entry = gitignore_entry_for(target)
+    existing = path.read_text().splitlines() if path.exists() else []
+    if entry in existing:
+        return False
+
+    new_text = "\n".join(existing).rstrip("\n")
+    if new_text:
+        new_text += "\n"
+    new_text += entry + "\n"
+    path.write_text(new_text)
+    return True
+
+
+def main() -> int:
+    args = parse_args()
+    target = Path(args.target_dir)
+
+    if target.exists():
+        return print_existing_repo_info(target)
+
+    command = ["git", "clone", "--depth", "1"]
+    if args.branch:
+        command.extend(["--branch", args.branch])
+    command.extend([args.repo_url, str(target)])
+
+    try:
+        run(command)
+        if args.commit:
+            run(["git", "-C", str(target), "fetch", "--depth", "1", "origin", args.commit])
+            run(["git", "-C", str(target), "checkout", args.commit])
+    except subprocess.CalledProcessError as exc:
+        if exc.stdout:
+            print(exc.stdout, end="")
+        if exc.stderr:
+            print(exc.stderr, end="", file=sys.stderr)
+        return exc.returncode
+
+    head = run(["git", "-C", str(target), "rev-parse", "HEAD"])
+    print(f"cloned: {target}")
+    print(f"head: {head.stdout.strip()}")
+
+    if args.update_gitignore:
+        changed = update_gitignore(Path(args.gitignore), target)
+        print(f"gitignore_updated: {str(changed).lower()}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())