How to use the ReadIt Voice Reader agent skill

What an agent skill is and what ReadIt makes the agent do

An agent skill is a folder of instructions and tools that an AI agent loads when a request matches the skill's description. ReadIt is one such skill. Once it is installed and set up, asking the agent to read something aloud makes it turn the content into a spoken script, send that script to the Fish Audio text-to-speech service, and play the audio on your Mac while the rest of the audio generates.

While a read is running you can pause, resume, check status, or stop it with simple commands. The read is one continuous piece of audio, not a summary: the skill is meant to keep the original words and order.

• Reads an article, a file, pasted text, or the agent's latest substantive write-up
• Starts playback within seconds, regardless of length
• Supports stop, pause, resume and status while reading
• Is silent in headless or scheduled contexts by design

Install the ReadIt skill from the download ZIP

Download the ReadIt ZIP from this page and unzip it. Then place the ReadIt folder in one of two locations: your personal skills folder at ~/.claude/skills/, or a project's .claude/skills/ folder if you want the skill only for that project.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/
• Claude apps: Settings → Capabilities → Skills, then upload

Set up Fish Audio, your API key and a voice

ReadIt needs a Fish Audio account and an API key stored as FISH_API_KEY in your environment file. The key is never printed or placed in a URL. There is no local fallback voice, so Fish Audio is required.

Voices come from your LifeOS configuration file, LIFEOS_CONFIG.toml, under your config root. ReadIt uses the [da.voices.reader] profile when it has a fish_reference_id, otherwise [da.voices.main]. The file must already contain name under [principal] and [da], and a timezone under [principal], or the config will not load. Full steps are in the skill's Setup.md file.

• Runtime: Bun must be installed
• Platform: macOS, because playback uses the built-in afplay tool
• Secret: FISH_API_KEY in your env file
• Voice: a [da.voices.*] profile with fish_reference_id in LIFEOS_CONFIG.toml
• Optional: FISH_PRINCIPAL_VOICE_ID for the --voice principal option
• Optional pronunciations: LIFEOS/USER/PRINCIPAL/PRONUNCIATIONS.json

Trigger ReadIt with natural requests

You do not need a special command. Phrases such as "read it to me", "read this to me", "read that aloud", "say this out loud", "listen to this", "read the article", or "read your write-up" activate the read. Short forms like "ri" or "/ri" also work. For a URL or file, include it in the request.

For control, say "stop reading", "pause the read" or "resume the read". Asking where you are in the read returns status.

• "read it to me" after the agent writes something
• "/ri https://example.com/some-article" for a web page
• "read this to me" with a pasted passage
• "pause the read", "resume the read", "stop reading"

Read a file or pasted text from the command line

The skill exposes a small tool contract. The agent normally calls it for you, but you can see the forms it uses. Reading a file takes a path and an optional title and voice profile. Reading short text takes the text directly. Control commands take no arguments.

• Optional --title sets the title shown in the reply
• Optional --voice picks any [da.voices.<name>] profile that has a fish_reference_id

Know the limits and safety notes

ReadIt runs scripts and uses the network. Your text and voice clone are processed by Fish Audio, so do not use it for content you do not want sent to a third-party service. A new read stops the one already running, because there is no queue. Chunks are capped at 2,400 characters and split at paragraph or sentence breaks.

Raw markdown is not a good script. The skill strips markup as a backstop, but tables read as comma lists, headers become fragments, and acronyms may be spelled out letter by letter. Ask the agent to write a spoken version for articles with a lot of structure.

• Network: text is sent to Fish Audio
• Scripts: the skill runs Bun scripts on your machine
• Headless channels and scheduled jobs never speak
• Playback is not available on Linux or Windows

Tips for better reads

Set pace with fish_speed in your voice profile, between 0.5 and 2.0. Unset means 1.0. Drama 3 tags such as [sigh] and <emphasis> pass through to the voice, so you can use them in a script. Add pronunciations for names and terms in PRONUNCIATIONS.json so they are said correctly.

• Set fish_speed between 0.5 and 2.0 for pacing
• Add names and terms to PRONUNCIATIONS.json
• Ask for a spoken script first when the source is a dense page