xxjrq/github-project-intro

GitHub Single Repository Video Orchestration

This Skill is the sole orchestration entry point for a single GitHub repository video. Each repository independently owns its facts, plan, script, screen recordings, timeline, audio, cover data, and release package; only public components are reused. Old works and examples can only serve as references, not as facts, schemas, or visual hard standards.

1. Reading Order and Responsibilities

First read the documents specified by the repository's AGENTS.md, then read and execute by stage:

1. work-library-api-registration: Workspace onboarding or task field replication.
2. ~/.codex/skills/selfmedia-github-research/SKILL.md: Official sources and high-risk claims.
3. ~/.codex/skills/douyin-tech-content-planner/SKILL.md: Audience, unique benefit, hook, and evidence order.
4. ~/.codex/skills/record-web-demo/SKILL.md: Evidence list, Action Plan, and real screen recordings.
5. ~/.codex/skills/selfmedia-script-storyboard/SKILL.md: First determine the final voiceover and readable storyboard; do not estimate final audio duration yet.
6. Audio rules from this Skill: Generate audio serially and measure it, obtaining real duration and subtitle timings.
7. ~/.codex/skills/selfmedia-script-storyboard/SKILL.md: Use screen recording action times and measured audio to complete Timeline v1.2.
8. ~/.codex/skills/selfmedia-cover-design/SKILL.md: 3:4 and 4:3 covers.
9. ~/.codex/skills/selfmedia-remotion-render/SKILL.md: Public template rendering.
10. Workflow gates from this Skill: Verify stage order, required artifacts, and workspace status; after passing the five-file machine contract, atomically generate the formal release package.

Content Agents can only modify their own content units. apps/studio/src/root.tsx, public templates, public covers, schemas, Preflight, and release validators can only be modified by the main integration Agent. Multiple Agents must not modify shared files simultaneously.

2. Onboarding and Formal Content Units

1. After the user submits a formal topic, workspace onboarding must be completed first: For new content, call POST /api/production-requests; for existing directories, call POST /api/works followed by POST /api/production-requests/adopt. Both methods must return a valid work_id and production request ID; without these two IDs, no research, screen recording, or rendering is allowed.
2. After successful onboarding, establish or take over the independent content unit in projects/github/videos/<content-id>/ and synchronize projects/index.yaml and projects/task-index.yaml. content.yaml, task.yaml, and 制作单.md must all record the same work_id; the first stage of the workspace workflow interface is fixed as "Workspace Onboarding".
3. The workspace only stores task requirements; when copying a template, clear old repository URL, Stars, version, license, script, timeline, screen recordings, sources, cover data, and release package.
4. renderer.composition_id is fixed to GitHubProjectDemoTemplate. The template ID is returned by the workspace/API; do not hardcode a template ID from a historical work.
5. When the user submits a formal task, the workspace is allowed to execute continuously through the eight stages to release_ready. Only set stopAfterStageId when the user explicitly requests a test and specifies a stop point; planning only produces the production order, render only leaves rendering staging, no formal directory is created. When the workspace executes continuously, reuse the same Codex session, retain stage gates, but do not rebuild context for each stage.
6. Formal content units must exist:
   • project.json
   • content.yaml
   • task.yaml
   • research/facts.json
   • 制作单.md
7. When Pipeline research outputs to a temporary workspace, official sources, currently used dynamic fields, and high-risk claim conclusions must be written back to the formal content unit; do not substitute a temporary directory for the formal project.

GitHub single project videos maintain a single human-authored master document 制作单.md, using five fixed marker sections: decision, voiceover, storyboard, assets, release. New tasks do not create research/decision.md, research/content-plan.md, script/voiceover.md, script/script.json, 创作提示词.md, or qa/; facts, timeline, Action Plan, screen recording list, audio, SRT, and rendering Props continue to use separate machine files.

3. Source, Risk, and Planning Gates

