Content
82%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A lean, highly actionable CLI skill document: real commands with defaults, a complete options and error reference, and a well-sequenced workflow with fallback handling. Its one real defect is that the default --speakers path depends on prompts/speaker-transcript.md, which is absent from the bundle, leaving both that workflow step and one reference dangling; a minor batch-verification gap keeps workflow clarity just below the top anchor.
Suggestions
Add the missing prompts/speaker-transcript.md to the bundle (or inline its essential instructions in SKILL.md) — it is referenced by both the Workflow and Speaker Identification sections, so the recommended default run (--chapters --speakers) cannot be completed as written.
Add an explicit verification step for multi-URL runs: after the script finishes, confirm each requested video produced an output file and report any that hit Error Cases entries (e.g., 'Video unavailable') so batch failures aren't silently dropped.
Note in the Script Directory section that the other scripts/ files (shared.ts, transcript.ts, youtube.ts, etc.) are internal modules of main.ts, so a reader scanning the bundle isn't left wondering whether they are separate entry points.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Every section carries script-specific knowledge Claude cannot infer: the options table with defaults, the output-directory tree ("transcript-raw.json # raw API snippets { text, start, duration }[]"), the zsh quoting gotcha ("Always single-quote the URL (zsh globs ? ...)"), and the error table. No background concepts are explained; matches "Lean and efficient; assumes Claude's competence; every token earns its place". Not score 4: there is no over-explanation to trim — even the sentence-splitting detail describes non-obvious output semantics. | 5 / 5 |
Actionability | Concrete, near copy-paste commands ("${BUN_X} {baseDir}/scripts/main.ts <url> --languages zh,en,ja") with the placeholder substitution rule stated up front, plus enumerated input URL forms, env var, and error remedies. Not score 5: the Speaker Identification workflow (which the default "--chapters --speakers for the richest output" routes through) instructs a sub-agent to "Read the saved .md and {baseDir}/prompts/speaker-transcript.md", but that file does not exist in the bundle, so a documented step cannot be executed as written — a concrete "minor gap" per the anchor-4 wording. | 4 / 5 |
Workflow Clarity | The 5-step Workflow is clearly sequenced with a pre-flight checkpoint ("No language specified → run --list first") and an error-recovery chain ("retries alternate client identities, then yt-dlp" → "try YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER=safari"), and Error Cases maps failures to remedies. Not score 5: inputs allow "multiple" URLs (batch) yet there is no explicit verification step that every requested video produced an output before reporting back — a minor validation gap rather than absent validation, so the score-3 cap for batch operations without any validation does not apply. | 4 / 5 |
Progressive Disclosure | Good structure: SKILL.md is an overview of a CLI whose implementation lives in scripts/ (main.ts referenced via a Script Directory table; supporting modules correctly left unreferenced), and the speaker-identification prompt is (rightly) split out to a separate file. Not score 5: that split-out file, "{baseDir}/prompts/speaker-transcript.md", is referenced twice but missing from the bundle (no prompts/ directory exists), so one one-level-deep reference is broken; not score 3 because all other content is appropriately placed and references are clearly signaled. | 4 / 5 |
Total | 17 / 20 Passed |