Build a Safe Text-to-Speech Skill

Release mode Alpha

Level
Builder
Format
individual or pair. A partner may be planner, reviewer, or listener without receiving the credential.

Build a modest command-line text-to-speech skill with a coding agent as collaborator—not as an unreviewed autopilot. The goal is a tool that takes a deliberate voice choice, one text source, and an explicit output path, while refusing unsafe or ambiguous requests.

Plan before code, protect the key, prove the failure paths, then make one small audio file

What you will make

Build a modest command-line text-to-speech skill with a coding agent as collaborator—not as an unreviewed autopilot. The goal is a tool that takes a deliberate voice choice, one text source, and an explicit output path, while refusing unsafe or ambiguous requests.

By the end, you can plan a tool before coding, create a local secret boundary, test expected failures, run one short live synthesis, listen to the result, and explain what would need human review before a team adopts it.

Lab materials

Use during the lab

Go deeper

Before you start

Level and format: Builder; individual or pair. A partner may be planner, reviewer, or listener without receiving the credential.

You need: a local project folder, a coding agent such as Codex or Claude Code, Node.js or another runtime you can explain, headphones or speakers, the planning worksheet, and the secrets checklist. The live finish also needs your own Speechify account and API key, a low spending limit or alert, and a current provider documentation check. Do not share an account or key with another learner.

The core idea

A useful skill is a small agreement between a person and a tool. The agreement includes what the command accepts, what it refuses, where files go, what it costs, which information is allowed to reach a provider, and who decides whether the result is usable.

An API key is not just a configuration detail. It is authority to spend against an account. It belongs in a local or managed secret boundary, not in prompts, code, audio metadata, browser files, screenshots, or a Git repository.

Build and test the smallest safe voiceover skill

Complete the activity here. Open the optional Lab Notebook beside this page when you want a place to record your work.

  1. Plan before the coding agent changes files

    Complete the skill planning worksheet. Choose a narrow goal such as: “Create a 10–20 second voiceover from an approved voice and an original script.”

    Ask your coding agent to review the plan, identify missing assumptions, and propose tests. Do not ask it to synthesize audio or create files yet. It should be able to restate:

    • the command contract;
    • the provider boundary;
    • the one allowed text source;
    • the output-path and overwrite rule;
    • the credential boundary;
    • the spend boundary; and
    • the failure cases that must be tested before a live request.

    Revise the worksheet until you can approve the plan yourself. You may use the tool-neutral prompt recipes, but adapt only the project details—not the safety requirements.

  2. Create a local project and secret boundary

    Create a new local learner project. Add a value-free .env.example containing only:

    SPEECHIFY_API_KEY=

    Create your local .env separately and place your own key there. Verify that .env and .env.* are ignored while .env.example remains visible to Git. Do not show the .env file to the coding agent, paste its value into a conversation, or include it in a screenshot.

    Read the secrets handling checklist before continuing. If you cannot confirm the ignore rule and spending guardrail, stop at the dry-run portion of this lab.

  3. Build the smallest acceptable command

    Ask the coding agent to implement the reviewed plan. A useful command shape is:

    voiceover --voice <approved-slug> (--text <text> | --text-file <path>) --out <path>.mp3 [--force] [--dry-run]

    The skill may use a provider-specific adapter internally, but the caller should not need to know provider request details. Keep a local approved-voice record with a stable slug and the provider voice identifier. Do not select by a changing catalog position or ask the tool to choose a voice for you.

    Before a live request, make the command pass a dry run and make it fail correctly when you:

    • omit --out;
    • omit both text inputs or provide both;
    • name an unknown or unapproved voice;
    • run without a credential; and
    • target an existing output without --force.

    Record outcomes, not secrets, in your worksheet.

  4. Run one small live acceptance test

    Confirm your provider account has a low spending limit or alert. Use an original test of no more than two short sentences. Run the approved command once with an explicit output path.

    Listen from beginning to end. Confirm that the file exists, has positive duration, and is understandable. Record the selected voice slug, provider/model label, character count or billable count if returned, output filename, duration, and human listening result. Do not record the key or the full provider request headers.

    If the request fails, preserve the error category and remove any sensitive output before asking an agent for help. If you suspect the key appeared anywhere outside .env, revoke or rotate it before continuing.

  5. Use the skill for a practical voiceover

    Choose an approved voice deliberately and generate a short, low-risk voiceover from your own script file. Keep the command recipe and a one-paragraph human review note:

    • Why did this voice fit the intended audience or persona?
    • Could a listener understand it without the transcript?
    • What should change before this is used publicly?

    Audio generation is not editorial approval. Keep a person responsible for the script, voice fit, rights, and final release.

  6. Draft the human voice-audition website brief

    Do not add synthesis to a browser. Instead, write a short static-site brief that uses pre-generated clips and a shared set of scripts. It must include audio controls, visible voice metadata, ratings, notes, approval choices, and Markdown/JSON decision export.

    Review the existing Voice Auditions project as a worked reference. Your brief should state that only static HTML, CSS, JavaScript, registry data, and approved audio may be published. Provider clients, keys, and browser-side generation are excluded.

  7. Capture voice cloning as an idea, not an implementation

    Write a five-question idea note:

    1. Whose voice is involved, and what specific use has that person agreed to?
    2. How will listeners know when a cloned voice is used?
    3. Who can create, use, revoke, or delete the clone?
    4. What impersonation, retention, rights, or provider-term risks remain?
    5. What independent review is required before any pilot?

    Do not submit a voice sample, create a clone, or select a vendor for this step.

Check your result

  • Compare your record with the source and the stated task. Name what the result supports, what remains uncertain, and what must be checked by a person or authoritative source before anyone acts.

  • A polished result is not proof that it is accurate, complete, safe, or appropriate. Keep unresolved questions visible and verify consequential claims outside the tool.

You are done when

What did the plan prevent that an “just make it work” prompt might have missed? Which test failure taught you the most? What responsibility remained human even after the MP3 existed?

Done means you have a reviewed plan, a local skill that passes its dry-run and negative tests, an ignored local .env and value-free .env.example, one small tested MP3 from your own account, a secret-free test record, a human listening note, a static audition-site brief, and a voice-cloning idea note with no cloning action.

Try another version

These are optional extensions, not additional completion requirements.

Learner Map

Tracks

Modules

Help us improve this Activity

Tell us what helped, what slowed you down, or what you needed but could not find.

🎓 Give learner feedback