1. Use the GitHub repository page to confirm the project identity and save the official URL. Only access README, official documentation, or release pages for high-risk claims that actually appear in this video; do not perform full-function encyclopedia-style verification.
2. High-risk claims include: dynamic numbers and rankings; prices, costs, savings ratios, and performance comparisons; security, privacy, and legal conclusions; licenses, versions, maintenance status, and official identity; absolute promises; and specific results without supporting real footage or official sources.
3. Fields like Stars, version, and license are only verified when used in visuals or copy; when used, refresh before the formal render. facts.json saves the precise value, source, and risk conclusion; if there are no additional high-risk claims, record an empty list.
4. Common pain points, rhetorical questions, emotions, analogies, mild humor, and colloquial summaries of real demos do not require sentence-by-sentence verification. Hooks provided or approved by the user are locked by default; only veto when there is a clear factual error, legal compliance risk, or serious misleading content; for other risks, make only minimal word-level modifications.
5. A video promises only one core benefit. First determine the audience, human-language hook, payoff within the first 12 seconds, and a unique CTA, then write the script. The facts file must not inject README technical jargon into the voiceover; only hard barriers that truly affect usability are explained naturally with the corresponding function; prohibit creating separate risk prompt pages, pending verification pages, disclaimer walls, or scope boundary pages.
6. The public release must not display complete URLs, QR codes, download buttons, off-platform action instructions, or specific monetary amounts for ordinary tools.
7. Stop when the project identity cannot be confirmed, or if the public copy still contains unresolved high-risk claims; if there are no high-risk claims, do not block screen recording and rendering.

4. Real Evidence and Asset Timing

record-web-demo must be executed first:

1. Use an 800×600 logical viewport to capture README, images/GIFs, candidate screenshots, and selectors.
2. First, establish the GitHub repository identity shot: The real repository name uses a thin rounded rectangle, Stars or version use a thin ellipse; this shot must be placed before any README or external demo.
3. Then select 1–3 pieces of evidence from README or official demos that can prove the core benefit; file lists, installation logs, logos, and licenses cannot serve as default outcome evidence.
4. GitHub identity and external demos use separate Action Plans and screen recording files; each must be verified before recording. When a 1600×1200 encoded source is needed, use --pixel-scale 2 for post-processing, do not expand the webpage layout.
5. The screen recording list must record startMs, endMs, page, action, evidence object, and execution result for each actual action.
6. The screen recording script must complete successfully; actions in the list must have actual startMs, endMs, and completion status; failed actions must not enter the Timeline.
7. The Timeline's trimStartMs and trimEndMs can only come from the screen recording list; it is forbidden to treat finished scene timings as asset in-points.

5. Script and Timeline

Duration is determined by information, measured voiceover delivery, and visual reading time; it is not fixed at 25 seconds. Default narrative reference:

0～3 seconds    GitHub repository page, project name, Stars, and core value
3～6 seconds    First real evidence from README results or official demo
First 12 seconds    Strongest real evidence appears
Middle section    Continue demonstrating 1–2 pieces of evidence
Later section    Applicable scenarios, limitations, or constraints
End    One sentence summary and one natural CTA

First, write the final voiceover and readable storyboard into the voiceover and storyboard sections of 制作单.md. After the audio stage is complete, use the measured audio duration, subtitle timings, and screen recording list to generate the single machine director file timeline.json. Timeline:

• Use packages/timeline-schema/timeline.schema.json, version 1.2;
• Scene role only allows hook, proof, process, result, identity, cta;
• direction.proofByMs <= 12000;
• direction.demoLayoutPreset is fixed to fixed-demo-v1; demo outer border fixed at x=86, y=420, width=908, height=681;
• At most one visualPeak: true;
• focus uses normalized coordinates derived from verified source frames;
• Demo scenes must not set identityTop, evidenceTop, captionTop; emphasis can only occur inside the demo frame;
• If screen recordings already have annotations, do not repeat annotations in Remotion;
• Scenes, subtitles, and audio cover the full time without overlap, out-of-bounds, or invalid gaps.

