---
name: navid
description: End-to-end nAvid workflow for creating social videos with HyperFrames across multiple content types. Use when the user invokes /navid, says navid, or asks Codex to create, fix, render, or systematize 9:16 Facebook Reels, TikTok, YouTube Shorts, news recaps, science explainers, myth-vs-fact videos, how-it-works explainers, product promos, storytelling videos, listicles, article-to-video outputs, Vietnamese voiceover videos, CTA/outro sections, TikTok Follow lower-thirds, SFX, captions, contact sheets, or reusable video production workflows.
---

# nAvid

Create professional vertical social videos with a small, deterministic workflow.
HyperFrames is mandatory for every nAvid composition, preview, QA and render workflow.

## Skill Root Anchor

All relative paths in this document and in `references/` resolve from the
**skill root**: the directory that contains this `SKILL.md` file.

When the agent first reads this file, it **must** record the absolute path of
the containing directory as `NAVID_SKILL_ROOT` and use it as the base for
every `templates/`, `references/`, `scripts/` and `agents/` reference.

Example: if the absolute path is
`/path-to-skills/navid/SKILL.md`, then:

- `templates/registry.json` → `/path-to-skills/navid/templates/registry.json`
- `scripts/template_library.py` → `/path-to-skills/navid/scripts/template_library.py`
- `references/template-library.md` → `/path-to-skills/navid/references/template-library.md`

Never hardcode a development or source path. Never resolve these paths
relative to the user's project directory or working directory. The skill root
is portable: it moves with the installed package.

## Public Video Duration Boundary

- A completed public single-video output must run for at least `55` seconds and
  no more than `180` seconds, unless the user explicitly approves a different
  duration for a named deliverable.
- Shorter sequence previews may be used for template QA only; they are not a
  completed public video draft under this workflow.
- Measure the narration and rendered output before QA; if either falls outside
  the approved boundary, revise pacing/content or obtain explicit approval.

## Common Template Asset Contract

The shared TikTok profile card, avatar/brand image, cursor, SFX and default
media assets are mandatory for every current and future template. Before
building, selecting, saving or approving a template, verify
`templates/assets/required-assets.json` and treat any missing required asset as
a workflow blocker.

- TikTok outro/profile UI must use the canonical
  `templates/components/tiktok-profile-card/` component.
- The shared avatar/brand image `ainew247na.jpg` and pointer asset
  `cursor-hand.png` are common assets for all template sets. Portable template
  copies must remain byte-identical to the packaged canonical assets unless a
  documented channel override is explicitly approved.
- A production Follow-to-Following click must include the packaged
  `templates/assets/sfx/follow-click.wav` or a documented rights-cleared
  replacement synchronized to the button press.
- Default `.mp3`, `.mp4` and `.gif` files under
  `templates/assets/default-media/` are install/template-QA placeholders only.
  Public outputs must still generate project-specific narration, rendered MP4
  and topic-specific media.
- Any future template that references a default `.mp3`, `.mp4`, `.gif`, SFX,
  avatar, cursor or profile-card asset must declare an existing packaged file
  in `templates/assets/required-assets.json`.

## Original-Source Anchored Editorial Boundary

- When the user supplies any repo/site/document/social/share URL, treat it as source intake, not publishing metadata. Attempt Crawl4AI first for each supplied URL, then record Markdown or the fallback reason before using browser/API/manual metadata for that source.
- Primary facts about the subject must be anchored to original or official
  material: the original repository, official website, original publisher
  article, official documentation, official release post or publisher-owned
  assets.
- For a video whose subject is the original repo/site/article, a supplied
  sharing post is an editorial input, not the public subject: do not name,
  quote, display or cite that post in narration, on-screen text, storyboard or
  public attribution. Extract its audience hook, promised benefit, practical
  question or notable use case, then write those points as a topic-first hook.
- After extracting a hook from a supplementary source, use the
  original/official source to explain what the product actually is, how it
  works and what limitations or warnings qualify the promise. A hook may say
  a capability is being introduced or sought; it must not silently state a
  stronger verified conclusion than the original source supports.
- Mention a supplementary post publicly only when the user explicitly makes
  that post itself part of the video topic.
- When a supplementary source conflicts with an original/official source,
  prefer the original source and either explain the difference or omit the
  unsupported detail. Never silently merge the two into a stronger claim.

