npm - @maccesar/aiskills - Versions diffs - 1.22.0 → 1.23.0 - Mend

@maccesar/aiskills 1.22.0 → 1.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/README.md CHANGED Viewed

@@ -42,20 +42,20 @@ Installed files:
 ### Which option should I use?
-| | Plugin (Option A) | CLI (Option B) |
-|---|---|---|
-| **Claude Code** | Recommended | Supported |
-| **Gemini CLI** | Not available | Supported |
-| **Codex CLI** | Not available | Supported |
-| **Auto-updates** | Via marketplace | `aiskills update` |
+|                  | Plugin (Option A) | CLI (Option B)    |
+| ---------------- | ----------------- | ----------------- |
+| **Claude Code**  | Recommended       | Supported         |
+| **Gemini CLI**   | Not available     | Supported         |
+| **Codex CLI**    | Not available     | Supported         |
+| **Auto-updates** | Via marketplace   | `aiskills update` |
 ---
 ## Compatible platforms
-| Platform                                                  | Status    | Installation Path   |
-| --------------------------------------------------------- | --------- | ------------------- |
-| [Claude Code](https://claude.ai/claude-code)              | Supported | `~/.claude/skills/` |
+| Platform                                                  | Status    | Installation Path                     |
+| --------------------------------------------------------- | --------- | ------------------------------------- |
+| [Claude Code](https://claude.ai/claude-code)              | Supported | `~/.claude/skills/`                   |
 | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Supported | `~/.agents/skills/` (auto-discovered) |
 | [Codex CLI](https://developers.openai.com/codex/cli/)     | Supported | `~/.agents/skills/` (auto-discovered) |
@@ -65,20 +65,29 @@ All three platforms use the same Agent Skills format: a `SKILL.md` file with YAM
 ## Available skills
-| Skill                | Domain       | Source                               | Reference Files |
-| -------------------- | ------------ | ------------------------------------ | --------------- |
-| refactoring-ui       | Design       | "Refactoring UI" by Wathan & Schoger | 7 files         |
-| humaniza             | Writing (es) | Curated Spanish/es-MX style rules    | 7 files         |
-| audit-codebase       | Auditing     | Evidence-based audit methodology     | 2 files         |
-| vscode-extension-dev | VS Code      | VS Code Extension API docs           | 14 files        |
-| stitch-showcase      | Design Tools | Google Stitch export workflow        | 16 files        |
-| session-log          | Project      | Convention + 3 A/B rounds            | 2 files         |
-| release              | Publishing   | Portable, confirmation-gated workflow | 1 file          |
-| seo-launch           | Web / SEO    | Head tags, share cards, server files | 5 files         |
-| npm-supply-chain     | npm / CI     | npm and GitHub changelogs, 2025–2026 | 5 files         |
+| Skill                 | Domain           | Source                                | Reference Files      |
+| --------------------- | ---------------- | ------------------------------------- | -------------------- |
+| refactoring-ui        | Design           | "Refactoring UI" by Wathan & Schoger  | 7 files              |
+| humaniza              | Writing (es)     | Curated Spanish/es-MX style rules     | 7 files              |
+| audit-codebase        | Auditing         | Evidence-based audit methodology      | 2 files              |
+| vscode-extension-dev  | VS Code          | VS Code Extension API docs            | 14 files             |
+| stitch-showcase       | Design Tools     | Google Stitch export workflow         | 16 files             |
+| session-log           | Project          | Convention + 3 A/B rounds             | 2 files              |
+| technical-demo-videos | Video Production | Reproducible macOS technical demos    | 9 guides + 4 scripts |
+| release               | Publishing       | Portable, confirmation-gated workflow | 1 file               |
+| seo-launch            | Web / SEO        | Head tags, share cards, server files  | 5 files              |
+| npm-supply-chain      | npm / CI         | npm and GitHub changelogs, 2025–2026  | 5 files              |
 Use `aiskills list` to see available skills from the command line. Pull requests are welcome.
+### Technical demo videos
+`technical-demo-videos` turns a conversational tutorial idea and a project path into a reviewable storyboard, a permanent recorder, an event log, narration and caption sources, and a verified delivery master. It loads the appropriate framework or domain skills before writing technical claims, prepares VS Code outside the capture, announces every real recording with a clapperboard, uses a fresh disposable project for each take, and keeps all production sources needed to recreate the result. YouTube upload automation and vertical derivatives remain opt-in.
+Automated YouTube publication requires an explicit channel and playlist choice (including an explicit no-playlist choice), validates both against the authenticated account, and binds execution to a reviewed dry run with a confirmation token.
+The workstation geometry and temporary-copy directory are configuration, not assumptions baked into the skill. A team can calibrate one profile and reuse the same workflow for a CLI, web app, mobile simulator, build process, or another technical tutorial.
 ---
 ## Explicit-only release skill
@@ -87,11 +96,11 @@ End-to-end release janitor that works across project types: npm, Titanium (`tiap
 Unlike the other skills, `release` is never supposed to activate merely because a repository looks ready. Name it explicitly:
-| Platform | Invocation |
-| --- | --- |
-| Claude Code | `/release [patch\|minor\|major]` |
-| Codex CLI | `$release [patch\|minor\|major]` |
-| Gemini CLI | `Use the release skill [with a patch\|minor\|major bump]` |
+| Platform    | Invocation                                                |
+| ----------- | --------------------------------------------------------- |
+| Claude Code | `/release [patch\|minor\|major]`                          |
+| Codex CLI   | `$release [patch\|minor\|major]`                          |
+| Gemini CLI  | `Use the release skill [with a patch\|minor\|major bump]` |
 Codex carries platform-specific metadata that disables implicit invocation. Claude Code has its own equivalent frontmatter field, but adding it to this universal `SKILL.md` makes Codex reject the skill; the common body therefore enforces the boundary for Claude and Gemini: the prompt must name `release` before the workflow may proceed. Gemini still asks for activation consent. Every platform then stops again at the release plan and requires a second explicit confirmation before any mutation.
@@ -182,15 +191,15 @@ Example prompts:
 ```
 Reference files:
-| File                     | Topics                                                                                  |
-| ------------------------ | --------------------------------------------------------------------------------------- |
+| File                     | Topics                                                                                   |
+| ------------------------ | ---------------------------------------------------------------------------------------- |
 | 01-foundations.md        | Project mindset: feature-first work, scope discipline, defining systems, picking a voice |
-| 02-page-mechanics.md     | Visual hierarchy, layout, white space, spacing scales, typography                       |
-| 03-visual-treatment.md   | Color systems (HSL, shades, greys, contrast), depth and shadows, image handling         |
-| 04-polish.md             | Borders, accents, empty states, decorative defaults, sharpening design intuition        |
-| 05-motion.md             | Motion system, hover/press states, loading patterns, `prefers-reduced-motion`           |
-| 06-dark-mode.md          | Dark mode color tokens, text contrast, shadows, images, theme toggle                    |
-| 07-component-patterns.md | Modals (focus, layout), forms (labels, validation), tables (density, alignment)         |
+| 02-page-mechanics.md     | Visual hierarchy, layout, white space, spacing scales, typography                        |
+| 03-visual-treatment.md   | Color systems (HSL, shades, greys, contrast), depth and shadows, image handling          |
+| 04-polish.md             | Borders, accents, empty states, decorative defaults, sharpening design intuition         |
+| 05-motion.md             | Motion system, hover/press states, loading patterns, `prefers-reduced-motion`            |
+| 06-dark-mode.md          | Dark mode color tokens, text contrast, shadows, images, theme toggle                     |
+| 07-component-patterns.md | Modals (focus, layout), forms (labels, validation), tables (density, alignment)          |
 ---
@@ -263,7 +272,7 @@ Example prompts:
 ```
 Reference files:
-| File                   | Topics                                                                     |
+| File                   | Topics                                                                      |
 | ---------------------- | --------------------------------------------------------------------------- |
 | comprehensive-audit.md | Mandatory principles, 24-area technical scope, 5-phase method, severity     |
 | report-format.md       | Executive summary, findings table, decision matrix, correction plan formats |
@@ -302,22 +311,22 @@ Example prompts:
 ```
 Reference files:
-| File                   | Topics                                                                                                     |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
-| api-treeview.md        | TreeDataProvider, TreeView registration                                                                    |
-| api-webview.md         | Webview Panel, CSP/nonce, postMessage, asWebviewUri                                                        |
-| api-quickpick.md       | Simple and async QuickPick with debounced search                                                           |
-| api-statusbar.md       | StatusBarItem, codicons, dynamic updates                                                                   |
-| api-secretstorage.md   | Credential manager pattern, onDidChange                                                                    |
-| api-progress.md        | withProgress (Notification + Window), cancellation tokens                                                  |
+| File                   | Topics                                                                                                      |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------- |
+| api-treeview.md        | TreeDataProvider, TreeView registration                                                                     |
+| api-webview.md         | Webview Panel, CSP/nonce, postMessage, asWebviewUri                                                         |
+| api-quickpick.md       | Simple and async QuickPick with debounced search                                                            |
+| api-statusbar.md       | StatusBarItem, codicons, dynamic updates                                                                    |
+| api-secretstorage.md   | Credential manager pattern, onDidChange                                                                     |
+| api-progress.md        | withProgress (Notification + Window), cancellation tokens                                                   |
 | api-additional.md      | FileSystemWatcher, Disposable cleanup, Diagnostics, OutputChannel, ContextKeys, TextDocumentContentProvider |
-| architecture.md        | Project structure, layered architecture, testing strategy                                                  |
-| package-json-schema.md | contributes, activationEvents, engines, scripts, devDependencies                                           |
-| publishing.md          | vsce, .vscodeignore, CI/CD, Open VSX, versioning                                                           |
-| lsp.md                 | LSP client setup, server lifecycle, capabilities, diagnostics                                              |
-| notebooks.md           | Notebook serializers, controllers, renderers, output mime types                                            |
-| debugger.md            | DAP: descriptor factory, configuration provider, adapter lifecycle                                         |
-| testing.md             | Multi-suite test config, workspace fixtures, mocking `vscode`, CI, coverage                                |
+| architecture.md        | Project structure, layered architecture, testing strategy                                                   |
+| package-json-schema.md | contributes, activationEvents, engines, scripts, devDependencies                                            |
+| publishing.md          | vsce, .vscodeignore, CI/CD, Open VSX, versioning                                                            |
+| lsp.md                 | LSP client setup, server lifecycle, capabilities, diagnostics                                               |
+| notebooks.md           | Notebook serializers, controllers, renderers, output mime types                                             |
+| debugger.md            | DAP: descriptor factory, configuration provider, adapter lifecycle                                          |
+| testing.md             | Multi-suite test config, workspace fixtures, mocking `vscode`, CI, coverage                                 |
 ---
@@ -327,12 +336,12 @@ Gives a project one predictable place for its working state, so both you and any
 The convention:
-| File | Holds | Loaded at startup |
-| --- | --- | --- |
-| `status.md` | Where the work stands: half-done things, next step, what's blocked, deployment state, which assistant wrote the note | **No** |
-| `requirements.md` | What the system must do, and the acceptance criterion for each item | Yes |
-| `decisions.md` | What was chosen and why. Append-only, dated | Yes |
-| `context.md` | Documentation map, architecture, conventions, traps, provenance | Yes |
+| File              | Holds                                                                                                                | Loaded at startup |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `status.md`       | Where the work stands: half-done things, next step, what's blocked, deployment state, which assistant wrote the note | **No**            |
+| `requirements.md` | What the system must do, and the acceptance criterion for each item                                                  | Yes               |
+| `decisions.md`    | What was chosen and why. Append-only, dated                                                                          | Yes               |
+| `context.md`      | Documentation map, architecture, conventions, traps, provenance                                                      | Yes               |
 **Why `status.md` is excluded from startup.** Cached context is matched as a prefix — the first byte that differs invalidates everything after it. Status written inside a startup-loaded file means every update throws away the cache for all the stable content behind it. The file you edit most often is the one that must not load at startup.
@@ -362,10 +371,10 @@ What it will not do:
 Measured behaviour, across three A/B rounds against a no-skill baseline (18 runs, adversarially graded):
-| | With skill | Without |
-| --- | --- | --- |
-| Kept volatile status out of the startup chain | 9 / 9 | 0 / 9 |
-| Left the user's broken uncommitted code untouched | yes | no — fixed it unasked |
+|                                                   | With skill | Without               |
+| ------------------------------------------------- | ---------- | --------------------- |
+| Kept volatile status out of the startup chain     | 9 / 9      | 0 / 9                 |
+| Left the user's broken uncommitted code untouched | yes        | no — fixed it unasked |
 Token cost is 3–13% higher per run. **Those rounds graded an earlier layout** — a single status file versus an imported memory index — so what they establish is the split itself, not the four filenames. The paths added since (resuming against a stale file, upgrading an earlier install, monorepos, a gitignored `docs/`) have prompts written for them and have not been run. The grading notes, and an explicit account of what is and isn't measured, are in `skills/session-log/evals/`.
@@ -480,13 +489,13 @@ Certificate verification is on by default; `--local` is the explicit opt-out for
 **Stage 2**, once you approve, installs the tags from a parameterized template, generates the images with ImageMagick, writes `robots.txt` / `sitemap.xml` / `.htaccess`, and re-runs the audit against the live site to verify.
-| Reference file | Covers |
-| --- | --- |
-| `head-tags.md` | title, description, canonical, robots, the Open Graph block, Twitter card, and why the URLs must be absolute |
-| `images.md` | og:image 1200×630, SVG favicon, apple-touch-icon, and the ImageMagick commands with the decision behind each flag |
-| `server-files.md` | robots.txt, sitemap.xml, .htaccess: canonical domain, compression, split caching, security headers |
-| `structured-data.md` | JSON-LD for LocalBusiness, Organization, Article and BreadcrumbList |
-| `search-engines.md` | Search Console (Domain vs URL prefix), Bing, submitting the sitemap, validators, busting Facebook's cache |
+| Reference file       | Covers                                                                                                            |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `head-tags.md`       | title, description, canonical, robots, the Open Graph block, Twitter card, and why the URLs must be absolute      |
+| `images.md`          | og:image 1200×630, SVG favicon, apple-touch-icon, and the ImageMagick commands with the decision behind each flag |
+| `server-files.md`    | robots.txt, sitemap.xml, .htaccess: canonical domain, compression, split caching, security headers                |
+| `structured-data.md` | JSON-LD for LocalBusiness, Organization, Article and BreadcrumbList                                               |
+| `search-engines.md`  | Search Console (Domain vs URL prefix), Bing, submitting the sitemap, validators, busting Facebook's cache         |
 Templates in `assets/`: a parameterized `head.php` for static sites, a `social-meta.blade.php` component for Laravel, a commented `.htaccess`, and a `robots.txt`.
@@ -521,13 +530,13 @@ It reports tokens sitting in `~/.npmrc` or the project `.npmrc`, Actions secrets
 The badge check earns its place from this repo's own history: three badges asked for `aiskills` while the package publishes as `@maccesar/aiskills`, so shields.io rendered "package not found" instead of an error and the downloads badge hid a real 568/month for months.
-| Reference file | Covers |
-| --- | --- |
-| `authentication.md` | the timeline, session-based login, the three token types, the 2FA-bypass phases with dates, the npmjs.com banner, and which paths remain |
+| Reference file          | Covers                                                                                                                                                 |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `authentication.md`     | the timeline, session-based login, the three token types, the 2FA-bypass phases with dates, the npmjs.com banner, and which paths remain               |
 | `trusted-publishing.md` | the publisher form field by field, `id-token: write`, the Node/npm minimums, provenance, the version guard, and the mistakes that break a registration |
-| `install-defaults.md` | npm v12 defaults, `npm approve-scripts`, the committed allowlist, which packages break, and the `ignore-scripts` trap |
-| `migration.md` | the once-per-project procedure in order, what only the package owner can do, and the cleanup the old flow leaves behind |
-| `verification.md` | the command behind each claim — including why `npm view` reports a stale version and what npmjs.com shows when OIDC worked |
+| `install-defaults.md`   | npm v12 defaults, `npm approve-scripts`, the committed allowlist, which packages break, and the `ignore-scripts` trap                                  |
+| `migration.md`          | the once-per-project procedure in order, what only the package owner can do, and the cleanup the old flow leaves behind                                |
+| `verification.md`       | the command behind each claim — including why `npm view` reports a stale version and what npmjs.com shows when OIDC worked                             |
 `assets/publish.yml` is the workflow template, commented line by line.
@@ -588,9 +597,9 @@ aiskills auto-update --silent   # No output (for hooks)
 ```
 Options:
-| Option        | Description                          |
-| ------------- | ------------------------------------ |
-| `-s, --silent` | Suppress all output except errors   |
+| Option         | Description                       |
+| -------------- | --------------------------------- |
+| `-s, --silent` | Suppress all output except errors |
 What it does:
 1. Checks a local cache (`~/.aiskills/last-check.json`) — if already checked today, exits immediately

package/lib/config.js CHANGED Viewed

@@ -35,6 +35,7 @@ export const SKILLS = [
   'seo-launch',
   'session-log',
   'stitch-showcase',
+  'technical-demo-videos',
   'vscode-extension-dev',
 ];

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/aiskills",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "AI coding assistant skills for Claude Code, Gemini CLI, and Codex CLI",
   "type": "module",
   "bin": {

package/skills/technical-demo-videos/SKILL.md ADDED Viewed

@@ -0,0 +1,146 @@
+---
+name: technical-demo-videos
+description: Plan and produce reproducible macOS screen-recorded technical demonstrations from a project path and a conversational goal. Use when the user wants a coding, CLI, build, simulator, emulator, or app workflow recorded in VS Code, including reviewable scripts, timed narration, captions, retakes, or final video assembly. Present the recording plan for approval before controlling the UI or starting a capture.
+---
+# Technical Demo Videos
+Turn a natural-language request into a reviewable production plan and, after approval, a reproducible recording package. Treat domain-specific projects such as Titanium, Flutter, native mobile, web, or a CLI as inputs; do not encode one repository, framework, command, or directory layout in this skill.
+Act as the project's technical screenwriter, director, producer, screen operator, voice-script writer, and editor. Translate the user's informal explanation into a concise visual story that is technically accurate, pleasant to watch, and practical to reproduce. These roles are responsibilities, not permission to override the user's creative brief, change the product, publish media, spend money, or begin recording without approval.
+## Required workflow
+Read only the references needed for the current phase, but read each applicable reference before drafting advice or acting:
+| Task | Required reference |
+|---|---|
+| Storyboard, narration intent, or take review | [references/story-direction.md](references/story-direction.md) |
+| Production package or artifact cleanup | [references/package-contract.md](references/package-contract.md) |
+| macOS or VS Code automation | [references/recording-workflow.md](references/recording-workflow.md) and [references/vscode-default-profile.md](references/vscode-default-profile.md) |
+| Audio alignment or final duration | [references/audio-timing.md](references/audio-timing.md) |
+| Upload-ready horizontal master | [references/youtube-master.md](references/youtube-master.md) |
+| Vertical or social derivative | [references/vertical-social-video.md](references/vertical-social-video.md) |
+| Publishing copy and settings | [references/publishing-metadata.md](references/publishing-metadata.md) |
+| Automated YouTube publication | [references/youtube-publishing.md](references/youtube-publishing.md) |
+In proposals, review notes, and handoff documents, cite each concrete production recommendation from this skill as `[source: references/<file>.md]`. Cite technical claims using the applicable domain skill or official primary documentation. If a claim cannot be verified from the inspected project or a consulted source, prefix it with `FROM_MEMORY (unverified):` instead of presenting it as fact.
+## Establish the request
+Resolve these facts from the user's message and the inspected project:
+- source project path;
+- demonstration goal and intended audience;
+- exact command or UI operation;
+- target platform, device, simulator, or emulator;
+- files, terminal output, and runtime result that prove success;
+- spoken language, caption language, and desired voice workflow;
+- artifact destination and naming convention.
+Preserve meaningful series conventions. When a project slug combines an order and the demonstrated command, such as `02-images`, keep that slug across the plan, recorder, recipe, takes, event logs, narration, captions, and final render. Do not invent a marketing title that breaks traceability unless the user requests one.
+Infer safe details from the project and existing conventions. Ask only when a missing choice would materially change the demonstration. Use the applicable domain skill or official documentation to validate commands and expected results. Do not execute the showcased command during planning unless a harmless preflight is necessary and the user authorized implementation rather than review only.
+## Route technical knowledge
+This skill owns production and recording decisions; it is not the technical authority for every stack. Detect the project's languages, framework, build system, requested feature, and teaching angle before drafting the proposal. Assemble the smallest useful panel of installed skills, which may combine:
+- **platform and framework expertise:** mobile and web frameworks, application platforms, databases, build systems, CLIs, or release tooling;
+- **software judgment:** architecture, senior engineering, refactoring, security, performance, testing, maintainability, or framework-specific best practices;
+- **presentation quality:** UI/UX, visual hierarchy, accessibility, responsive design, technical writing, diagrams, or documentation;
+- **deliverable expertise:** voice, captions, image work, presentations, or publishing when the brief actually needs them.
+This routing is a hard gate: do not draft the recording plan, visible sequence, narration intent, recipe, or recorder until every applicable domain skill has been loaded and its required task-specific references have been read. If a requested command, option, API, or behavior belongs to another installed skill, treat that skill and its cited sources as the technical authority. Verify the exact behavior in the inspected project or implementation when the documentation leaves any uncertainty. Never fill a technical gap with a plausible-looking command, option, output path, or product claim.
+Use those skills to establish:
+- the exact valid command and required working directory;
+- prerequisites, configuration, credentials, devices, and expected duration;
+- success and failure signals;
+- files or runtime behavior that prove the claim;
+- framework-specific actions that should or should not appear on screen.
+Apply specialists only when their perspective materially affects this video. A command-only demo may need the framework skill and engineering judgment but no UI redesign. A UI walkthrough may need UI/UX and accessibility guidance in addition to the framework skill. An architecture explanation may need diagrams and software-architecture analysis without changing the application.
+Then apply this skill to turn those verified facts into the visual sequence, narration intent, automation, and edit. If no suitable domain skill is installed, inspect the project and consult official primary documentation when current or uncertain facts matter. Never invent a command or expected result merely to complete a script.
+Reconcile advice in this order: the user's explicit brief and scope, factual platform constraints, observable project behavior, safety and correctness, then stylistic recommendations. Clearly label an optional best practice as a recommendation; do not present it as a prerequisite. Mention the specialist skills used in the written proposal so the user can review the basis of the technical and creative decisions.
+## Phase 1: propose before recording
+Inspect the source project without changing it. Draft a production package and present the plan to the user before any UI automation or screen recording. The proposal must include:
+1. the exact initial frame and preparation that will remain outside the video;
+2. every visible action in order, including commands exactly as typed;
+3. the proof shown after each meaningful action;
+4. estimated visual timing and narration beats;
+5. files that will be generated and files that will remain untouched;
+6. cleanup behavior and any external cost, login, device, or permission dependency.
+Shape the proposal as a short story: establish what exists before the command, show the action without wasted motion, prove the promised result, and finish on the strongest useful frame. Every spoken claim must have matching visual evidence. Remove dead time, redundant file browsing, terminal noise, and actions that do not advance the demonstration. Narration explains meaning while the image supplies evidence; it should not mechanically read filenames already visible.
+Use a beat table with these columns unless the user requests another format: `Beat`, `Estimated time`, `On screen`, `Operator action`, `Narration intent`, and `Proof/exit condition`. Follow it with the proposed exact command text, initial-frame checklist, expected generated artifacts, and open questions or risks.
+Write the draft `recording-plan.md` and recipe/recorder files when the user asked to create the production package, but mark them as draft. Then stop and request review. Approval of the concept is not approval to begin recording.
+Read [references/story-direction.md](references/story-direction.md) when drafting or revising the proposal. Read [references/package-contract.md](references/package-contract.md) when creating the package. Read [references/recording-workflow.md](references/recording-workflow.md) before generating or running macOS/VS Code automation. Also read [references/vscode-default-profile.md](references/vscode-default-profile.md), load an approved workstation profile when one exists, and preserve its calibrated layout across takes. When none exists, calibrate once outside capture and save the resulting values with the production package.
+## Phase 2: generate the reproducible package
+After the plan is approved, generate one permanent recorder and its data under the episode's `production/` subfolder. Build the recorder from reusable primitives in `scripts/recording_runtime.py`, but copy that runtime into the production package so recreation does not depend on this installed skill or its future version. Reserve the episode root for the final upload-ready MP4, external SRT, and one publishing-metadata document.
+The recorder must:
+- accept or derive the source project path without embedding a random temporary path;
+- create a fresh disposable copy for every take unless the workflow genuinely requires the original; select a short, dedicated copies directory from the recipe, `TECHNICAL_DEMO_COPIES_ROOT`, or the runtime default, append a random slug, and keep helpers in a separate system-temp directory so printed absolute paths remain readable;
+- verify preconditions before opening applications;
+- prepare the initial frame before capture begins;
+- identify and assert the exact target window before every UI action block;
+- record real event timestamps from the same clock as capture;
+- refuse to overwrite existing recordings or user-provided audio;
+- let validation-only checks inspect draft, approved, and finalized packages, while allowing a real capture only when the recipe is explicitly approved and its timing is ready;
+- stop capture before closing the project window;
+- close only the window it opened and remove all temporary copies and helpers in `finally` cleanup.
+For VS Code captures, make the accepted workstation-profile preparation part of every generated recorder. Project-specific recipes begin after that common preparation and contain only the actions that tell the episode's story. Store display selection, logical geometry, shortcuts, terminal-divider coordinates, and panel behavior as profile data rather than scattering machine-specific values through the recorder.
+Retakes modify the same permanent recorder or declarative recipe. Names such as `take-02` identify output media, never different throwaway automation scripts.
+## Phase 3: announce and capture
+Immediately before a real capture, send a commentary message beginning with `🎬` that says recording is about to start and asks the user not to move the mouse or keyboard. Allow a short visible lead time before starting. Never begin a capture in the same tool call that first announces it.
+Do all setup outside the recording: open the isolated project window, arrange panels, open the terminal, choose the correct device or simulator state, and remove Welcome or unrelated tabs. Capture only the approved sequence. Do not introduce extra pauses merely to fit provisional narration.
+When a simulator or emulator is needed only for a later proof beat, boot it, wait for readiness, warm the build, and terminate any previously running copy of the demonstrated app without activating the simulator window. Bring that app to the foreground only at the scheduled recorded action. This keeps preparation invisible and avoids leaving an old runtime state on screen.
+After capture, perform only inexpensive structural checks: confirm that capture exited, the video and event log exist, and the disposable copy was removed. Then ask the user how the take looked before extracting frames, building contact sheets, transcribing, or performing detailed visual analysis. The user watched the live sequence and is the primary first reviewer.
+Inspect frames only when the user requests it, reports a specific problem that needs diagnosis, or could not watch the take. Correct confirmed automation defects by editing the same recorder and creating a new take. Do not generate final narration for a rejected take.
+## Phase 4: narration and delivery
+Choose the timing authority explicitly. The default is capture-first: write narration after an accepted visual sequence, derive cue boundaries from its event log, then create narration text, cue JSON, and external SRT. When the user wants an externally generated voice track to determine the video duration, use audio-first instead: approve final narration before capture, preserve ordinary paragraph breaks, measure the returned audio, and only then lock and execute the visual recipe. Keep an audio-first recipe in draft until those measurements exist.
+For voice-generator input, use fluent prose and normal paragraph breaks by default. Do not inject pause-control tags such as `[short pause]`, `[pause]`, `[long pause]`, or SSML `<break>` unless the user explicitly requests provider-specific pause markup. Do not burn subtitles into the image unless explicitly requested.
+If the user generates voice audio in an external service, preserve the original file. Align speech blocks to cues without stretching the voice, and report a paragraph/block mismatch rather than guessing. Creating paid audio or using an external account requires the user's authorization.
+Measure the first and last audible speech in the returned audio instead of relying only on the container duration. Unless the brief specifies otherwise, allow roughly 0.35 seconds before the first spoken word and 1.5 seconds after the last spoken word, with a normal acceptable post-roll range of 1–2 seconds. Count silence already present in the audio toward those margins, avoid doubling it, and never use `-shortest` when it would remove the clean final frame. Read [references/audio-timing.md](references/audio-timing.md) before timing or assembling narration.
+Do not settle for placing the complete narration track under the capture when the spoken paragraphs and visible actions drift apart. After the take is accepted, compare every narration paragraph with its intended event and perform block-level editorial alignment whenever needed: preserve every spoken sample unchanged, trim only surplus silence at known paragraph boundaries, and place each paragraph against the action or proof it explains. Adjust visual holds or cuts when that produces the more natural result; never create one conspicuous pause to absorb a distributed timing mismatch. Record the source and final ranges in the cue sheet or recording plan so the edit is reproducible. If paragraph boundaries cannot be identified confidently, stop and report the mismatch instead of cutting through speech.
+Verify the final video visually and audibly. Review the beginning, every paragraph transition, every command/result beat, and the ending rather than checking duration alone. Keep a clean final frame after the last spoken line. Preserve the complete reproducible package and remove only intermediates identified by the package contract.
+Before naming any render `<slug>-final.mp4`, read [references/youtube-master.md](references/youtube-master.md), verify its time-sensitive defaults against current official YouTube upload guidance, and pass its delivery-master quality gate. A stream-copied mux is a review preview, not a final upload file. Validate resolution, constant frame rate, bitrate, H.264 profile, pixel format, BT.709 metadata, AAC sample rate, and fast-start layout; never infer quality from the `.mp4` extension or 4K dimensions alone.
+Use `scripts/events_to_cues.py` to normalize a completed event log. The generated SRT must reflect final audio alignment rather than estimated plan timings.
+When the user requests a vertical or social-media derivative, read [references/vertical-social-video.md](references/vertical-social-video.md). Keep it opt-in: do not reframe a horizontal master or burn dynamic captions merely because social delivery might be useful later.
+When the user requests titles, descriptions, keywords, hashtags, upload settings, or a complete social publishing handoff, read [references/publishing-metadata.md](references/publishing-metadata.md). Browse current official platform documentation because these recommendations and limits change, then create one clearly grouped metadata document for each episode.
+When the user requests automated YouTube upload, playlist placement, captions, scheduling, or metadata publication, read [references/youtube-publishing.md](references/youtube-publishing.md). Before generating the upload manifest or dry run, present a publishing-target table containing the expected channel ID/name, either an exact playlist ID/name or an explicit `none`, privacy/schedule, captions, and thumbnail. Do not infer “no playlist” from silence. If the user does not know the IDs, request authorization to run `scripts/youtube_publish.py --inspect-account` and present the authenticated channel and available playlists without uploading. Wait for the user to approve these choices.
+Then generate the production manifest and run a dry run with `scripts/youtube_publish.py`. Present its exact target, operations, hashes, and confirmation token. A real API upload is a separate external mutation: wait for explicit authorization that refers to the reviewed dry run, then pass its token through `--confirm-plan`. The script must verify that OAuth exposes `expectedChannelId` before performing `videos.insert`. Default new uploads to private, never invent a playlist ID, and preserve an upload receipt so retries do not create duplicate videos.

package/skills/technical-demo-videos/agents/openai.yaml ADDED Viewed

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Technical Demo Videos"
+  short_description: "Plan and produce reproducible technical screen demos"
+  default_prompt: "Use $technical-demo-videos to create a reviewable recording plan and reproducible production package for this technical demo. Do not record until I approve the plan."

package/skills/technical-demo-videos/evals/evals.json ADDED Viewed

@@ -0,0 +1,62 @@
+{
+  "skill_name": "technical-demo-videos",
+  "note": "Cross-domain planning evals written when a project-specific production workflow was generalized. These prompts are review fixtures, not claims of completed recordings or measured results.",
+  "evals": [
+    {
+      "id": 0,
+      "name": "node-cli-capture-plan",
+      "prompt": "Take /workspace/json-pretty-cli and make a short VS Code video showing npm test, then formatting fixtures/input.json with node bin/pretty.js. Show the output file and give me the recording plan before touching the UI.",
+      "fixture_spec": "A small Node.js CLI repository with package.json, bin/pretty.js, test/pretty.test.js and fixtures/input.json. It has no video conventions or workstation-specific paths.",
+      "expected_output": "Inspects the project and applicable Node documentation, proposes the exact initial frame, command sequence, visible proof, narration beats, disposable-copy location and cleanup, then waits for approval without recording.",
+      "assertions": [
+        "Does not start UI automation or recording before approval",
+        "Uses the exact project path and verified commands instead of framework assumptions",
+        "Shows both test success and the formatted output as separate proof beats",
+        "Keeps workstation geometry and disposable-copy root configurable",
+        "Names the production artifacts and cleanup behavior"
+      ]
+    },
+    {
+      "id": 1,
+      "name": "web-app-runtime-proof",
+      "prompt": "Plan a tutorial from /workspace/inventory-web that starts its dev server, changes the stock filter in VS Code, and proves the result in the browser. I want English narration and selectable captions.",
+      "fixture_spec": "A Vite web application with a documented npm run dev command, a StockFilter component and local fixture data. The browser can be opened without authentication or network access.",
+      "expected_output": "Loads appropriate web/UI expertise, proposes a deterministic server-readiness check and browser proof, keeps setup outside capture, and separates narration source from SRT spelling.",
+      "assertions": [
+        "Routes technical claims through applicable domain skills or primary project documentation",
+        "Waits for observable server readiness instead of a long arbitrary sleep",
+        "Defines the browser state that proves the filter works",
+        "Keeps English voice text and selectable captions as separate artifacts",
+        "Does not publish or create paid voice audio without authorization"
+      ]
+    },
+    {
+      "id": 2,
+      "name": "retake-audio-alignment",
+      "prompt": "The take is good, but paragraph three says the build completed before the terminal reaches Finished. Fix the same recorder, keep my original voice file, and make take 2.",
+      "fixture_spec": "An approved technical-video package with recording plan, permanent recorder, take-01 MOV, event log, paragraph-based narration, original external voice MP3 and cue sheet.",
+      "expected_output": "Edits the permanent recipe rather than creating a throwaway script, preserves the supplied audio, records take 2 after a clapperboard warning, asks for the live review, and performs block-level alignment only after acceptance.",
+      "assertions": [
+        "Modifies the permanent recorder or recipe instead of creating a take-specific automation script",
+        "Never overwrites take 1 or the supplied audio",
+        "Announces the real capture with a clapperboard in a separate update",
+        "Uses actual event timing for the Finished beat",
+        "Keeps a clean post-roll and does not use one unrelated long pause to absorb drift"
+      ]
+    },
+    {
+      "id": 3,
+      "name": "youtube-channel-playlist-targeting",
+      "prompt": "Upload the approved final video to my YouTube tutorials playlist. I have several channels and do not know the channel or playlist IDs yet.",
+      "fixture_spec": "An approved production package with final MP4, SRT, publishing metadata, OAuth client file, and token path. No channel or playlist ID has been selected.",
+      "expected_output": "Requests authorization for read-only account inspection, presents the authenticated channels and playlists, obtains an explicit channel/playlist/privacy/captions/thumbnail decision, runs a dry run, and waits for separate approval before executing with its confirmation token.",
+      "assertions": [
+        "Does not infer a channel or playlist from its visible name",
+        "Does not treat silence as approval to leave the video out of playlists",
+        "Inspects the OAuth account without uploading when IDs are unknown",
+        "Verifies expectedChannelId before videos.insert",
+        "Requires approval of the exact dry-run token before upload"
+      ]
+    }
+  ]
+}

package/skills/technical-demo-videos/references/audio-timing.md ADDED Viewed

@@ -0,0 +1,40 @@
+# Narration entrance, exit, and visual timing
+Read this before aligning returned narration audio or deciding the final video duration.
+## Measure audible speech
+Inspect three different values:
+1. the audio container duration;
+2. the first audible spoken sample;
+3. the last audible spoken sample.
+Use silence detection as a measurement aid, then associate speech blocks with the known narration paragraphs. Do not assume every detected pause is a paragraph boundary; voices may pause naturally around punctuation or spelled product names.
+## Default margins
+- Aim for about `0.35 s` of visual lead-in before the first spoken word. A practical range is `0.25–0.50 s` for a short technical video.
+- Aim for `1.5 s` of clean visual post-roll after the last spoken word. A range of `1–2 s` is normally appropriate.
+- Count existing leading or trailing silence in the returned audio toward those margins. Do not add the same cushion twice.
+- Base the final video duration on the last audible speech plus post-roll, not simply on the audio container duration.
+Distribute additional visual time across the matching narration beats. Do not hide a duration mismatch by adding one unrelated pause before the command or by holding a source preview longer than its spoken explanation.
+Preserve the original narration file. Do not time-stretch it unless the user explicitly requests that treatment. When muxing, do not use `-shortest` if it would cut the final visual margin.
+## Align paragraphs as editable blocks
+Treat the narration paragraphs and their matching event-log beats as the units of the final edit. A single unedited audio track is acceptable only when those blocks already align naturally.
+When they do not:
+1. map each approved paragraph to its audible source range and intended visual event;
+2. preserve the original audio file and every spoken sample;
+3. remove only unnecessary silence between confidently identified paragraph boundaries;
+4. position each speech block so its explanation begins with, or slightly anticipates, the corresponding visible action;
+5. extend or trim neutral visual holds where appropriate, distributing corrections across the relevant beats;
+6. retain natural conversational pauses and the configured lead-in and post-roll;
+7. write the source-audio range, final-video range, and matching visual cue into the cue sheet or recording plan.
+Never cut based only on generic silence detection. Confirm boundaries against the approved paragraph text, and do not split a spoken sentence or word. If the returned voice merges paragraphs or inserts ambiguous pauses, report the mismatch instead of guessing.

package/skills/technical-demo-videos/references/package-contract.md ADDED Viewed

@@ -0,0 +1,33 @@
+# Production package contract
+Prefer an existing project convention. Otherwise propose `demo-videos/<slug>/` beneath the project root, or an external destination when the source repository should remain untouched. Treat the episode root as the upload handoff: it contains only `<slug>-final.mp4`, `<slug>-subtitles-<language>.srt`, `<slug>-publishing-metadata.md`, and the `production/` subfolder.
+## Draft and source files
+- `production/recording-plan.md`: human-readable approved story, initial frame, visible actions, proof, timing intent, narration beats, risks, and cleanup.
+- `production/<slug>-recording.json`: machine-readable values and ordered actions when the recorder is data-driven.
+- `production/record-<slug>.py`: permanent entry point for rehearsals, retakes, and recreation.
+- `production/recording_runtime.py`: copied reusable automation primitives, pinned with the package.
+The recorder and recipe are source artifacts. A take number never appears in their filenames. Choose the next take number after the highest take already present in `production/`; do not reuse gaps left by rejected or archived takes.
+## Capture and delivery files
+- `production/<slug>-take-01.mov`: raw capture; increment for a retake and never overwrite.
+- `production/<slug>-take-01-events.json`: actual monotonic timestamps for the matching capture.
+- `production/<slug>-cues.json`: normalized visual and narration intervals for the accepted take.
+- `production/<slug>-narration-<language>.txt`: text sent to the voice generator.
+- `production/` keeps the original returned audio, with its provider filename preserved when useful.
+- `<slug>-subtitles-<language>.srt`: selectable upload-ready captions in the episode root.
+- `<slug>-final.mp4`: synchronized delivery master that passed the YouTube master quality gate; a stream-copied review preview does not qualify.
+- `<slug>-publishing-metadata.md`: copy-ready YouTube, TikTok and Instagram metadata plus upload settings in the episode root.
+Use names appropriate to the project when it already has a convention. The essential rule is that each media file can be traced to the recorder version, recipe, and event log that produced it.
+## Temporary material
+Disposable project copies, compiled click helpers, diagnostic screenshots, extracted frames, split audio blocks, proxy files, and rejected render intermediates are temporary. Create them in a uniquely named temporary directory and remove that exact directory after verification or failure.
+Remove caches and Finder metadata such as `__pycache__/` and `.DS_Store` from the episode root before handoff. They are neither publication files nor production sources.
+Never delete source projects, accepted takes, user-provided audio, or an existing artifact merely to reuse its filename.