Titles, covers, first frames, voiceovers, subtitles, and release copy must include GitHub and the project name, and maintain consistency of project identity, numbers, and other high-risk facts. Titles for the three platforms must not exceed 30 Unicode characters each. The topic/tag lines for the three platforms must each contain #github优质项目 #github开源, totaling 5–7 non-repeating tags, supplemented by the project tag and at least two value/scenario tags matching this content; at most 2 real-time trending tags can be added, and only when there is supporting evidence for that platform.

6. Public Remotion Architecture

New repositories only use public Compositions:

• GitHubProjectDemoTemplate
• GitHubProjectCoverPortrait
• GitHubProjectCoverLandscape

GitHubProjectCoverFeed is only for historical compatibility; it is not included in the new project's Composition list, rendering tasks, or release package.

The project passes Timeline, project name, Stars, hook, result, preset, and assets via structured input. Prohibited:

• Creating a repository-specific TSX visual system;
• Registering repository-specific video or cover Compositions in Root;
• Hardcoding OpenMontage or any historical project as public template default facts;
• Changing facts, guessing asset timings, or reordering scenes during the rendering stage.

GitHubProjectDemoTemplate is the template ID, not the project ID. The Studio is fixed to use http://localhost:3000/, selecting project data via input props. Normal TSX, CSS, JSON, and asset changes rely on hot reloading; only dependency, configuration, entry point changes, service unresponsiveness, or unrecoverable compilation errors allow a restart, with the reason recorded. CLI formal rendering does not depend on the Studio port.

Before formal rendering, execute a unified Preflight: check that formal files are complete, dynamic fields and high-risk claims used in public content are valid, Action Plan and screen recordings pass, asset timings are legal, Timeline Schema passes, title lengths pass, audio mode is consistent, and cover data is complete. Stop immediately if any check fails.

7. Audio Mode

Obey only the voice.mode consistent across the workspace, content.yaml, and task.yaml:

• generate-and-mix: Generate Edge-TTS serially and mix it into the release video; final output must be AAC 48kHz stereo, average volume approximately -20 to -28dB.
• generate-reference: Generate reference audio but do not mix; the release video must truly have no audio track.
• self-recorded: Do not generate TTS; the release video must truly have no audio track; SRT is kept for the user to fine-tune after dubbing.

Preflight fails if the mode is missing or inconsistent across the three locations. The audio stage must precede the Timeline stage; after script changes, regenerate and measure the audio; do not reuse old durations. Timeline and SRT must use the current measured duration; if audio or SRT exceeds the Timeline duration, do not proceed to rendering.

8. Covers and Formal Rendering

Covers must use selfmedia-cover-design; do not temporarily assemble one after the video is complete. The video is fixed to generate two independently laid out covers: 3:4, 4:3; do not hard-crop video frames, do not generate 9:16 video stream covers.

GitHub series fixed information order: GitHub column identity, project name, golden Star below the project name, one specific result of 6–12 characters. Cover data must come from this project, and generate 3:4 and 4:3 files separately.

After all projects pass Preflight, bundle only once, then batch render videos and covers according to the approved plan. Do not repeatedly preview, extract frames per scene, and re-render for the same version; do not create QA image directories.

9. Media Assets, Covers, and Multi-Platform Release

9.1 First Distinguish Four Types of Image Outputs

A project cannot register only one "image" field. They must be managed separately:

Output	Purpose	Preferred Generation Method	Use AI Image Generation?
In-article images	Explain architecture, workflow, installation steps, real features	Official screenshots, screen recording frames, Remotion stills, or SVG; use AI only for fact-free backgrounds when necessary	Default no; factual scenes cannot be fabricated with AI
Article cover	Thumbnail for article lists on CSDN, Zhihu, WeChat Official Accounts, etc.	Remotion/HTML/CSS compositing and layout	AI can be used to generate text-free backgrounds, but title, project name, Stars, and numbers must be overlaid afterwards
Video cover	Thumbnail for Douyin/Bilibili video or graphic content	selfmedia-cover-design + public Remotion Composition, independently generate 3:4 and 4:3	AI can generate the visual subject, but cannot crop a video frame to replace the cover
Skill icon	SkillHub discovery page, skill package metadata	Reuse the project icon or generate a text-free icon with selfmedia-imagegen, then crop/export 512px	Yes; do not place tiny text or unreadable English inside the icon

