DEV Community: douzatan

Cursor Windsurf Mobile Agent Skill: Delegating Android UI Tasks From Your IDE

douzatan — Thu, 15 Oct 2026 01:45:32 +0000

Installing a cursor windsurf mobile agent skill lets your AI code editor delegate live Android UI verification, deep-link testing, and recurring in-app workflows to a cloud or physical Android device without stuffing raw XML view hierarchies into your editor context window. Modern AI IDEs excel at editing TypeScript backends, refactoring Kotlin view models, and running headless browser checks, yet they stall the moment a feature has to be verified inside a real mobile application.

By wiring Airtap into Cursor Agent or Windsurf Cascade through a lightweight skill definition, your IDE coding assistant can dispatch high-level mobile goals to an isolated cloud Android phone or a local test handset running the Autopilot app, then read the structured step log right inside your workspace.

Why Does Your IDE Need a Cursor Windsurf Mobile Agent Skill Instead of Raw ADB Scripts?

Your IDE needs a cursor windsurf mobile agent skill because forcing an editor-based coding model to drive an Android screen through raw shell commands wastes tens of thousands of context tokens per turn and breaks whenever custom UI frameworks omit static resource identifiers. When full-stack or mobile engineers try to connect an AI code editor directly to a local Android emulator, they usually start by telling the agent to run shell commands through the Android Debug Bridge (adb) command guide (verified October 2026) and dump the view hierarchy using the Android UI Automator testing framework (verified October 2026).

In practice, that raw loop creates three immediate bottlenecks inside your editor:

Context Window Exhaustion: A single adb shell uiautomator dump on a modern commercial Android app produces 2,500 to 5,000 lines of deeply nested XML nodes. Feeding that dump into Cursor Composer or Windsurf Cascade on every tap consumes 20,000 to 40,000 tokens, pushing your actual source code out of the active context window.
Custom Canvas and WebView Blindness: Many production mobile screens mix Jetpack Compose, Flutter canvases, React Native bridges, or embedded WebViews that do not expose clean resource-id strings. Coordinate-guessing scripts fail whenever a promotional banner shifts a button down by 80 pixels.
Local Emulator RAM Overhead: Running a full Android Studio AVD alongside Docker containers, a local backend server, and an AI IDE routinely pegs 16 GB to 32 GB of laptop memory and stops working the moment your machine sleeps.

Delegating the mobile UI loop through a dedicated skill separates code intelligence in the IDE from screen perception and actuation on the Android device. Your editor sends a concise task contract, and the mobile runtime handles the Observe -> Interpret -> Decide -> Act cycle on the phone screen.

How Do Raw Local Emulators Compare to Skill-Delegated Android Execution?

Before adding the skill files to your repository, review how local ADB scripting compares against delegating Android tasks through a dedicated mobile agent skill:

Engineering Dimension	Raw Local `adb` + `uiautomator dump`	Local Instrumented Espresso / Maestro	Skill-Delegated Android Runtime (Airtap)
IDE Context Token Cost	Very high (20k to 40k tokens per screen XML dump)	Moderate (requires maintaining separate test selector files)	Low (IDE sends goal + receiver ID, receives concise JSON outcome)
Local Hardware Footprint	Heavy (Android SDK + local emulator consuming 4 to 8 GB RAM)	Heavy (local emulator or paid CI device farm required)	Zero local emulator overhead when targeting a Cloud Android Phone
Dynamic Popups & Custom Views	Brittle (breaks on unexpected permission modals or missing IDs)	Fails unless every popup is explicitly scripted in advance	Handled dynamically by live screen perception on each step
Target Device Options	Local USB-tethered device or local AVD only	Local AVD or CI test runner only	Cloud Android Phone container or physical phone via Autopilot app
2FA, Login & Payment Screens	Requires hardcoded test credentials in plain text	Requires staging auth-bypass flags in app build	Pauses automatically and sends a live `Take Control` link to human

This separation is particularly useful when you are building a backend webhook, deep-link router, or mobile API endpoint in your IDE and want to verify how the real Android app responds without switching windows.

How Do You Install and Configure the Skill in Cursor and Windsurf?

Setting up the integration takes less than five minutes and uses standard workspace configuration files supported by both editors.

Step 1: Install the skill package and Personal Access Token

You can install the skill from the airtap-ai/airtap-skill repository (also listed on ClawHub) using npx skills, or pull the machine-readable specification directly via curl:

# Option A: Install directly for Cursor or Windsurf via npx skills
npx skills add airtap-ai/airtap-skill -a cursor
npx skills add airtap-ai/airtap-skill -a windsurf

# Option B: Fetch the raw skill specification into your workspace skills folder
mkdir -p .agents/skills/airtap
curl -sL https://airtap.ai/skill.md -o .agents/skills/airtap/SKILL.md

Next, open the Airtap web app, navigate to Settings -> Personal Access Token, generate a token, and export it in your shell profile (never commit tokens to Git):

export AIRTAP_PAT="atp_live_your_personal_access_token_here"

With the skill installed, your IDE agent gains six core operations: listing available receivers (devices) or models, creating mobile tasks, monitoring running tasks, sending follow-up input when a task asks a clarifying question, canceling tasks, and updating device location context.

Step 2: Configure project rules for Cursor Agent

As detailed in the Cursor Rules for AI documentation (verified October 2026), Cursor loads modular project instructions from .cursor/rules/. Create .cursor/rules/airtap-mobile.mdc so Cursor Agent knows when and how to invoke the mobile skill instead of running raw adb commands:

# Cursor Rule: .cursor/rules/airtap-mobile.mdc
# Scope: Mobile UI verification, deep-link checks, and Android routine delegation

When a task requires inspecting or interacting with an Android mobile app:
1. Read `.agents/skills/airtap/SKILL.md` before proposing any mobile shell commands.
2. Do NOT run raw `adb shell uiautomator dump` or hardcode X/Y tap coordinates.
3. Verify that `$AIRTAP_PAT` is set in the environment, then list available receivers (Cloud Android Phone or Autopilot physical device).
4. Formulate a concise task contract specifying:
   - Target app name and starting screen or deep link
   - Exact observation or UI verification goal
   - Stop condition (pause and request human Take Control on any login, 2FA, or payment commit screen)
5. Poll the task status until completion and summarize the step-by-step action log in the editor response.

Step 3: Configure workspace rules for Windsurf Cascade

In Windsurf, the agentic Cascade engine reads workspace-level instructions from .windsurfrules, as documented in the Windsurf Cascade workspace documentation (verified October 2026). Add a dedicated mobile delegation block to your repository's .windsurfrules file:

# Windsurf Cascade Rule (.windsurfrules) - Mobile Execution Bridge

## Mobile App Verification & Routine Delegation
- Whenever verifying backend API changes, push notifications, or deep links against an Android app, delegate UI execution via `.agents/skills/airtap/SKILL.md`.
- Prefer the isolated Cloud Android Phone receiver for general regression and staging checks.
- Select the Autopilot physical device receiver when testing SIM-bound, carrier-specific, or local-network hardware apps.
- Never place app passwords, OTP codes, or payment credentials inside prompts or environment files. If a task enters `PAUSED_TAKE_CONTROL`, notify the developer to complete authentication via the live link.

Keeping both .cursor/rules/airtap-mobile.mdc and .windsurfrules committed to version control alongside .agents/skills/airtap/SKILL.md ensures that every engineer on your team gets identical mobile delegation behavior regardless of which AI code editor they prefer. When a pull request modifies an API response schema or an Android navigation graph, either editor can immediately run the same mobile verification contract without per-developer emulator setup.

How Do You Dispatch Live Android Tasks and Handle Interactive Interrupts From the Editor?

Once your workspace rules are in place, you can ask Cursor Agent or Windsurf Cascade to verify mobile flows directly from your coding session. First, decide which receiver fits your task:

Cloud Android Phone: Provisioned in about 60 seconds inside a private, isolated cloud container. You can sign into Google Play to install staging or production apps, view the live screen stream in the web dashboard, and let sessions wipe cleanly on logout.
Physical Android Phone via Autopilot: Install the Autopilot Android app on a spare handset on your desk to let the agent operate apps bound to a physical SIM card, local Wi-Fi IoT devices (such as a Nest thermostat), or device-specific logins.

When you prompt your IDE agent to verify a change (for example, "After deploying the updated promo endpoint, open our Android app on the cloud phone, apply code OCTSAVE20 on the cart screen, and confirm the discount badge renders without submitting payment"), the agent uses the skill workflow to list receivers, create the task, and monitor progress:

{
  "operation": "create_task",
  "receiver_id": "rcv_cloud_android_primary",
  "task_prompt": "Open the staging retail app, add the default test item to cart, enter promo code OCTSAVE20, and read the discount line item. Stop before checkout payment.",
  "stop_on_sensitive_screen": true,
  "location_override": {
    "city": "San Jose, CA",
    "latitude": 37.3382,
    "longitude": -121.8863
  }
}

During execution, the runtime runs its Observe -> Interpret -> Decide -> Act loop on the Android screen and returns structured status updates:

If the task is ambiguous: Suppose the promo code field is hidden behind a collapsed accordion or displays two different tier options. The agent pauses to ask a clarifying question, and your IDE can pass your answer back using the skill's follow-up input call.
If the app prompts for login or 2FA: Passwords are never stored or visible to the agent, and the runtime is cryptographically blocked from reading secure fields. The task pauses and emits a Take Control notification (also accessible via iMessage, SMS, or Telegram) so you can sign in directly on the isolated container screen and resume the run.
If the workflow should run on a recurring schedule: Once an interactive run succeeds, you can save it as a scheduled routine in the visual routine builder so it runs automatically every morning or after every nightly build.

What Best Practices Keep IDE-to-Mobile Delegation Fast and Reliable?

After wiring the skill into your repository, follow these four engineering habits to keep your IDE sessions fast and predictable:

Write Goal-Oriented Task Contracts, Not Pixel Scripts: Tell the mobile agent what state to verify ("Open Orders tab, select the topmost order, and verify the status badge text"), not how many pixels to scroll. The screen-reading loop adapts to layout density and popups automatically.
Set Explicit Stop Boundaries in Every Prompt: Always state where the mobile agent must stop (for example, "Stop on the order review screen; do not tap Place Order"). Keeping irreversible actions behind human confirmation prevents accidental test orders.
Use Location Updates for Geo-Fenced App Flows: If your mobile app renders different pricing, store inventory, or booking slots based on GPS coordinates, use the skill's location update action before creating the verification task.
Promote Proven Checks to Scheduled Routines: Rather than re-running routine mobile smoke checks manually from your editor every morning, convert working tasks into scheduled routines that alert you on Telegram, SMS, or iMessage only when a check fails or a target condition hits.

