docs: add subtitle translator demo and overview

README.md

@@ -1,14 +1,22 @@
 # Agent Skills
 
-A growing collection of reusable Agent Skills for popular SaaS APIs—from image generation and video creation to subtitling, automation, and more.
+A growing collection of reusable Agent Skills for practical SaaS workflows—from image generation and video creation to subtitling and automation.
 
-Each skill is a self-contained directory built around the open [`SKILL.md`](https://agentskills.io/specification) format. Copy or symlink the skill directory you need into an agent-compatible skills location, such as `.agents/skills/` in a repository or `~/.agents/skills/` for personal use.
+Each skill is a self-contained directory built around the open [`SKILL.md`](https://agentskills.io/specification) format. Copy or symlink the directory you need into an agent-compatible skills location, such as `.agents/skills/` in a repository or `~/.agents/skills/` for personal use.
 
-## Skills
+## Featured skill: Video Subtitle Translator
 
-| Skill | Description | Requirements |
+Turn a local audio or video file into polished, timed subtitles—and deliver it as an SRT/VTT/ASS file, a video with permanent subtitles, or a video with a selectable subtitle track.
+
+![Chinese burned-in subtitle preview](skills/video-subtitle-translator/examples/测试视频.中文字幕预览.gif)
+
+The preview above is taken from the included [**测试视频** demo](skills/video-subtitle-translator/examples/测试视频.中文字幕烧录版.mp4): English speech transcribed, translated to Simplified Chinese, and burned into the video.
+
+| Skill | What it does | Requirements |
 | --- | --- | --- |
-| [`video-subtitle-translator`](skills/video-subtitle-translator/) | Transcribe media, translate timed subtitles, prepare readable CJK subtitles, and export hard or soft subtitles. | Node.js 18+, FFmpeg, OO CLI and enabled Fusion ASR/LLM access |
+| [`video-subtitle-translator`](skills/video-subtitle-translator/) | Alibaba Qwen ASR transcription, timed subtitle generation, translation, CJK-aware layout, and hard or soft subtitle export. | Node.js 18+, FFmpeg, OO CLI, Fusion ASR, and OO LLM access |
+
+Read the [video subtitle translator overview and demo](skills/video-subtitle-translator/README.md) for the workflow, formats, languages, and delivery options.
 
 ## Install a skill locally
 
@@ -18,7 +26,7 @@ mkdir -p .agents/skills
 cp -R agent-skills/skills/video-subtitle-translator .agents/skills/
 ```
 
-Restart or reload your agent after installing a skill. See the skill's `SKILL.md` for prerequisites, data handling, workflow details, and output conventions.
+Restart or reload your agent after installing a skill. See the skill's `SKILL.md` for the agent-facing prerequisites, data handling, workflow details, and output conventions.
 
 ## Contributing
 

skills/video-subtitle-translator/README.md

@@ -0,0 +1,64 @@
+# Video Subtitle Translator
+
+**Give any video readable, natural subtitles—then export exactly the format your audience needs.**
+
+`video-subtitle-translator` is an OO-powered Agent Skill for turning local audio and video into timed captions, translated subtitle files, hard-subtitled MP4s, or videos with selectable subtitle tracks. It combines Alibaba Qwen ASR transcription with deterministic subtitle processing, so the output is ready for sharing rather than a loose block of transcript text.
+
+## See the result
+
+![测试视频：英文语音已翻译并烧录为简体中文字幕](examples/测试视频.中文字幕预览.gif)
+
+This preview comes from [**测试视频** — download or play the complete burned-in MP4](examples/测试视频.中文字幕烧录版.mp4). The source is English; the finished video has natural, bottom-centered Simplified Chinese subtitles with a high-contrast outline.
+
+## What it does
+
+### 1. Produce a word-timed transcript with Alibaba Qwen ASR
+
+The skill uploads normalized audio through the OO workflow and submits it to **Alibaba Qwen ASR FileTrans** through the Fusion API. The transcript includes sentence and word timestamps, not just plain text. Those timestamps are what make subtitles accurately follow the speaker.
+
+### 2. Turn the transcript into clean SRT subtitles
+
+Its bundled conversion tool groups timed words into screen-friendly cues. It uses sensible boundaries for pauses, cue duration, character count, and words per cue, then writes portable SRT files (and VTT when requested). The original transcript and word-timed subtitle files are retained for review.
+
+### 3. Translate without losing timing
+
+When a translation is requested, the configured OO LLM translates cue text while preserving every subtitle index and timestamp. Translation checkpoints make longer jobs resumable, and optional glossary, domain, audience, and style settings help keep names and terminology consistent.
+
+### 4. Deliver subtitles your viewers can actually use
+
+- **Burned-in MP4:** permanent subtitles that show everywhere—ideal for social media, mobile playback, and uploads.
+- **Soft-subtitle MKV:** a selectable, editable subtitle track without re-encoding the video.
+- **SRT, VTT, and ASS:** sidecar files for editors, players, and workflows that need a separate subtitle asset.
+- **CJK-aware layout:** Chinese, Japanese, and Korean subtitles are reflowed for readable two-line delivery instead of using English character-count assumptions.
+
+## Languages
+
+Alibaba Qwen ASR supports automatic detection or an explicit source language. The current workflow supports Chinese, Cantonese, English, Japanese, Korean, German, French, Spanish, Portuguese, Italian, Arabic, Russian, Hindi, Indonesian, Thai, Turkish, Vietnamese, and many additional European and Southeast Asian languages. Translation targets are supplied by the configured OO LLM, so the same workflow can deliver subtitles for a multilingual audience.
+
+## Choose the output
+
+| Need | Recommended result |
+| --- | --- |
+| Subtitles must always appear | Burned-in MP4 |
+| Viewers need to toggle subtitles | Soft-subtitle MKV |
+| A video editor or platform needs a subtitle file | SRT or VTT |
+| Matching typography and placement matter | ASS sidecar or styled MKV |
+
+## Install
+
+```bash
+git clone https://github.com/alwaysmavs/agent-skills.git
+mkdir -p .agents/skills
+cp -R agent-skills/skills/video-subtitle-translator .agents/skills/
+```
+
+The implementation guide for agents, including setup, commands, data handling, and recovery steps, is in [SKILL.md](SKILL.md). It requires Node.js 18+, FFmpeg/FFprobe, an authenticated `oo` CLI, Fusion API access, and an OO LLM configuration.
+
+## Included demo
+
+| Asset | Details |
+| --- | --- |
+| [`测试视频.中文字幕烧录版.mp4`](examples/测试视频.中文字幕烧录版.mp4) | Complete 2:46 demo video with Simplified Chinese subtitles permanently burned in; MP4 title metadata: `测试视频`. |
+| [`测试视频.中文字幕预览.gif`](examples/测试视频.中文字幕预览.gif) | Short, autoplaying preview used in this page and the repository home page. |
+
+The demo is included solely to show the generated subtitle result. No raw transcript, API key, uploaded-media URL, or intermediate job data is committed.