Conclusion: Article covers and video covers are not cropped from the first video frame; in-article images do not require calling image generation for each one. Real screenshots handle evidence, Remotion handles stable layouts, and AI image generation only handles vision backgrounds or icons with no factual risk.

9.2 Generation Order for Image Assets

Each project prepares assets in the following order; it is forbidden to create covers first and then supplement facts:

Official sources and fact verification
  → Real screenshots/screen recordings/README evidence
  → Article structure and video storyboard
  → Determine which supporting images are needed
  → Generate or organize image assets
  → Remotion unifier overlays project name, title, numbers, and brand layout
  → Generate article cover, 3:4 video cover, 4:3 video cover
  → Size/safe area/fact consistency check

Image source selection:

1. Real product visuals: GitHub, official Demo, official documentation, actual runtime pages; directly screenshot or extract frames from screen recordings.
2. Explanatory diagrams: Prefer using Remotion, SVG, HTML/CSS; suitable for architecture diagrams, flowcharts, comparison tables, and installation steps.
3. Atmosphere backgrounds: Use selfmedia-imagegen; do not place unverified Logos, Stars, version numbers, prices, or feature promises.
4. Article cover titles: Must be overlaid in Remotion/HTML/CSS; do not rely on AI to generate Chinese text within pixels.

9.3 Cover Fields and Layout Rules

Cover data for each project must be saved separately, including at least:

cover:
  eyebrow: "GitHub Open Source Project"
  project_name: "<Project Name>"
  hook: "<6–12 character specific result>"
  star_text: "<Real Stars, with verification date>"
  focal_asset: "<Path to real screenshot or fact-risk-free background image>"
  palette: "<This project's selected color palette>"
  source_checked_at: "<YYYY-MM-DD>"
  outputs:
    portrait: "02-Portrait-Cover-3by4.png"
    landscape: "03-Landscape-Cover-4by3.png"

GitHub series fixed information order: column identity → project name → golden Star → one specific result. The cover's main title expresses only one benefit; do not cram "100 projects," a complete feature list, or installation commands into the cover.

• 3:4: 1080×1440, top boundary approximately 115px, bottom boundary approximately 216px, left/right each 86px.
• 4:3: Independently re-laid out; do not stretch or hard-crop the 3:4 cover.
• 9:16 video frame: 1080×1920, core content adheres to the project's safe zone: top 170px, bottom 288px, left/right 86px; this is not the video cover size.
• Titles, project names, Stars, versions, and other precise numbers use deterministic layout; do not generate precise text inside AI images.

9.4 Division of Labor Between Article Images and Remotion

Before publishing an article, choose according to the article type:

Article Content	Recommended Assets	Notes
Project introduction	1 project cover + 1 real GitHub screenshot + 1 core capability diagram	Core capability diagram uses SVG/Remotion, do not use AI to fake product screenshots
Installation tutorial	Command screenshots, terminal screenshots, flowcharts	Commands and paths must come from the real project
Architecture breakdown	SVG/Remotion architecture diagram + official README screenshot	Structure visualization, fact sources still point to the official repository
Comparison review	Remotion/HTML table + official links for each project	Only compare verified fields
Pure opinion piece	Cover + a few atmosphere images	Atmosphere images can be AI-generated, but cannot be used to prove product functionality

9.5 Release Platform Tiers

Release is not sending the same original text to all platforms; layer by "code source, skill distribution, article search, video distribution":