Airtap is free to start, with a daily soft usage cap that resets at 00:00 UTC, making it easy to test both one-off IDE verifications and scheduled mobile routines without provisioning local emulator farms.

Disclosure: Assisted by AI tooling (#abotwrotethis).

Building a Multi Agent Workflow Telegram to Slack Relay With a Cloud Android Phone

douzatan — Wed, 14 Oct 2026 13:53:14 +0000

Wiring a multi agent workflow telegram to slack pipeline lets an on-call engineer or operations lead send a short command in Telegram, delegate a live mobile app inspection to an isolated cloud Android phone, and publish a structured status card into a team Slack channel. Most tutorials that connect Telegram to Slack stop at a trivial text forwarder: a webhook receives a string in one chat app and reposts the exact same string in another. Real operational workflows are rarely that simple. When a growth, logistics, or marketplace ops team needs to verify regional in-app promo pricing, check live delivery or rideshare wait times, or inspect a smart-facility controller that only ships as an Android or iOS binary, standard HTTP webhook glue hits a brick wall.

To bridge that gap without maintaining brittle reverse-engineered mobile scrapers, you can equip your orchestrator agent with Airtap, which provides a real Android phone inside an isolated cloud container (or connects to a spare physical Android phone via Autopilot) that developer agents can drive through a lightweight skill file. Your ingress bot handles the Telegram command, your orchestrator delegates the screen-level mobile task to the Android runtime, and your egress worker formats the structured output into Slack Block Kit.

This tutorial walks through the four-node relay architecture, webhook deduplication and security headers, delegating mobile UI checks via the skill specification, formatting Slack Block Kit cards, and handling session expiration or human-in-the-loop escalations. API details below are verified against official Telegram Bot API and Slack Developer documentation as of October 2026.

Why a multi agent workflow telegram to slack relay needs a real Android runtime

In a typical operations setup, Telegram serves as the fast, mobile-first command trigger for founders or on-call responders who are away from their desks, while Slack serves as the persistent system of record where the wider engineering or operations team tracks incident timelines and price audits. A multi agent workflow telegram to slack architecture becomes much more useful when the middle of the pipeline can inspect software that has no public web API.

Consider three everyday ops checks that fail inside a standard headless browser worker:

Verifying app-only retail and delivery pricing. Regional delivery apps, pharmacy loyalty wallets, and travel platforms frequently display different prices or promo banners inside their native mobile apps than on their public websites.
Checking live local supply and wait times. Mobility, courier, and booking apps lock real-time ETA maps behind mutual TLS (mTLS) and Google Play Integrity attestation, blocking raw Python requests or headless Chromium scripts.
Inspecting mobile-bound hardware and IoT controls. Many smart thermostats, access locks, and building sensors only expose their status dashboards inside a companion Android app.

Splitting the relay into four single-responsibility nodes keeps your codebase modular:

Node 1 (Telegram Ingress Webhook): Validates the incoming operator command, checks the sender allowlist, deduplicates the update_id, and returns HTTP 200 OK in under 500 milliseconds.
Node 2 (Orchestrator Agent): Parses the user's intent, loads the mobile execution skill, and dispatches a bounded, read-only mobile inspection task with a strict JSON return schema.
Node 3 (Cloud Android Runtime): Opens the genuine Android application inside an isolated container, reads the live screen and accessibility tree, and extracts the requested metrics.
Node 4 (Slack Block Kit Egress): Converts the structured JSON telemetry into an actionable Slack card posted to #ops-mobile-checks.

Step 1: Verify and deduplicate incoming Telegram Bot webhook commands

The biggest operational trap when connecting a chat webhook to a real UI agent is webhook timeout retry storms. Under the official Telegram Bot API setWebhook specification, Telegram expects your HTTPS endpoint to acknowledge incoming Update payloads promptly, and it will re-deliver the same update_id if your server hangs for 45 seconds waiting for an Android app to launch and render.

Always verify the X-Telegram-Bot-Api-Secret-Token header, check update_id against a short-lived cache or Redis set, acknowledge the request immediately, and push the agent job to an asynchronous background worker:

import express from "express";

const seenUpdates = new Set<number>();
const ALLOWED_USER_IDS = new Set([10492819, 29481022]);
const app = express();
app.use(express.json());

app.post("/webhooks/telegram", (req, res) => {
  const secret = req.header("X-Telegram-Bot-Api-Secret-Token");
  if (secret !== process.env.TELEGRAM_WEBHOOK_SECRET) {
    return res.status(401).json({ error: "unauthorized" });
  }

  const update = req.body;
  if (!update?.update_id || seenUpdates.has(update.update_id)) {
    return res.status(200).json({ ok: true, deduped: true });
  }
  seenUpdates.add(update.update_id);

  const msg = update.message;
  if (!msg?.text || !ALLOWED_USER_IDS.has(msg.from?.id)) {
    return res.status(200).json({ ok: true, ignored: true });
  }

  res.status(200).json({ ok: true, queued: true });
  void runMultiAgentRelay(msg.chat.id, msg.from.username, msg.text);
});

By returning 200 OK before calling runMultiAgentRelay, your pipeline guarantees that a 40-second mobile screen check will never trigger three duplicate runs.

Step 2: Equip your orchestrator agent with the cloud Android skill

Instead of writing custom Appium scripts or brittle coordinate macros for every mobile app you want to inspect, your orchestrator agent (such as Claude Code, Codex, OpenClaw, or a custom agent loop) can load Airtap's public skill definition directly.

On your agent runner host, fetch the skill specification so your orchestrator knows how to dispatch tasks to your cloud Android phone (or to a spare physical Android phone connected via Autopilot):

curl -sL https://airtap.ai/skill.md

When the orchestrator delegates a task to the mobile execution layer, instruct it to enforce two rules: keep the operation strictly read-only unless a human explicitly confirms a state change, and return a deterministic JSON object so your downstream Slack formatter never has to regex-parse conversational prose.

Here is an example task prompt template that the orchestrator passes to the mobile worker when an operator sends /check_ride SFO_Terminal_G in Telegram:

{
  "task_type": "mobile_ui_inspection",
  "read_only": true,
  "instruction": "Open Uber and Lyft on the signed-in Android phone. Check live pickup ETAs and standard fares from 500 Howard St, San Francisco to SFO International Terminal G. Do not tap Book or confirm any ride.",
  "response_schema": {
    "status": "OK | NEEDS_TAKE_CONTROL | ERROR",
    "app_checked": "Uber & Lyft",
    "uber_quote": "$42.50 (4 min ETA)",
    "lyft_quote": "$46.10 (6 min ETA)",
    "requires_human_action": false,
    "take_control_reason": null
  }
}

Because the cloud Android phone runs inside its own isolated container with the real apps installed, the agent reads the live screen state naturally without triggering API gateway blocks.

Step 3: Post structured results or escalation alerts to Slack Block Kit

Once the mobile worker returns its structured JSON payload, the final node in your multi agent workflow telegram to slack pipeline formats the result for your team channel. According to the Slack Incoming Webhooks documentation, every webhook POST should include both a top-level text string (used for mobile push notifications and screen readers) and a rich blocks array built with the Slack Block Kit framework.

async function postToSlack(operator: string, command: string, result: any) {
  const statusEmoji = result.status === "OK" ? "🟢" : "🟠";
  const payload = {
    text: `[${result.status}] Mobile check completed for ${command}`,
    blocks: [
      {
        type: "header",
        text: {
          type: "plain_text",
          text: `${statusEmoji} Mobile App Check: ${result.app_checked}`
        }
      },
      {
        type: "section",
        fields: [
          { type: "mrkdwn", text: `*Triggered By:*\n@${operator} (via Telegram)` },
          { type: "mrkdwn", text: `*Status:*\n\`${result.status}\`` },
          { type: "mrkdwn", text: `*Primary Quote:*\n${result.uber_quote || "N/A"}` },
          { type: "mrkdwn", text: `*Secondary Quote:*\n${result.lyft_quote || "N/A"}` }
        ]
      },
      {
        type: "context",
        elements: [
          {
            type: "mrkdwn",
            text: `Command: \`${command}\` · Executed on isolated Android container`
          }
        ]
      }
    ]
  };

  await fetch(process.env.SLACK_WEBHOOK_URL!, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload)
  });
}

When result.status is OK, the team channel gets a clean four-field summary card within seconds of the mobile check finishing.

Handling mobile session expirations, retries, and Take Control handoffs

Real mobile apps occasionally throw curveballs that headless scripts cannot solve on their own: a 30-day login token expires, a two-factor verification prompt appears, or an operator asks the agent to prepare a booking that requires payment confirmation.

Under Airtap's security model, password fields are cryptographically blocked from agent reading, and your credentials are never stored by or visible to the AI. Instead of pasting passwords into Telegram or Slack env vars, your relay should route authentication and payment gates through a Take Control handoff, where the operator taps a link to interact with the cloud phone screen directly, completes sign-in, and lets the agent resume.

Here is how to map each failure mode across your multi agent workflow telegram to slack pipeline:

Failure or Escalation Scenario	What Happens on the Android Runtime	Orchestrator Retry Policy	Slack & Telegram Notification Behavior
Telegram Webhook Timeout (>10s)	Task continues running normally on the Android phone	Deduplicate by `update_id`; do not spawn a second Android task	ACK `200 OK` immediately on ingress before starting the agent loop
App Session Expired / Login Prompt	Agent detects sign-in screen; password fields are blocked from reading	`0` automated retries; pause task and emit `NEEDS_TAKE_CONTROL`	Post orange alert card in Slack and reply in Telegram with Take Control handoff notice
2FA Code or Passkey Challenge	Security prompt blocks navigation to target screen	Pause execution for up to 10 minutes awaiting human input	Notify triggering operator in Telegram to enter the 2FA code directly via Take Control
Checkout / Payment Confirmation Gate	Agent reaches final review screen with price and terms	Never auto-submit payment; hold state for explicit human confirmation	Send quote summary to Slack and Telegram; require operator approval before confirming
Transient App Modal or Promo Popup	Promo banner overlays the main navigation bar	Up to `1` screen-level dismissal retry by the UI agent	Log dismissal in context block; only alert Slack if screen remains blocked after retry

Production checklist before deploying your relay

Before moving your Telegram-to-Android-to-Slack relay from a local test script to an always-on team bot, verify four operational guardrails:

Lock down your Telegram sender allowlist. A Telegram bot username is publicly discoverable. Checking X-Telegram-Bot-Api-Secret-Token only proves the request came from Telegram's servers, not that the sender is on your team. Always filter against an explicit allowlist of numeric Telegram from.id values.
Choose the right Android device target for the job. For 90% of team checks, Airtap's cloud Android phone (which sets up in about 60 seconds inside an isolated per-user container) is the cleanest choice because it supports live screen view in the web dashboard and wipes sessions cleanly on logout. If a task requires an app bound to a local office Wi-Fi network or physical SIM card, connect a spare Android phone via Autopilot (noting that live screen streaming in the web dashboard is currently supported only for the cloud phone).
Keep routine checks read-only by default. Separate inspection commands (like /check_price or /check_eta) from action commands so no automated schedule or fat-fingered chat message can accidentally complete a purchase without a human confirmation step.
Mind your daily usage rhythm. Airtap is free to start, with a daily soft usage cap, making it straightforward to prototype your multi-agent relay and run recurring team checks without provisioning custom emulator clusters.

Codex Mobile App Automation: Delegating Android UI Tasks via Skill Files

douzatan — Wed, 14 Oct 2026 13:52:11 +0000

Setting up codex mobile app automation lets a terminal coding agent hand off mobile-only Android UI tasks, in-app smoke tests, and recurring screen checks to a dedicated cloud or physical phone without maintaining brittle ADB shell scripts. Terminal agents are remarkably fast at refactoring TypeScript, querying Postgres, and calling REST endpoints, yet they hit an immediate wall whenever a workflow requires tapping inside a native Android application that has no public web interface or API.

By connecting a terminal coding agent such as OpenAI's Codex CLI, Claude Code, Cursor, or OpenClaw to Airtap through a single Markdown skill file, your desktop agent can delegate mobile UI execution to a cloud Android phone (or a local test phone running the Autopilot app) and receive structured results back in the terminal.

Why do terminal coding agents hit a wall on mobile apps, and how does codex mobile app automation solve it?

When you run OpenAI Codex CLI or Claude Code (verified October 14, 2026) inside a repository, the agent has full access to your local shell, file tree, and HTTP clients. That works for backend services and web apps that can be driven through Playwright, but three common engineering and operations tasks still live exclusively inside mobile apps:

Mobile-only staging and release verification: Verifying that a freshly built Android APK or deep-link push notification actually renders the right screen state on a real Android device after a backend deploy.
In-app state and pricing checks: Querying mobile apps that enforce certificate pinning, device attestation, or mobile-only member states that return 403 Forbidden to headless web scrapers.
Multi-step operational routines: Automating recurring business chores (checking a mobile merchant dashboard, verifying a booking slot, or confirming an in-app delivery status) where the vendor never shipped a webhook or REST API.

Historically, giving a CLI agent access to an Android screen meant wiring up Android Debug Bridge (adb), dumping XML hierarchies with Android UI Automator, and asking your coding LLM to parse 4,000 lines of nested <node> tags on every turn. That burns context tokens, breaks whenever a Jetpack Compose or Flutter surface omits resource-id attributes, and fails the moment your laptop lid closes.

A codex mobile app automation setup separates the coding and orchestration brain (running in your terminal) from the mobile UI execution runtime (which reads the Android screen, taps, scrolls, and returns the outcome).

How does a declarative skill file compare to raw ADB and UI Automator scripts?

Before wiring up a skill file, it helps to compare what happens when a terminal coding agent drives an Android device directly via adb shell versus delegating the task through a dedicated mobile execution layer:

Dimension	Raw `adb shell input` + XML Dump	Instrumented UI Automator / Espresso	Skill-Delegated Mobile Agent (Airtap)
Setup & Dependencies	Local Android SDK, USB debugging or wireless ADB, custom Python wrapper	Full Gradle test target, matching APK signature, Java/Kotlin selectors	Single skill file (`curl -sL https://airtap.ai/skill.md`)
Token Cost in CLI Agent	Very high (15k to 40k tokens per turn for raw `uiautomator dump` XML)	Low during run, high maintenance when UI selectors change	Low (CLI agent sends goal + constraints, receives concise outcome)
Custom Views / Flutter / WebView	Fails when nodes lack `resource-id` or `content-desc`	Requires custom semantics hooks in source code	Handled by hybrid visual + system UI perception loop
Device Availability	Stops when developer laptop sleeps or USB disconnects	Requires local emulator or paid CI device farm	Runs 24/7 on Cloud Android Phone or local phone with Autopilot
Login / 2FA / Payment Screens	Requires hardcoded test credentials or manual ADB intervention	Fails or requires test-only auth bypass flags	Pauses and sends a `Take Control` link for human completion

Instead of forcing your coding model to act as a low-level screen coordinates calculator, the skill file teaches the CLI agent how to formulate a clear task contract, dispatch it, and wait for the structured result.

How do you wire the Airtap skill file into Codex CLI, Claude Code, or Cursor?

Airtap exposes a machine-readable skill specification at https://airtap.ai/skill.md designed for coding agents including OpenAI Codex, Claude Code, Cursor, Windsurf, and OpenClaw.

Step 1: Fetch and inspect the skill definition

From your project root or agent skills directory, pull the official skill file:

# Download the Airtap mobile execution skill into your agent workspace
mkdir -p .agents/skills/airtap-mobile
curl -sL https://airtap.ai/skill.md -o .agents/skills/airtap-mobile/SKILL.md

If you are using OpenAI Codex CLI or Claude Code, you can also reference the skill directly in your project's AGENTS.md or pass it into the session context so the agent knows when to delegate mobile UI tasks instead of writing local browser scrapers.

Step 2: Choose between a Cloud Android Phone and a local Autopilot device

Depending on what your terminal agent is automating, you can bind the skill to either of two execution targets:

Airtap Cloud Phone (Default): A dedicated, isolated cloud Android instance that stays online 24/7. Ideal for scheduled checks, external app verification, and multi-app workflows that should keep running when your workstation is powered off.
Physical Android Device via Autopilot: Install the Airtap Autopilot app on a spare Android test phone on your desk or local Wi-Fi network. Ideal when testing local LAN builds, hardware-bound authenticators, or smart-home apps tied to your local network.

Step 3: Structure the task handoff from your terminal agent

When your terminal coding agent delegates a task, the prompt payload should specify four fields so the mobile agent never guesses at success criteria:

task_handoff:
  target_app: "Android staging build or target mobile app name"
  initial_state: "Launch app from home screen; verify logged-in workspace"
  goal: "Navigate to Orders -> Filter by Pending -> Extract top 3 order IDs and status badges"
  stop_conditions:
    - "If a login, 2FA, or payment confirmation screen appears, pause and request Take Control"
    - "Return structured JSON with order_id, status, and timestamp"

When invoked from a terminal session (as shown in the public "Using Airtap inside Claude Code" demonstration on airtap.ai/see-it-in-action), the coding agent dispatches the instruction, Airtap's Brain and AutoPilot execute the UI navigation on the Android screen, and the CLI session receives the extracted values back to continue its local code or script execution.

How do you handle authentication, 2FA, and Take Control handoffs in a developer workflow?

One of the worst anti-patterns in DIY mobile automation is storing plaintext passwords, TOTP seeds, or session tokens inside .env files or passing them through LLM context windows.

When you delegate Android UI tasks through Airtap, credential boundaries are enforced at the device container level:

Persistent isolated Android session: Once you sign into an app inside your dedicated cloud Android phone (or on your own physical Android device running Autopilot), the session lives inside Android's native application sandbox rather than inside your terminal agent's prompt history.
Interactive Take Control pause: When the mobile agent encounters a login prompt, a biometric/2FA challenge, a CAPTCHA, or a checkout button, it pauses execution and sends a Take Control link. You tap or type the sensitive input directly on the streamed device screen, and then hand execution back to the agent to finish the routine.
Read-only vs state-changing guardrails: In your skill instructions, explicitly mark whether a delegated task is read-only (inspecting UI state, checking prices, reading a status screen) or allowed to submit a form.

Common Failure Modes and Troubleshooting Checklist

If your first delegated mobile task stalls or returns incomplete data, check these four common causes:

Vague completion criteria: Telling a mobile agent "check the app and see if it works" leads to ambiguous summaries. Always specify the exact screen element or value to return (for example, "return the exact text of the toast message or price total after applying code TEST20").
Missing time zone or locale context: If your task checks date pickers (such as flight, hotel, or appointment calendars), specify the exact date in YYYY-MM-DD format and note the target time zone.
Local ADB conflicts on physical Autopilot phones: If you are using a physical Android phone with Autopilot on your desk, disconnect active local adb logcat or scrcpy locks that might fight over input focus during a scheduled run.
Hitting daily usage caps with tight polling loops: Do not write a while true loop in bash that triggers a mobile UI check every 60 seconds. Use Airtap's built-in scheduling (for example, checking twice daily or every few hours) so tasks stay within the daily soft usage cap.

Frequently Asked Questions

Can I use the same skill file across OpenAI Codex CLI, Claude Code, and Cursor?

Yes. Because https://airtap.ai/skill.md is written as a portable Markdown instruction and command contract, any agentic coding tool that can read a local .md skill file and execute shell or HTTP calls can use the exact same setup.

Do I need to root my Android phone to use Autopilot?

No. Connecting a physical Android phone through Airtap's Autopilot app uses standard Android system capabilities and does not require unlocking the bootloader or rooting the device. And if you use Airtap's Cloud Phone, no physical hardware is required at all.

What does it cost to test mobile tasks from a coding agent?

Airtap is free to start, with a daily soft usage cap that resets at 00:00 UTC, so you can wire up the skill file and test delegated Android workflows without upfront infrastructure costs.

Disclosure: This tutorial was written for Airtap to demonstrate how developers connect terminal coding agents to cloud and physical Android devices via skill files. #abotwrotethis

Claude Code Android automation without ADB: tasks, states and follow-ups

douzatan — Tue, 29 Sep 2026 14:13:37 +0000

Claude Code Android automation does not need adb, a USB cable or a local emulator if the phone lives in the cloud: you install a skill, add an access token, and Claude Code sends tasks in plain English to a real Android device, then polls them until they finish or need you. Setup is four commands and one token.

The device in this tutorial comes from Airtap, which runs a real Android phone for you in an isolated cloud container, and the bridge is its open-source skill at github.com/airtap-ai/airtap-skill. Every command below comes from that repo's README and skills/airtap/SKILL.md, checked against the main branch in September 2026. This is for developers who already use Claude Code or Codex and want it to operate apps on a remote phone. Building or testing your own APK is out of scope.

TL;DR

claude plugin marketplace add airtap-ai/airtap-skill
claude plugin install airtap@airtap
export AIRTAP_PERSONAL_ACCESS_TOKEN="<token from Settings in the Airtap app>"
python3 scripts/airtap.py task create --message "<what to do>" --receiver-id cloud

How does Claude Code Android automation work without ADB?

Most Android tools for Claude Code are MCP servers that drive a phone plugged into your machine through adb, so Claude Code decides every tap. This skill splits the work differently. Claude Code writes the task in plain language, and Airtap's own agent, working on the device, does the tapping.