## Output Contract

For a completed single-video draft, create `videos/<project-name>/` with:

- `SCRIPT.md` containing `## Publish Title` before the public voiceover.
- `PUBLISH.md` containing `## Publish Title`, `## Post Caption` and
  `## Hashtags` with exactly 5 hashtags for the ready-to-post package.
- `STORYBOARD.md` describing scene roles and evidence/illustration intent.
  For tool, repository, product or workflow videos, it must also include a
  target-audience/use-case beat explaining who should use it and for what
  practical purpose.
- For GitHub/repository videos, `capture/repo-evidence-digest.json` or `.md`
  with API-minimized repo facts, Crawl4AI web digests, metrics and selected images.
- When user-supplied URLs exist, `capture/crawl4ai/*.md` for useful crawl output or a recorded Crawl4AI attempt/fallback in `capture/source-record.json` and `run-state.json` before scripting.
- `voiceover.txt` and the generated narration asset.
- HyperFrames `index.html` plus local media/SFX and topic-specific assets (screenshots, images, GIFs) under `assets/` referenced by the composition.
- `renders/<project-name>.mp4`.
- A contact sheet or representative check frames when visual QA is required.
- `run-state.json` recording resolved intake, stage validity and quality decisions.
- `assets/` directory containing actual, topic-specific illustrations/proof (no placeholder or copied files from unrelated projects).

Template repository details are loaded only when existing-template selection,
recommendation or library maintenance is needed. For a batch, additionally
create `videos/_queues/<batch-id>/queue.json` and `SUMMARY.md` according to
`references/batch-queue.md`.

When the user asks to save or approve a reusable template from a completed
video, enter template-library maintenance directly: read
`references/template-library.md`, run its save/approval workflow, and do not
interpret approval as an npm publication or runtime-install request.

When the user asks to create, design, import, QA or approve a reusable template
set, use the dedicated template workflow: read
`references/template-creation.md` and do not run the normal video intake gate
unless a public video output is also requested.

## Mandatory Intake Gate

Do not research, script, generate voice, select visual assets, compose or
render until all required answers below are resolved.

Ask these questions in order and preserve the existing choices:

1. **Kênh / profile nào?**
   - `thanh-xuan-com-ao`
   - `ai-news-247`
   - Another explicit profile supplied by the user
2. **Ngôn ngữ đầu ra nào?**
   - `Tiếng Việt`
   - `English`
   - Another explicit language supplied by the user
3. **Chiến lược template nào?**
   - `Tạo mới`
   - `Dùng template có sẵn`
   - `Tự chọn phương án phù hợp`
4. **Template set nào?** Ask only when the selected strategy requires an
   existing set, or when more than one suitable existing set is available.

When the prompt already supplies an answer, record it and ask only the missing
items. If an interactive question tool is unavailable, show numbered choices
in chat and wait for the user's response.

Once intake is resolved, initialize or read `videos/<project-name>/run-state.json`
using `scripts/run_state.py`. Persist the intake and mode before production so
resume does not repeat completed questions.

## Run Modes

Parse these optional words from the user's prompt without adding routine intake:

| Word | Behavior |
| --- | --- |
| `review-first` | Pause for review at consequential content/evidence choices before building the draft. |
| `quiet` | Report milestones only. |
| `verbose` | Report detailed decisions and diagnostics. |

Default behavior after intake is `auto-run`: progress to a near-final draft
using preferred voice, actual narration timing and baseline QA. Proactively
recommend `review-first` for remakes/reference videos and security, legal or
sensitive claims.

## Required Routing

After intake, resolve every path below from `NAVID_SKILL_ROOT`:

1. Read `NAVID_SKILL_ROOT/references/execution-policy.md` for universal production behavior.
2. Read `NAVID_SKILL_ROOT/references/run-state.md` when starting, resuming or changing a run.
3. Read `NAVID_SKILL_ROOT/references/quality-gates.md` before any publishable output or render.
4. Use `NAVID_SKILL_ROOT/references/routing-matrix.md` to load only the applicable branch files.
5. Read `NAVID_SKILL_ROOT/references/channel-profiles.md` for the selected channel override.
6. Read `NAVID_SKILL_ROOT/references/presets.md` only for the selected content format.
7. Read `NAVID_SKILL_ROOT/references/template-library.md` only when selecting, recommending,
   validating or promoting a reusable template set.