Tier	Platform	Main Task	Release Content
Primary code source	GitHub	Authoritative facts, versions, Issues, Stars	Source code, README, CHANGELOG, License, Release
Domestic code mirror	Gitee	Domestic access, mirror entry, backup download	Source code and README synced with GitHub, clearly stating GitHub as the primary source
Skill distribution	SkillHub	Skill search, installation, version management	Valid skill package, manifest, Chinese description, icon, version changelog
Article search	CSDN, Zhihu, Juejin, Toutiao, WeChat Official Accounts	Long-form article search, explanation, and traffic guidance	Platform-adapted articles, covers, real screenshots, official links
Video/graphic distribution	Bilibili, Douyin	Discovery, demonstration, follow, and traffic guidance	Video, column/graphic content, 3:4 or platform-required entrance image
Optional distribution	Shaoshupai, SegmentFault, OSChina, Blog Park	Technical readers and developer communities	Only publish when the content truly fits; do not spam for quantity

Recommended minimum release combination for 100 projects:

GitHub primary source + Gitee mirror
  → Projects with a Skill go to SkillHub
  → CSDN / Zhihu / WeChat Official Accounts: choose the article version suitable for the platform
  → Bilibili / Douyin: publish demo videos or graphic content

Not all GitHub projects can be published on SkillHub. Only projects with a truly executable Skill package structure, SKILL.md/manifest.yaml, trigger words, and self-test instructions are listed; ordinary tool repositories only release on GitHub, Gitee, and article/video content.

9.6 Platform Adaptation Before Release

Each platform generates an independent release field; do not copy a single Markdown file verbatim to all platforms:

release:
  github:
    repo_url: ""
    release_url: ""
    status: "pending"
  gitee:
    mirror_url: ""
    sync_checked_at: ""
    status: "pending"
  skillhub:
    skill_slug: ""
    package_path: ""
    icon_path: ""
    status: "not_applicable"
  articles:
    csdn: { title: "", url: "", status: "pending" }
    zhihu: { title: "", url: "", status: "not_applicable" }
    wechat: { title: "", url: "", status: "not_applicable" }
  media:
    bilibili: { url: "", status: "pending" }
    douyin: { url: "", status: "pending" }

After each platform is completed, re-read the title, body/README key sections, project link, images, and public status; the release log records the actual URL, time, version, browser environment, and acceptance conclusion. Publishing, sending, deleting, and overwriting old drafts remain manual confirmation actions.

10. Release Check

After the Agent completes the following machine process gates, write the five files into renders/release-package/. After the workspace validation passes, atomically rename to 发布成品/ and directly enter release_ready:

• The workspace production request is associated with a valid work_id, and the library record directory matches source_dir exactly; otherwise stop, do not enter source and risk verification, screen recording, or rendering stages;
• Pipeline validate --require-assets passes;
• Timeline Schema, asset duration, and first-12-second evidence gate pass;
• Rendering command succeeds, video output is 1080×1920, 30fps, H.264;
• Audio track conforms to voice.mode, TTS and SRT end does not exceed video duration; for generate-and-mix, the final average volume must be between -28 and -20dB;
• Both cover sizes and naming are correct;
• The three platforms each have substantially different titles and descriptions, titles do not exceed 30 Unicode characters, descriptions retain real paragraphs;
• The three platform tags each include #github优质项目 #github开源, each line has 5–7 non-repeating tags, and the project tags and value/scenario tags match the current content;
• projects/index.yaml, projects/task-index.yaml, task.yaml, content.yaml states are consistent.

Do not play incomplete segments, extract frames, check images one by one, perform OCR, create contact sheets or 20:9 stress maps; do not generate QA images or subjective reports. The final visuals are reviewed by the user.

No longer set a rendered → visual_reviewed manual confirmation stage, nor copy duplicate candidate packages. If any machine contract fails, do not create 发布成品/ or report release_ready. The formal release package must and can only contain five files: release copy, video, 3:4 cover, 4:3 cover, SRT. The SRT is fixedly named 04-subtitles.srt; the final visuals are reviewed by the user in the formal directory.

Do not automatically upload, operate platform accounts, or collect post-release data.