README.md

@@ -7,4 +7,4 @@ Personal agent skills packaged through Nix.
 Some skills adapt workflows or helper scripts from public examples.
 
 - `axi-review` is based on the [AXI principles](https://axi.md/).
-- `youtube-transcript` is based on [`amosblomqvist/pi-config/skills/youtube-transcript`](https://github.com/amosblomqvist/pi-config/tree/main/skills/youtube-transcript).
+- `ingest-youtube-transcript` is based on [`amosblomqvist/pi-config/skills/youtube-transcript`](https://github.com/amosblomqvist/pi-config/tree/main/skills/youtube-transcript).

flake.nix

@@ -37,7 +37,7 @@
                 inherit pkgs;
                 inherit (skill) name src;
               }
-              // nixpkgs.lib.optionalAttrs (skill.name == "youtube-transcript") {
+              // nixpkgs.lib.optionalAttrs (skill.name == "ingest-youtube-transcript") {
                 commands = [
                   {
                     path = "fetch_transcript";

skills/ingest-youtube-transcript/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: ingest-youtube-transcript
+description: Use for YouTube URLs that need transcript analysis, summarization, quoting, search, or durable output.
+---
+
+# Ingest YouTube Transcript
+
+Ingest a YouTube video's title and transcript.
+Use the transcript to understand the source and answer the user's request.
+Create durable output when the user requests it or active project conventions require it.
+
+## Helper command
+
+Run from this skill directory:
+
+```bash
+./fetch_transcript "<youtube_url>"
+```
+
+The command prints JSON to stdout:
+
+```json
+{
+  "title": "Video title",
+  "transcript": "full transcript text as a single string"
+}
+```
+
+The command writes progress logs to stderr.
+The command exits non-zero on failure and writes the error to stderr.
+
+## Ingest workflow
+
+1. Run `./fetch_transcript` for the YouTube URL.
+2. Read the returned `title` and `transcript`.
+3. Build source understanding from the transcript.
+4. Respond to the user's request in chat by default.
+5. Create durable output when requested or when active project conventions require it.
+6. State the output path when you create durable output.
+7. State the scratch location when you create temporary scratch files.
+
+## Durable output
+
+Follow active project conventions for durable output.
+Answer in chat when no durable output convention exists.
+The user can request durable output afterward.
+
+## Transcript behavior
+
+The helper prefers manual English subtitles.
+The helper falls back to automatic English subtitles.
+The helper attempts only English captions.
+The language order is `en`, `en-US`, `en-GB`, then any `en*` caption.
+The transcript is plain text with timing and formatting removed.
+Videos without English captions fail.

skills/youtube-transcript/SKILL.md

@@ -1,45 +0,0 @@
----
-name: youtube-transcript
-description: Fetch the transcript and title of a YouTube video as JSON. Use when the user provides a YouTube URL and needs spoken captions for analysis, summarization, quoting, or search.
----
-
-# YouTube Transcript
-
-Fetch a YouTube video's title and full transcript with `yt-dlp` captions.
-Prefer manual English subtitles.
-Fall back to automatic English subtitles.
-
-## Requirements
-
-The Nix-packaged skill provides Python 3 and `yt-dlp`.
-A source checkout requires Python 3 and `yt-dlp` on `PATH`.
-
-## Usage
-
-Run from this skill directory:
-
-```bash
-./fetch_transcript "<youtube_url>"
-```
-
-## Output
-
-Prints a JSON object to stdout:
-
-```json
-{
-  "title": "Video title",
-  "transcript": "full transcript text as a single string"
-}
-```
-
-Progress logs go to stderr.
-On failure, the script exits non-zero and writes the error to stderr.
-
-## Notes
-
-- Only English captions are attempted.
-- The language order is `en`, `en-US`, `en-GB`, then any `en*` caption.
-- Manual captions are preferred over automatic captions.
-- The transcript is plain text with timing and formatting removed.
-- Videos without English captions fail.