8. Read `NAVID_SKILL_ROOT/references/template-creation.md` for `navid template create`,
   `/navid-template`, template authoring, template QA or template approval intent.
9. Read `NAVID_SKILL_ROOT/references/editorial-media.md` for AI News, technology, source-backed
   or reference-video work that selects evidence or public visual media.
10. Read `NAVID_SKILL_ROOT/references/batch-queue.md` only for batch intent, after shared intake
   is resolved and before dispatching the first ordered item.
11. Use `NAVID_SKILL_ROOT/references/quick-video-workflow.md` only as a compatibility adapter
    when an older invocation or manual entry path needs mapping.

Never load `NAVID_SKILL_ROOT/references/legacy/` in production. It is audit evidence only.

## Single-Video Skeleton

1. Resolve intake and mode flags, then persist or inspect run state.
2. When using an existing template, recommend/select an approved set and
   persist its rationale before composition.
3. Determine content type, source needs and a public target duration within
   `55-180` seconds unless an explicit exception has been approved.
4. Crawl every user-supplied URL with Crawl4AI first, including social/share links, and record Markdown or the fallback result before extracting hooks, claims or official sources.
5. For GitHub/repository inputs, create a repo evidence digest first using
   repository metadata, README signals, selected images and Crawl4AI digests
   for non-GitHub web links; use that compact digest for scripting to reduce
   token-heavy README/screenshots without making related links the subject.
6. Choose the channel override and format preset.
7. Draft publish title, post caption, exactly 5 hashtags, hook, narration, target audience/use-case beat and CTA/outro treatment. For a repo/tool/product, explicitly explain who should use it, why they need it and one concrete workflow example.
8. Plan scenes and visual roles: proof, explanation or illustration.
9. Generate narration using the selected profile, then measure actual duration.
10. Build deterministic HyperFrames composition and localize assets. Run `npx hyperframes preview videos/<project-name>` to review/tweak.
11. Run required QA, render MP4 using `npx hyperframes render videos/<project-name> -o videos/<project-name>/renders/<project-name>.mp4`, and report the evidence checked.
12. When a render is complete, send the user its render path, publish title
    and exactly 5 hashtags from `PUBLISH.md`; do not leave publishing metadata
    implicit.

The skeleton is not permission to bypass an unresolved intake question or a
quality/risk stop.

## Stop And Fallback Boundary

- Automatically retry safe technical failures that do not alter output meaning
  or quality, up to two retries after the first attempt.
- Stop and ask before a fallback that changes voice, evidence, layout quality,
  attribution, factual confidence or publishability.
- Stop on risky or unverifiable claims rather than presenting them as fact.
- Creative choices inside the selected profile/preset and approved constraints
  may proceed automatically in `auto-run`, then be reported.

## Compatibility And Phase Boundaries

- Preserve existing input styles: topic, URL, GitHub repo, article-to-video,
  remake/reference request and batch intent.
- A batch request uses `references/batch-queue.md`: resolve shared intake once,
  process linked single-video states sequentially and report queue outcomes.
- Template candidate/approval rules and multi-screen set governance are owned
  by `references/template-library.md`.
- Template approval saves to the internal library; npm publication and runtime
  synchronization are separate operations unless explicitly requested.
- Source-backed editorial proof/media behavior and reference-video non-reuse
  are owned by `references/editorial-media.md`.

## Ownership Map

| Concern | Authority |
| --- | --- |
| Intake, mode flags, routing and non-bypassable stops | This `SKILL.md` |
| Universal production execution | `references/execution-policy.md` |
| Per-project checkpoints, resume and decision state | `references/run-state.md` |
| Universal QA and release readiness | `references/quality-gates.md` |
| Request-to-reference selection | `references/routing-matrix.md` |
| Channel-specific overrides | `references/channel-profiles.md` |
| Format-specific beats and tone | `references/presets.md` |
| Candidate/approved templates and recommendations | `references/template-library.md` |
| Dedicated reusable-template authoring workflow | `references/template-creation.md` |
| Source proof, explainer/illustration roles and public media selection | `references/editorial-media.md` |
| Batch ordering, state links, continuation and summary reporting | `references/batch-queue.md` |
| Old invocation mapping only | `references/quick-video-workflow.md` |