The path looks like this:

Claude Code picks up the airtap skill and runs its bundled CLI, scripts/airtap.py.
The CLI calls the Airtap API over HTTPS with your token as a Bearer header.
The task goes to a receiver: cloud (the hosted phone, and the default) or a physical Android phone you linked through the Autopilot app.
The on-device agent works through the app screen by screen and writes progress messages back to the task.
Claude Code polls those messages and decides what to tell you.

The trade-off is control. With adb you script every coordinate. Here you hand off one task per request and manage its lifecycle, which is most of what follows.

What you need before you start

Claude Code or Codex. Cursor, Windsurf, Cline and GitHub Copilot also work through npx skills.
python3 with requests and python-dotenv (the skill's whole requirements.txt).
Node.js if you use the npx skills route.
An Airtap account. Sign in at airtap.ai/app with Google. No paid plan is needed; a per-account daily limit applies and resets at 00:00 UTC.

Step 1: install the skill

Claude Code

claude plugin marketplace add airtap-ai/airtap-skill
claude plugin install airtap@airtap

Per the Claude Code plugin docs, a plugin you install from the shell loads the next time you start Claude Code, or right away if you run /reload-plugins in an open session. claude plugin list confirms it's installed.

Codex

npx skills add airtap-ai/airtap-skill -a codex

Cursor, Windsurf, Cline or GitHub Copilot

The -a flag of npx skills picks the agent:

npx skills add airtap-ai/airtap-skill -a cursor
npx skills add airtap-ai/airtap-skill -a windsurf
npx skills add airtap-ai/airtap-skill -a cline
npx skills add airtap-ai/airtap-skill -a github-copilot

The public repo; the install commands above come from this README.

If the dependencies are missing, run this from the skill directory:

pip3 install -r requirements.txt

Step 2: add your personal access token

In the Airtap web app, open Settings, create a personal access token and copy it. Then give it to the skill in one of two ways.

Set an environment variable before you launch your agent:

export AIRTAP_PERSONAL_ACCESS_TOKEN="your-personal-access-token"

Or write it into scripts/.env from the skill directory:

python3 scripts/airtap.py --add-token "your-personal-access-token"

Two repo details matter. Values in scripts/.env override a shell variable of the same name, so a stale .env beats a fresh export. And SKILL.md tells the agent not to ask you to paste the token into chat, so run this yourself in a terminal.

Skip this step and the first API call fails fast. This is what receiver get-list prints with no token set:

Error: Missing auth token. Run --add-token or add AIRTAP_PERSONAL_ACCESS_TOKEN to .env before running this command.

Step 3: run a first task on the cloud phone

You don't type CLI commands yourself. Ask Claude Code something like "Use the Airtap skill to open the Play Store on the cloud phone and list the apps on the home screen," and the skill turns it into:

python3 scripts/airtap.py task create \
  --message "Open the Play Store and list the apps on the home screen" \
  --receiver-id cloud

The response includes a taskId, which every later command needs. Also note:

The cloud phone takes about 60 seconds to set up the first time.
Some apps come pre-installed. Sign in to Google Play on the phone for the rest.
You log in to your own accounts yourself, once. The web dashboard shows the cloud phone's live screen.

To target your own linked phone instead, run receiver get-list and pass its ID. SKILL.md tells agents to stay on cloud unless you ask for a specific device.

Step 4: watch the task, answer it, or stop it

A task can take a few seconds or several minutes, so the repo treats it as a long-running job. Monitor it with task poll:

python3 scripts/airtap.py task poll --task-id "task_abc123"

It calls task get-details every 10 seconds (change that with --interval-secs). It stops by itself once the task completes, fails, is cancelled or needs input, and it returns the full task payload plus a _poll summary. In that payload, messages is the conversation in order, and most progress updates come from the newest type: "agent" message.

Send more input, or resume a paused task:

python3 scripts/airtap.py task add-user-message --task-id "task_abc123" --message "Continue"

Stop it:

python3 scripts/airtap.py task cancel --task-id "task_abc123"

If you leave out --model-id, tasks run on airtap-1.0-flash, which is quicker and fine for short jobs. For long multi-step flows, pass --model-id airtap-1.0. It's slower, but more reliable on complex work. Both task create and add-user-message also accept --image-file if a screenshot or reference picture helps.

What do the task states mean for your agent?

task poll exits on six states. Three are final, and three mean a human is needed. This table maps each one to what SKILL.md tells the agent to do:

`taskState`	What happened	What your agent should do	Command
`COMPLETED`	Task finished	Summarize the latest agent messages	none
`FAILED`	Task could not finish	Report the state and the last agent message	none
`CANCELLED`	Task was cancelled	Report it	none
`WAITING_FOR_USER_INPUT`	The agent needs a clarification	Ask you, forward the answer	`task add-user-message`
`WAITING_FOR_USER_INTERVENTION`	Someone has to act on the device (a login, for example)	Tell you exactly what to do, wait for your OK, resume	`task add-user-message`
`WAITING_FOR_USER_CONTINUE`	Task hit its step limit	Summarize progress, ask whether to continue	`task add-user-message`

Claude Code already reads these rules from SKILL.md. To pin the same behavior for every agent in a repo, add this to CLAUDE.md or AGENTS.md:

## Android tasks (Airtap skill)
- Use receiver `cloud` unless I name a device.
- After `task create`, run `task poll` and wait. Do not create a second task for the same request.
- On any WAITING_* state, stop and ask me. Never answer on my behalf.
- Never ask me to paste the access token into chat.

How should you word Android tasks for an agent?

The on-device agent reads the screen at each step, so a vague task still runs, but it wanders. Habits that help:

Name the app and the finish line. "In the Weather app, read tomorrow's high for Chicago and stop" is better than "check the weather".
Say what must not happen: "do not place the order", "do not send the message".
Put the output format in the task so the summary is easy to parse.

Three task messages written that way:

Open the Play Store, search for "Google Keep", and report the rating and last-updated date of the official app. Do not install anything.
In Google Maps, find the three closest pharmacies to Union Square, San Francisco that are open now. Return name and closing time.
Open the Gmail app, count unread emails from the last 24 hours, and list the five senders. Do not open or archive any email.

If a task depends on where you are, update your location first:

python3 scripts/airtap.py user update-location --payload '{"latitude":37.7880,"longitude":-122.4075}'

Troubleshooting the Airtap skill

Symptom	Likely cause	Fix
`Missing auth token...`	No token in the environment or `scripts/.env`	Step 2
The new token is ignored	An old `scripts/.env` overrides the shell variable	Edit or delete `scripts/.env`
`Airtap API request failed with status 404`	SKILL.md: on any 404 or request failure, get an updated skill before retrying	`claude plugin marketplace update airtap`, or `npx skills update airtap`
Claude Code doesn't list the skill	Plugin not loaded yet	`/reload-plugins`, then check `claude plugin list`
Skill missing on claude.ai/code	Cloud sessions don't load plugins you installed locally	Run Claude Code locally
`ModuleNotFoundError: No module named 'requests'`	Dependencies missing	`pip3 install -r requirements.txt`
`python3` not found on Windows	The interpreter is called `python` or `py` there	Swap the command name
Task stuck in a WAITING state	It's waiting on you	See the state table

When a request fails without a clear message, check the CLI's debug log at airtap/airtap.log in your system temp directory.

Limits and security notes

This is not a test harness. You get task results and progress messages, not per-tap assertions. For testing your own app, use adb-based tools.
Logins stay with you. According to Airtap's homepage, passwords are never stored or shown to the agent, and the agent is blocked from reading secure fields. That also means a task can pause in WAITING_FOR_USER_INTERVENTION until you type something yourself.
Live screen view is only for the cloud phone. Physical devices linked through Autopilot have no live view yet, so poll output is all you see there. Autopilot is Android only.
Treat the token like any API key. Keep scripts/.env out of git and out of anything you screenshot.
A loop that keeps re-creating failed tasks eats the daily soft cap. Limit retries.

Quick answers

Can Claude Code drive an iPhone this way? No. The receivers are Android: the cloud phone or your own Android phone through Autopilot.

Can it use my real phone instead of the cloud one? Yes. Link it with the Autopilot Android app, find its ID with receiver get-list, and ask for that device by name.

Once your first task poll comes back COMPLETED, the setup is done. What's left is wording, and the three task messages above are a reasonable template for the next one.

Treat Your Product Line Art Like Code: A Docs-as-Code Pipeline from Photo to Spec-Sheet Flat

douzatan — Thu, 17 Sep 2026 16:25:06 +0000

The AI Line Art Generator tool page on Virse, the generation step this pipeline builds around

A product photo to line drawing conversion is the easy part of hardware documentation. Keeping that drawing correct through the next five product revisions, without anyone quietly re-uploading a photo by hand every time the part changes, is the part most documentation pipelines get wrong.

Most teams writing hardware docs already treat their Markdown, their API references, and their release notes as code: version controlled, reviewed in pull requests, rebuilt automatically the moment something upstream changes. Then a designer generates one line drawing for a spec sheet, drops the PNG into a shared drive, and that file quietly becomes the one artifact in the whole documentation set nobody can trace back to a source photo, a parameter, or a revision. Screenshots and diagrams are already the part of a doc set that goes stale first, mostly because updating an image takes one extra manual step that updating a sentence does not. Line art generated from a product photo has the same problem, and it is worth solving the same way you would solve any other pipeline gap: give the step a predictable input, a predictable output, a stated reason to rerun it, and a way for a teammate to review what changed.

Product photo to line drawing: a one-time conversion versus a pipeline step

The drawing is traced from a real photo, which is exactly why it cannot be regenerated from a text prompt alone

A tool that turns a photo into line art is reading the shape of a real object and tracing it, not guessing at a shape from a text prompt. That single fact is why this kind of asset cannot be treated the same way you treat a diagram written in Mermaid or PlantUML syntax. A diagram-as-code file is source code. Check it into Git, and anyone can regenerate the exact same picture from the exact same text forever. A line drawing pulled from a photo has no text equivalent to check in. The only way to regenerate it is to keep the photo, the line style, and any notes about what to keep or drop, and run the generation step again with those same three inputs.

Treat the photo, the parameters, and the result as one unit that travels together, and a "one-time conversion" turns into an ordinary pipeline step with a beginning and an end you can point to. Skip that step, and the drawing becomes exactly the kind of orphaned asset a docs-as-code setup was supposed to prevent in the first place.

What a docs-as-code pipeline expects from any generated asset

A typical docs-as-code setup gets built around plain text formats, Git as the single source of truth, continuous integration that rebuilds the site automatically, pull request review, and a linter that catches formatting drift. That checklist is written for prose, and it usually has exactly one line about images: automate your screenshots. A generated line drawing needs the same four things any other pipeline output needs, and none of the four are specific to line art at all:

A predictable input: the source photo, plus whatever settings actually produced this exact result
A predictable output location: a path that does not depend on someone remembering where they saved a file three weeks ago
A rerun trigger: a stated, specific reason the step needs to run again, not a vague sense that the drawing looks old
A reviewable change: some way for a teammate to look at a pull request and understand what actually moved between the old drawing and the new one

The rest of this piece works through what those four things look like once you make them concrete for a product line drawing instead of leaving them as an abstract checklist.

Naming the output: encode product, angle, line style, and revision in one filename

A filename that only says kettle-lineart-final.png fails the moment there is a second kettle revision, a second camera angle, or a second line style for the same product. A name that survives more than one revision needs to encode four things at once instead of one:

Segment	Example value	Why it needs to be there
Product identifier	`kettle-900ml`	Distinguishes this part from every other part living in the same repository
Angle or view	`front34`	A three-quarter front photo and a straight side photo of the same product are not interchangeable inputs, and a filename should say which one produced this drawing
Line style	`detailed`, `clean`, or `bold`	The three real options on the generator, Detailed line art, Clean line art, and Bold outline, produce results that are not substitutes for each other
Revision	`rev-b`	Marks which iteration of the product this drawing was traced from

Engineering drawings solved the revision part of this problem long before anyone generated a line drawing from a photo. Design-phase revisions use letters, construction or as-built phases switch over to numbers starting at 0, and the letters I, L, and O get skipped entirely because they are too easy to misread as the digits 1 and 0, especially on a faded printout. Borrowing that convention for generated line art costs nothing and buys the same benefit a factory floor has relied on for decades: kettle-900ml-front34-detailed-rev-b.png tells a teammate everything they need to know about a file without opening it first.

Generating the actual drawing is the one step in this pipeline a documentation team does not need to build in house. Upload a product photo with the background already removed, pick one of the three real options on the form, and download the black-on-white result. Virse's AI Line Art Generator works this way, and you can try it here to compare Detailed line art, Clean line art, and Bold outline on a real product photo before deciding which one becomes the canonical drawing for a given revision. What matters for the pipeline is not which tool draws the line. What matters is that whatever tool produces it, the result traces back to a real photo you can point to, with a line style you can name, instead of a result nobody can reproduce next quarter.

Where the drawing lives: a folder a documentation build can actually trust

A flat sketch like this is exactly the kind of asset a documentation build needs to trust the revision of

The filename convention above only helps once the file actually lands somewhere predictable. A docs repository can hold generated line art the same way it holds any other build artifact, as long as the source photo and the result sit next to each other instead of the source living in someone's downloads folder while the result lives alone in the docs repo:

assets/line-art/
  kettle-900ml/
    rev-b/
      source-front34.jpg
      params.json
      kettle-900ml-front34-detailed-rev-b.png
      kettle-900ml-front34-clean-rev-b.png
      kettle-900ml-front34-bold-rev-b.png

params.json is a small text file that records what actually happened when this drawing was made: which photo, which line style, which notes about seams or logos to keep or drop. That one file is what turns a folder of PNGs into something a documentation build can trust, because it answers "what would it take to regenerate this" without anyone having to track down whoever ran the original generation.

This structure earns its keep exactly where a tech pack or a spec sheet needs it most. A flat sketch has to show a part's proportions, seams, and hardware accurately enough that a factory can build from it without a phone call back to the design team, and industry guidance on tech packs is blunt about what happens once a product changes: the technical design update has to reach the manufacturer without any ambiguity. A line drawing sitting in a folder with no record of which revision it traces back to cannot make that promise, no matter how clean the drawing itself looks.

When to rerun the step: three triggers that actually justify a new drawing

"This drawing looks a little old" is not a rerun trigger. A real trigger is specific enough to write into a pull request description on its own, and there are three that actually apply to a photo-derived line drawing:

The product's geometry changed. A new revision changes a dimension, adds a feature, or removes one. The old drawing is now factually wrong, not merely out of date.
The reference photo changed. A better angle, a cleaner background removal, or a corrected framing produces a more faithful trace, even when the product itself did not change at all.
The downstream use changed the line style requirement. A drawing that started life as a Clean line art base for a canvas re-render now has to go into a factory-facing spec sheet, which calls for Detailed line art instead.

Any one of those three is worth a new revision folder and a fresh params.json. None of them is "someone thought the folder looked cluttered" or "it has been a while since anyone touched this."

Reviewing a line art change without a text diff

A Markdown file diffs cleanly. Git shows exactly which line changed, and a reviewer can read the whole story in the pull request without opening anything else. A PNG does not diff that way, and pretending it does by staring at two images side by side and hoping to spot the difference does not scale past the first handful of reviews. The workaround is to stop trying to diff the pixels directly and start diffing the thing that actually explains them.

Schematic: the rerun step loops back to the photo, it does not start a new pipeline

Splitting the review into two separate questions handles this in practice. First: does params.json show a change that matches the stated rerun trigger, a different source photo path, a different line style, a bumped revision letter? That part is an ordinary text diff, and any reviewer can read it inside a pull request without opening an image viewer at all. Second: does the new PNG, placed next to the old one, still look like the same object drawn to the same rules? That part still needs a human eye, but it becomes a much smaller and much faster check once the metadata diff has already confirmed the change was intentional and matches what the pull request claims it is doing.

What to check	How to check it	Automatable?
Did the right thing change	Text diff of `params.json`	Yes
Does the new revision label match the claim in the PR	Text diff of the folder path	Yes
Does the new drawing still look like the actual product	Side-by-side visual comparison	No, this still needs a human

What this pipeline still cannot automate away

None of the structure above replaces judgment about the drawing itself. A tool that traces a real photo will not invent detail that was never in the picture, and it will not quietly drop the object's actual proportions just to produce a cleaner-looking line, but it also has no opinion about whether a given change deserves a new revision folder or whether the reference photo was clean enough to trust in the first place. That call belongs to whoever is building the documentation, the same way deciding to merge a pull request belongs to whoever is reviewing it, not to whatever tool generated the diff underneath.

Treating a generated line drawing like code does not mean pretending it is text. It means giving it the same four things any other build artifact already gets in a docs-as-code setup: a name that says what it is, a folder that says where it came from, a stated reason it exists in this particular form, and a way for a teammate to check the change without taking a screenshot on faith. Once that structure is in place, regenerating a drawing after the sixth product revision is a rerun of a known step, not an afternoon spent trying to remember which photo the first version ever came from.

YouTube transcript to documentation: a reviewable workflow

douzatan — Tue, 15 Sep 2026 16:15:02 +0000

Turning a YouTube transcript to documentation means organizing the spoken explanation around a task, checking the technical details, and keeping links to the moments that support them. The deliverable should let another developer complete the task and review the instructions without replaying the entire video.

This AllyHub guide uses AllyHub's transcript extractor to obtain published captions with timestamps. Extraction supplies the source material; a documentation author still needs to verify commands, fill in prerequisites, and decide which explanation belongs in the final page.

Working order: collect the transcript, map the source, write the task, check the result.

In this guide: source map, technical checks, task draft, review.

How do you turn a YouTube transcript to documentation?

Start with a video that covers one identifiable task, then use its timestamped transcript to build a task-based outline. For a first pass, choose something bounded, such as configuring a local project or explaining one deployment setting.

YouTube's own transcript view can help you inspect the source. For videos with captions, the transcript lets you jump from a line of text to the corresponding moment in the video, according to YouTube Help.

That jump matters when a sentence depends on a screen the reader cannot see. A speaker might say "change this value" while highlighting a configuration key. The transcript preserves the words, but the documentation needs the key, its intended value, and the reason for the change.

Before drafting, write down the intended reader and the starting state. "A teammate with the repository cloned but no local configuration" is a useful boundary. It tells you which setup steps the page must include.

Keep a source map before editing

Make a small table that connects each planned section to its supporting passage. This is a working record for the author and reviewer, so include uncertainty while it is still easy to resolve.

Documentation section	Source to keep	What to verify
Prerequisites	Video URL and relevant timestamp	Versions, permissions, and required files
Main procedure	Passage and the screen shown at that moment	Exact commands and order of operations
Expected result	Demonstration of a successful result	What success looks like for the current setup
Troubleshooting	Error discussed or demonstrated	Whether the remedy applies to the documented version

Keep the raw transcript alongside your edited notes. If an automatic caption misspells a package name, retain the original in the source file and correct it in the draft after checking the video or the package documentation.

Use the source map to find missing steps. If the video jumps from installation to a working application, the author must find out what happened between those states before calling the page a complete setup guide.

Which parts of a tutorial need independent checking?

Check every instruction whose correctness depends on exact syntax, software version, or the reader's environment. Captions can help locate those details, but they should not be treated as a command reference.

Pay particular attention to:

Commands that create, change, or remove files.
Environment variable names and configuration keys.
Prerequisites that the presenter already had installed.
Settings shown on screen but never spoken aloud.
Error messages and the conditions that produced them.

Use the official documentation for the actual version you are describing. If the video covers an older release, either scope the article to that release or update and verify the affected instructions.

Do not silently repair a command because it looks plausible. Mark it as unverified in your working notes, find the relevant source, and test it in a suitable environment before including it in an executable tutorial. The published page should contain the resolved instruction.

Turn the transcript into a task someone can finish

Organize the draft around what the reader must do. A video may include a long introduction, a failed attempt, and an explanation that only arrives after the demonstration. Written documentation can put the prerequisite first and move the failure into troubleshooting.

For each step, supply an action and an observable result. "Configure the project" leaves too much open. "Create the local configuration file, add the documented variables, then start the development server" gives the reader a sequence, though the final page still needs the exact names and commands.

Use this copyable structure:

Task:
Starting state:
Required versions and access:
Source video and timestamps:

Steps:
For each step, record the action and expected result.

Verification:
Explain how the reader can confirm the task succeeded.

Troubleshooting:
Name the symptom, likely cause, and checked remedy.

Last technical check:
Record the environment and the date of verification.

Review the draft against the source

Review source accuracy and task completion separately. A passage can accurately summarize what the speaker said while leaving the reader unable to reproduce the result.

First, compare the draft with the video at the saved timestamps. Check names, quoted statements, and the meaning of each explanation. Then follow the instructions from the declared starting state, recording any missing step or unexpected result.

The final handoff should contain the finished page and a compact source record. Keep draft uncertainties out of the published instructions, but preserve the evidence that resolved them in your working files.

Questions that come up during the handoff

Can you do this when a video has no captions?

The caption-based workflow needs an available caption track. If none exists, obtain a transcript through a separate transcription process or work from the recording manually. Check the resulting text against the audio and screen before using it as a technical source.

Should every sentence have a timestamp?

Usually the working source map can hold the detailed timestamps. In the published page, retain direct links for quotations, demonstrations, or explanations a reader may need to inspect. The goal is a reviewable document that remains comfortable to read.

For your next YouTube transcript to documentation task, start with one procedure and one reviewer. Finish when that reviewer can follow the page and trace any uncertain instruction back to its source.

Onboarding-Videos aus Team-Dokumentation generieren: unser Workflow nach drei Monaten

douzatan — Sat, 08 Aug 2026 15:45:09 +0000

Unser Team hat ein klassisches Problem gelöst, das vermutlich jedes wachsende Entwicklerteam kennt: Die Onboarding-Doku liest niemand, und für Videos hat niemand Zeit.

Die Lösung war unspektakulär pragmatisch. Wir generieren die Videos jetzt direkt aus den Dokumenten, die wir sowieso pflegen. Kein Kamera-Setup, kein Schnittprogramm, keine zusätzliche Content-Pipeline.

Dieser Post beschreibt den Workflow, die Einstellungen, die tatsächlich einen Unterschied machen, und die Stellen, an denen der Ansatz an seine Grenzen stößt.

Ausgangslage: 40 Seiten Confluence, die keiner liest

Wir sind ein Team von elf Leuten. Unsere Onboarding-Doku war solide gepflegt: Architektur-Überblick, Deployment-Prozess, Coding-Standards, Incident-Runbooks.

Das Problem war nicht die Qualität. Das Problem war das Format. Neue Kollegen bekamen in der ersten Woche einen Berg Text, und die immer gleichen Fragen landeten trotzdem im Team-Channel.

Der naheliegende Gedanke "machen wir doch Videos draus" scheiterte zweimal an der Realität: Wer selbst aufnimmt, produziert bei unserem Doku-Umfang wochenlang. Und bei jedem Release veraltet ein Teil der Aufnahmen.

Der Kerngedanke: Docs bleiben die Source of Truth

Der Ansatz, der bei uns funktioniert, folgt derselben Logik wie Docs-as-Code: Es gibt genau eine Quelle, und alles andere ist ein generiertes Artefakt.

Das Dokument bleibt das Original. Das Video wird daraus erzeugt. Ändert sich der Inhalt, wird das Dokument editiert und das Video neu generiert.

Damit verschwindet das Problem, das jede Video-Initiative in Teams killt: der Pflegeaufwand. Ein veraltetes Video ist bei uns kein Neuaufnahme-Projekt mehr, sondern ein Regenerieren mit aktualisierter Quelle.

Der Workflow im Detail

Wir nutzen dafür den AI-Learning-Video-Generator von Leadde. Der Ablauf besteht aus vier Schritten.

Schritt 1: Dokument hochladen

Unterstützt werden .pptx, .pdf, .doc, .docx und .txt bis 500 MB. Wir exportieren die jeweilige Doku-Seite als PDF oder Word-Datei.

Ein Detail, das uns Arbeit erspart hat: Diagramme und Screenshots aus dem Quelldokument werden geprüft und, wenn brauchbar, direkt ins Video übernommen. Unsere Architektur-Diagramme mussten wir nicht neu bauen.

Alternativ akzeptiert das Tool auch reinen Text oder einen Prompt, aus dem es selbst eine Struktur baut. Für Doku-Fragmente ohne saubere Datei ist das der schnellere Weg.

Schritt 2: Output konfigurieren

Die Einstellungen, die bei uns den Unterschied machen:

Avatar: über 200 zur Auswahl. Wir haben einen festgelegt und verwenden ihn für die gesamte Serie. Konsistenz schlägt Abwechslung.
Länge: vier Presets. Zusammenfassung (1 bis 3 Minuten), ausgewogen (3 bis 5), vertieft (5 bis 7), umfassend je nach Quellumfang. Für Onboarding-Module nehmen wir fast immer das ausgewogene Preset.
Sprache: 88 Optionen. Wir generieren auf Deutsch und für zwei englischsprachige Kollegen zusätzlich auf Englisch, aus derselben Quelle.

Der unterschätzte Teil sind die Kontextfelder unter "Weitere Einstellungen": Erzählstil, Zielgruppe, Sprecherhintergrund, Lernziel. Ein Skript, das mit "Zielgruppe: Backend-Entwickler, neu im Team, kennt unseren Stack nicht" generiert wurde, unterscheidet sich deutlich von einem ohne Kontext. Diese Felder leer zu lassen ist der häufigste Anfängerfehler.

Schritt 3: Skript reviewen, wie ein Pull Request

Nach der Analyse liefert das Tool eine Gliederung plus komplettes Sprecherskript. Dann gibt es zwei Buttons: im Studio editieren oder direkt generieren.

Wir behandeln das Skript wie einen PR: Es wird nie ungelesen gemerged. Der Review dauert bei uns zehn Minuten pro Video und folgt einer festen Checkliste:

Einstieg umschreiben. Die generierten Intros sind korrekt, aber generisch.
Fachbegriffe prüfen. Interne Projektnamen und Abkürzungen paraphrasiert die KI gern falsch.
Aussprache fixen. Dafür gibt es ein eigenes Tool; einmal korrigiert, sitzt der Begriff in allen folgenden Videos.

Für Serien-Konsistenz nutzen wir zusätzlich die Knowledge-Base-Funktion: Referenzmaterial hinterlegen, damit die Terminologie über alle Videos stabil bleibt statt zu driften.

Schritt 4: Generieren und Stichprobe

Die Generierung läuft ein paar Minuten pro Video. Wir queuen mehrere und reviewen im Block.

Der finale Check: Untertitel kontrollieren (automatisch generiert, Styling anpassbar), Szenenübergänge prüfen, einmal komplett in 1,5-facher Geschwindigkeit ansehen. Einzelne Szenen lassen sich isoliert korrigieren, ohne den Rest anzufassen. Das macht Wartung realistisch.

Zahlen nach drei Monaten

22 Onboarding-Module als Video, generiert aus bestehender Doku. Reale Arbeitszeit: rund 8 Stunden insgesamt.
Aufwand pro Video: 15 bis 25 Minuten, der Großteil davon Skript-Review.
Zwei Releases mit Doku-Änderungen seither. Update-Aufwand: Dokument editieren, regenerieren, fertig. Früher wäre das der Punkt gewesen, an dem die Videos verwaist wären.

Der messbare Effekt im Team: Die Wiederholungsfragen im Channel sind spürbar zurückgegangen, und neue Kollegen kommen mit konkreteren Fragen in die erste Pairing-Session. Kein kontrolliertes Experiment, klar. Aber der Trend war deutlich genug, dass wir den Rest der Doku nachziehen.

Wo der Ansatz an Grenzen stößt

Drei ehrliche Einschränkungen.

Erstens: Das Skript braucht immer einen menschlichen Review. Die Struktur stimmt, der Ton ist austauschbar. Wer ungeprüft published, bekommt eine Videobibliothek, die klingt wie von einer Maschine, weil sie es ist.

Zweitens: Ein Avatar ersetzt keinen guten Live-Workshop. Für interaktive Formate, Pairing und Architektur-Diskussionen bleibt der Mensch gesetzt. Die generierten Videos decken den reproduzierbaren Teil ab, nicht den dialogischen.

Drittens: Garbage in, garbage out. Schlecht strukturierte Doku ergibt schlecht strukturierte Videos. Der Ansatz belohnt Teams, die ihre Doku ohnehin ernst nehmen, und bestraft die anderen doppelt.

Integration in den bestehenden Doku-Prozess

Der Workflow oben beschreibt das Generieren. Interessanter ist, wie das Ganze dauerhaft im Team-Prozess lebt, ohne dass es eine Person "nebenbei" tragen muss.

Unsere Regeln nach drei Monaten Iteration:

Ownership folgt der Doku. Wer ein Doku-Kapitel pflegt, pflegt auch dessen Video. Kein separates Video-Team, keine Übergabe. Das Video ist ein Artefakt des Kapitels, wie ein generiertes Diagramm.

Regenerieren ist Teil der Definition of Done. Ändert ein PR die Onboarding-Doku substanziell, gehört das Neu-Generieren des betroffenen Videos zur Fertigstellung. Klingt streng, kostet real aber die erwähnten 15 bis 25 Minuten und verhindert das schleichende Veralten, an dem unsere früheren Video-Anläufe gestorben sind.

Ein Namensschema von Anfang an. Videos heißen bei uns wie die Doku-Kapitel, aus denen sie stammen, plus Versionsdatum. Banal, aber die Zuordnung Quelle-zu-Video muss ohne Nachdenken funktionieren, sonst regeneriert irgendwann jemand aus der falschen Version.

Quartalsweise Stichprobe. Einmal pro Quartal sieht sich ein Teammitglied drei zufällige Videos komplett an. Findet es veraltete Inhalte, war der Prozess davor undicht. Bisher zweimal passiert, beide Male ein fehlendes Regenerieren nach Doku-Änderung.

Was wir bewusst nicht tun: Videos für Inhalte generieren, die sich wöchentlich ändern. Sprint-spezifisches bleibt Text. Die Video-Schicht lohnt sich ab einer Halbwertszeit von ungefähr einem Quartal, darunter frisst die Pflege den Nutzen.

FAQ aus dem Team-Channel

Braucht man Video-Editing-Kenntnisse?
Nein. Der Editor funktioniert wie ein Folien-Tool, nicht wie ein Schnittprogramm. Hochladen, konfigurieren, Skript reviewen, generieren. Wer Slides bauen kann, kann das hier auch.

Wie gut ist das deutsche Voiceover?
Besser als erwartet, mit einer Einschränkung: Fachbegriffe und Projektnamen brauchen gelegentlich einen manuellen Aussprache-Fix. Der ist einmalig pro Begriff und gilt danach für alle Videos.

Was kostet ein Video an Zeit?
Nach der Einrichtungsphase 15 bis 25 Minuten Eigenaufwand. Die ersten zwei, drei Videos dauern länger, weil man seine Einstellungen noch sucht. Danach ist es Routine.

Lohnt sich das für kleine Teams?
Gerade für kleine. Große Organisationen haben L&D-Abteilungen; kleine Teams haben niemanden, dessen Job das ist. Genau diese Lücke füllt der generierte Ansatz.

Was ist mit vertraulichen Inhalten in der Doku?
Wir trennen vorher: Onboarding-Inhalte, die ins Video dürfen, liegen in eigenen Kapiteln, getrennt von Secrets, Kundendaten und internen Details. Diese Trennung hatten wir aus Doku-Hygiene ohnehin, sie zahlt sich hier doppelt aus. Zusätzlich lassen sich veröffentlichte Videos mit Passwortschutz versehen, was wir für teaminterne Module standardmäßig tun.

Warum nicht einfach Loom-Aufnahmen?
Haben wir davor gemacht, und die Aufnahmen waren nach zwei Releases veraltet und wurden nie aktualisiert, weil Neuaufnehmen Aufwand ist. Screencasts sind super für einmalige Erklärungen an eine Person. Für wiederverwendbare Module mit Update-Bedarf verliert das Format gegen generierte Videos, deren Quelle ein editierbares Dokument ist.

Fazit und Einstiegspunkt

Wer seine Onboarding-Doku pflegt und trotzdem zusieht, wie sie ungelesen bleibt, hat das Rohmaterial bereits fertig. Der Rest ist Transformation, keine Produktion.

Der pragmatische Test: das meistgefragte Doku-Kapitel exportieren und damit E-Learning-Videos selbst erstellen, mit ausgewogenem Preset und ausgefüllten Kontextfeldern. Nach einer halben Stunde liegt das erste Modul vor, und die Entscheidung fällt auf Basis eines echten Ergebnisses statt einer Produktseite.

Bei uns hat genau dieses eine Testvideo den Ausschlag gegeben. Die anderen 21 kamen, weil das erste gut genug war.

Fragen zum Workflow gern in die Kommentare. Insbesondere Erfahrungen mit anderen Doku-zu-Video-Pipelines würden mich interessieren; unser Setup ist bewusst simpel gehalten, und ich bin sicher, da geht noch mehr.

Ein Punkt, den ich als Nächstes testen will: die Analytics-Daten der Videos systematischer auswerten. Die Plattform zeigt pro Video, wie weit geschaut wird, und die Abbruchstellen unserer Onboarding-Module sind vermutlich die ehrlichste Doku-Review, die wir je hatten. Wo Leute aussteigen, ist entweder das Video zu lang oder das zugrunde liegende Kapitel schlecht strukturiert. Beides ist ein Fix im Quelldokument, kein Video-Problem. Wenn sich daraus etwas Brauchbares ergibt, schreibe ich einen Follow-up-Post.

My 30-minute monthly ritual for picking dev tutorial topics

douzatan — Sat, 01 Aug 2026 15:27:16 +0000

I make developer tutorials on the side, and for a long time my topic pipeline was "whatever bug I fought last." That produces the occasional hit and a lot of misses, because the bugs I happen to hit aren't a representative sample of what my audience is stuck on.

About a year ago I replaced the vibes with a ritual. Last Sunday of the month, coffee, thirty minutes, one page in my notes app. Here's the whole thing, phase by phase, in case it's useful to steal.

Phase 1 — Dump the candidates (5 minutes)

I open a note and brain-dump every topic I could plausibly make a video about that month. No filtering. Bugs I fixed, questions from my Discord, a library I finally understood, something a coworker asked twice.

The goal here is volume, not quality. I usually land on 12 to 20 candidates. Most will die in the next phase, and that's the point — this is the cheapest place to kill a bad idea, before it costs me a weekend of filming.

Phase 2 — Pull real demand (10 minutes)

This is the phase that changed my numbers, so I'll spend the words here.

I take each candidate and check whether people actually search for it, and in what words. I use AllyHub's free tool to look up the YouTube most searched keywords around a topic — I type in a candidate like "react useEffect cleanup" and it shows me what people search near it, which phrasings pull more interest, and which videos currently surface for those queries.

Two columns go in my note for each candidate: rough relative demand, and how strong the existing coverage looks. I'm not chasing precise numbers — the tool gives relative signal, not a view-count promise, and I treat it that way. I just want to know: is anyone looking for this, and is it already answered to death?

A candidate I was sure about — "clean architecture in Node" — turned out crowded and well-served. One I nearly cut — "prisma migrate drift resolve" — showed steady interest with only scattered forum answers behind it. Column data flipped my instinct completely.

Phase 3 — Score and rank (5 minutes)

Now I sort. My scoring is deliberately dumb: I want the intersection of real demand and weak existing coverage. High demand plus ten strong videos already there? Skip — I won't win that. Real demand plus stale or thin coverage? That goes to the top.

I also flag anything with essentially zero search volume that I still want to make. More on those in a second. They don't get scored against the demand topics — they're a separate bucket.

By the end of this phase I have a ranked shortlist of three or four topics, and I pick the top one or two to actually produce that month.

Phase 4 — Reality-check with my own judgment (5 minutes)

The data tells me what's wanted. It does not tell me whether I can make a good video about it, and I don't let it pretend otherwise. So the last five minutes are a gut check on each shortlisted topic: do I actually understand this well enough to teach it clearly, do I have a decent example on hand, will I still care about it once the camera's rolling.

A topic can have great demand and still be a no for me because I'd make a shallow video. Demand is necessary. It's nowhere near sufficient. The quality is entirely on me once I hit record — no keyword tool is going to save a tutorial where I don't know the material.

The exemption I keep on purpose

That separate bucket from Phase 3 matters. Some videos I make regardless of search demand, and I refuse to route them through this ritual.

When I release an open-source tool, I make a walkthrough — nobody's searching for a thing that launched yesterday. When I have an opinion about where a framework is heading, I record it. When something breaks in a way that taught me something, I do a post-mortem. These are bets on trust and voice, not discovery, and running them through a demand filter would just talk me out of the work worth doing.

So the ritual isn't "only make what people search for." It's "know which bucket a video is in." Discovery videos earn their spot through demand. Authority videos earn it through having something to say. The whole point of thirty minutes on the last Sunday is to stop confusing the two — which I did, expensively, for about two years before I wrote the ritual down.

Your Hackathon Demo Video Has a Second Life — Measure It

douzatan — Sat, 01 Aug 2026 15:02:59 +0000

The weekend ends, the judges score, someone wins the API-sponsor prize, and everyone flies home. What most teams forget is that the two-minute demo video they recorded at 3 a.m. is still online, still indexed, and still answering a question people type into search months later. That video outlives the event by a wide margin. The event was one day. The video is a permanent artifact.

Almost nobody measures the afterlife. Teams check the view count the Monday after — 200 views, mostly teammates and judges — and never look again. They miss the interesting part, which happens slowly and much later.

The demo is a landing page you already built

Think about who finds a hackathon demo six months out. Not the judges. It is someone with the exact problem your hack solved, typing "how to X with Y API" into YouTube or Google and landing on your clip. That person is worth a hundred launch-day teammates, because they arrived carrying the problem your project addresses.

If you shipped the project into a real product, that trickle is a lead source. If you're job hunting, it is a portfolio piece that keeps introducing itself while you sleep. Either way, the number you want isn't the total. It's whether new people keep arriving after the hype is gone.

A flat total hides the only signal that matters

Say the video sits at 1,400 views. Fine — but that lump tells you nothing about direction. Two very different stories produce the same 1,400:

A launch spike of 1,300 in week one from your own network, then near-zero. The video is dead; it only ever reached people you already knew.
300 in week one, then a steady 30–40 a week for the rest of the year. Search found it. Strangers with the problem keep showing up.

The second video is the asset. The first is a memento. You cannot tell them apart from a cumulative count — you need the shape over time, the per-week velocity. That is the whole reason to track a curve instead of a total.

Snapshot on a schedule and let history accumulate

The mechanics are dull, which is why they get skipped. You have to record the count on a fixed cadence so the gaps between readings become weekly velocity you can trust. Miss a few weeks and you are back to guessing.

I set a small tool to track YouTube video views on a daily snapshot for anything I want to watch long-term. It saves each reading, keeps the running history, and draws the per-day curve, so I'm looking at the slope rather than a single figure that only goes up. You configure it once and it keeps building the log on its own — no restart, no re-import when I check back in a quarter later. Daily is more than enough resolution here; a demo's afterlife moves in weeks, not seconds, and a live-updating counter would tell you nothing a once-a-day reading doesn't.

For deep channel analytics — retention, traffic sources, where a viewer dropped — YouTube Studio is the right place, and better than any outside tool for your own uploads. The external snapshot solves a narrower problem: it works across any public video, including ones on a teammate's or the organizer's channel you don't own, and it keeps the comparison clean over long stretches.

What the curve tells you to do next

Read the slope and act on it. A demo that keeps pulling steady weekly views is telling you the topic has durable search demand — that is a signal to write the blog post, cut the follow-up video, or point the project's landing page at that keyword. A demo that spiked and flatlined is telling you the idea traveled through your network but never connected to a standing question people search for.

Both are useful once the event is over and you're deciding where the project goes next. The hackathon graded your weekend. The view curve grades whether the thing you built keeps finding the people who need it.

Wie ich aus vorhandenen Schulungsunterlagen Lernvideos gemacht habe, ohne etwas zu filmen

douzatan — Sat, 01 Aug 2026 07:31:38 +0000

Unser Team hat brauchbare interne Schulungsunterlagen: Folien, ein paar PDFs, Notizen dazu, wie Dinge bei uns wirklich laufen. Was fehlte, war jemand, der sie sich ansieht. Neue Kolleginnen und Kollegen bekamen eine Foliensammlung ohne Kontext, überflogen sie und stellten dann trotzdem dieselben Fragen. Ein richtiges Lernvideo hätte geholfen, aber das von Hand zu produzieren, war nie realistisch. Also blieb es bei Text, den kaum jemand las.

Ich habe ausprobiert, Lernvideos direkt aus den Unterlagen zu erzeugen, die wir ohnehin pflegen. Hier eine kurze Bilanz, ehrlich auch bei den Grenzen.

Warum Folien als Lernmaterial schwach sind

Folien sind dafür gebaut, einen Vortragenden zu stützen. Ohne die Person bleiben Stichpunkte, denen die wichtigste Ebene fehlt. Ein Dokument ist besser zum Nachschlagen, aber schlechter für den ersten Durchgang, weil kaum jemand ein System von oben nach unten durchliest, um es zu verstehen. Was wirklich einarbeitet, ist ein einmaliger Durchlauf im eigenen Tempo. Genau den hatten wir nie, weil Aufnahme und Schnitt pro Thema mehr Aufwand sind als die eigentliche Arbeit.

Das Video aus dem Dokument erzeugen

Ich wollte Lernvideos mit KI erstellen und habe dem Tool gegeben, was schon da war: die Folien als Text plus meine Notizen. Er hat eine Gliederung entworfen, die Szenen aufgebaut und die Vertonung erzeugt. Man wählt einen Erzählstil und einen Detailgrad und benennt die Zielgruppe. Ich habe erklärend, ausführlich, Zielgruppe „neue Entwicklerin" eingestellt, und das Skript hat den Stoff vermittelt, statt Stichpunkte vorzulesen.

Entscheidend für einen Doku-Workflow: Die Eingabe ist das Dokument. Etwas Falsches korrigiere ich, indem ich den Text ändere und neu erzeuge, nicht durch eine neue Aufnahme. Als sich die Einrichtung letzten Monat geändert hat, war das Aktualisieren eine Sache von Minuten, kein Dreh. Für Leute, die den ganzen Tag an Code iterieren, fühlt sich das normal an. Die Unterstützung für viele Sprachen hieß außerdem, dass wir eine Version für nicht deutschsprachige Kolleginnen ausspielen konnten, indem wir das fertige Video übersetzen.

Wo es an Grenzen stößt

Ehrlich: Der erzeugte Sprecher wirkt bei genauem Hinsehen leicht synthetisch. Für interne Schulung stört mich das nicht, für etwas nach außen Gerichtetes würde ich es abwägen. Es ist außerdem deutlich besser darin, Konzepte und Abläufe zu erklären, als eine echte Bildschirminteraktion zu zeigen. Für den Teil, in dem ich eine echte Terminal-Sitzung zeigen wollte, war eine Bildschirmaufnahme das richtige Werkzeug, nicht dieses. Und das Ergebnis spiegelt nur die Eingabe: Aus schludrigen Notizen wird ein schludriges Video, was nebenbei ehrliches Feedback zu den Notizen selbst war.

Was sich geändert hat

Wir haben die Doku nicht ersetzt. Wir haben für die paar Themen, die neue Leute wirklich verinnerlichen sollten, kurze Videoversionen ergänzt, erzeugt aus den Unterlagen, die wir schon pflegen. Neue Kolleginnen sehen den Ablauf jetzt einmal während der Einarbeitung, statt ihm zum ersten Mal im Ernstfall zu begegnen, und die Videos bleiben aktuell, weil sie aus derselben Quelle neu erzeugt werden.

Wenn ihr Schulungsunterlagen habt und immer vorhattet, Video zu ergänzen, es aber nie getan habt, weil es ein separater Aufwand ist, dann passt das hier. Nehmt das eine Thema, das am häufigsten Rückfragen auslöst, erzeugt aus dem vorhandenen Dokument eine Version im kostenlosen Tarif und legt sie in die Einarbeitung. Bei uns war es das Onboarding zum Deployment, und die zwanzig Minuten haben sich gelohnt.

Our Tutorial Videos Rotted Every Release, So We Stopped Filming Them

douzatan — Sat, 01 Aug 2026 05:47:46 +0000

Every release used to break a video.

We maintain a developer tool, and the short explainer videos attached to it stayed accurate for about six weeks. Then a flag got renamed, a panel moved, the default changed, and the video was quietly wrong. Nobody volunteered to re-record it, because re-recording meant blocking an afternoon, setting up a mic, and doing five takes to get ninety seconds without stumbling over the word "idempotent." So the wrong video stayed up until a user pointed it out in an issue, and then it usually got deleted rather than remade.

The docs never had this problem. A doc changes in a pull request. Someone reviews the diff, it merges, and the site rebuilds. Video had no equivalent of that loop, so video rotted, and after the second round of rot we stopped making it. That is how a team ends up with docs that are current and a YouTube playlist that is a museum.

What eventually fixed it was not better recording discipline. It was removing the recording step entirely, so the video became something we regenerate from text like everything else we ship.

Why we wanted a presenter and not just a screencast

The obvious answer is a screencast with a voiceover. We had those. They are fine for "here is the sequence of clicks," and they are genuinely better than a talking head for anything where the user needs to see the actual interface respond.

They are worse for the conceptual half. When the video is explaining why a feature exists, what the mental model is, or which of two approaches you should pick, a cursor moving around a screen while a disembodied voice talks is hard to stay with. I notice it in my own viewing: I keep the tab open, I stop watching, I skim the transcript instead. A face delivering the explanation holds me longer. I do not have clean numbers from our own content to prove this, and I am suspicious of anyone who claims they do, but the pattern was consistent enough that we kept wanting the presenter format and kept failing to produce it.

The reason we failed was mundane. A talking head requires a specific human being to be available, on camera, on a schedule. On a small team, that human is also the person shipping the feature the video is about. Their time is the constraint, and video loses to shipping every single time. The format was not too hard for us. It was too dependent on a calendar.

Generating the presenter from the script instead

The change was using an AI talking head generator to produce the presenter, so the input is a script rather than a recording session.

The mechanics are dull, which is the point. You paste the script, pick a presenter from the built-in library, choose a voice, and it generates the talking-head video with lip sync. There is a setting for more natural expression so the delivery does not come out flat. You can also generate an avatar from a single photo if you want a consistent face that is specifically yours rather than one from the library, and you can put your own background behind it or drop in a brand kit so the clips in a series match. Output is an MP4 you download, plus a hosted link if you want to embed it.

The part that mattered for us: fixing a line means editing text and regenerating. Not booking a re-record. Not asking a teammate to sit down again for one sentence. That single property is what turned video from a project into a build step. When we renamed a flag last quarter, updating the video was a two-line diff in a script file and a regenerate, and it was done before the release notes were finished.

Scripts live in the repo now

Once video generation takes text as input, the script is source, so we treat it that way.

docs/
  videos/
    01-getting-started.script.md
    02-config-file.script.md
    03-ci-integration.script.md
    README.md          # voice, presenter, aspect ratio per series

Scripts get reviewed in a pull request like anything else. If a PR changes a CLI flag and there is a script mentioning that flag, the reviewer sees both in the same diff, which is the thing that never happened when video lived in a folder on someone's laptop. We do not have automated generation wired to CI, and I would not pretend otherwise: someone still opens the browser, pastes the updated script, and regenerates. But the expensive part is gone, and the cheap part is a five minute chore rather than an afternoon.

A few things we learned about writing these scripts, none of which are obvious the first time:

Write for the ear, not the eye. Sentences you would happily publish in a doc are often too long to listen to. Read the script out loud once before generating and cut anything you run out of breath on.

Do not read code aloud. A synthesized voice narrating --max-retries=3 is unpleasant, and it is unpleasant when a human does it too. Say what the flag does, show the code on screen, and let the two work together.

Say numbers the way people say them. Written "v2.4.0" gets voiced in ways you will not like. Spell it out phonetically in the script and let the doc keep the clean version.

The scripts also gave us something we did not plan for. Because our docs are translated, we can generate the same video in other languages from a translated script with the same presenter, which is a lot more approachable than asking someone to re-record a tutorial in a language they do not speak.

Where it is genuinely not good

This puts a synthetic face on screen, so being straight about it matters more than usual for a dev audience, which is not a crowd that responds well to being sold to.

It reads as generated. Not badly, but if you look at it with intent, you can tell it is not filmed. For routine explanatory content that is fine and nobody has complained. For anything where you are the point, a conference talk, a project announcement you want to feel personal, a video where a user is deciding whether to trust you as a maintainer, film yourself or do not make the video.

It does not show your interface. The presenter explains, it does not demonstrate. For the click-by-click sections we still capture the screen with our own recorder and upload that footage, then shrink the avatar into a corner so the interface has the frame. Anyone expecting the tool to record their screen for them is expecting the wrong tool.

The output is only as good as the script. Our first attempt was lifeless because we fed it a doc page verbatim, and a doc page is written to be scanned, not spoken. Rewriting it as something a person would actually say fixed it. The tool has no idea what your users are confused about unless the script says so.

And on likeness: only build an avatar from an image you have the right to use. If it is a teammate's face, that needs their explicit yes, and the yes needs to cover the videos you are actually going to make with it. Putting a colleague's face on a video they never agreed to is not a shortcut worth taking.

If you want to try this

Do not migrate a whole channel. Pick the one video you already know is out of date and have been avoiding for a month, write the script as a real script rather than a pasted doc page, and generate a couple of versions on a free tier. Watch them with someone who has not read the script.

If the presenter reads as a deliberate choice rather than an accident, keep it for that format. If it reads as off, you have lost an hour and learned something. For us the test case was the getting-started video, the one that broke on literally every release, and it has been current for three releases running, which it never managed when it depended on somebody being free to film.

How I Pick Which Coding Lessons to Record, After Wasting a Term on the Wrong Ones

douzatan — Wed, 29 Jul 2026 03:43:29 +0000

I teach web development, partly in a bootcamp and partly on a YouTube channel that started as lecture overflow. For my first full term of recording, I chose topics the way most instructors do: I taught what I thought was foundational, in syllabus order. Syllabus order and "what people actually get stuck on" order turned out to be almost unrelated, and my analytics said so, loudly.

Key takeaways
Pick tutorial topics from observed search demand, not from syllabus order or personal interest.
Collect the exact phrases learners type, typos included, then check which ones people actually search.
Chase the overlap: real search demand plus weak or dated coverage.
Keyword research decides what to make, not whether your teaching is any good. Those are separate problems.
The term I wasted on syllabus order
My carefully sequenced fundamentals playlist was a graveyard with two or three accidental hits. The hits confused me most, because I could not explain them, which meant I could not repeat them. A content library shaped by the syllabus mostly serves the syllabus.

The accidental hit that changed my process
I recorded a five-minute throwaway on a CORS error because a student hit it twice in one week. I almost did not post it. It has more views than my entire fundamentals playlist combined, and the comments are all one sentence: thank you, this was the only clear explanation I could find.

Step 1: collect the phrases learners actually type
Now I keep a running note of every question I see learners ask, in Discord servers, in subreddit threads, and under my own videos. I add the error messages and "how do I" moments from my own week. No filtering yet. The list runs 15 to 20 phrases, written the way people actually typed them, typos preserved. The typos are the real vocabulary.

Step 2: check the phrases against real search demand
Before I record anything, I spend twenty minutes running that list through a YouTube keyword research tool to see which phrasings people search around a topic and what already surfaces for them. This step deletes about two thirds of my list, which is the point.

The two gaps worth chasing
First, the vocabulary gap. I teach "asynchronous control flow." Nobody stuck at midnight searches that. They search "why is my await not waiting." I now keep a small glossary mapping my teaching terms to the searched phrasings, and I use the searched version in the title.

Second, the coverage gap. Some of the most-searched beginner errors are answered only by videos years old, using syntax two versions out of date. That is not competition. That is an opening, and it goes to the front of my queue.

One honest limit
This tells you what to make, not whether your explanation lands. I have posted well-researched topics with mediocre teaching and watched them underperform a rushed video on a hotter question. Selection gets you found. The teaching still has to be good, and no keyword tool fixes that half for you.

Try it before your next recording
If your channel has a graveyard and a couple of mystery hits, spend twenty minutes on demand before your next video. Worst case, you confirm your instinct. Best case, you stop making videos nobody was ever going to search for.