agentleFS
DingyangLyuDingyangLyu/MatClaw/.claude/skills/add-voice-transcription/SKILL.md

add-voice-transcription

Skill98 starsChanged 8 months agoApache-2.0View on GitHub

Add voice message transcription to MatClaw using OpenAI's Whisper API. Automatically transcribes WhatsApp voice notes so the agent can read and respond to them.

  • Reads credentials

4 other projects use a version of this, 2 of them edited.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. 0 are common, 9 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 9

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read .matclaw/state.yaml. If voice-transcription is in applied_skills, skip to Phase 3 (Configure).

    line 14
  2. Very specific:

    Use AskUserQuestion to collect information:

    line 18
  3. Distinctive:

    If yes, collect it now. If no, direct them to create one at https://platform.openai.com/api-keys.

    line 22
  4. Distinctive:

    Run the skills engine to apply this skill's code package.

    line 26
  5. Very specific:

    If .matclaw/ directory doesn't exist yet:

    line 30
  6. Distinctive:

    If the apply reports merge conflicts, read the intent files:

    line 50
  7. Distinctive:

    All tests must pass (including the 3 new voice transcription tests) and build must be clean before proceeding.

    line 61
  8. Distinctive:

    If the user doesn't have an API key:

    line 67
  9. Distinctive:

    Wait for the user to provide the key.

    line 78
  10. Very specific:

    Check OPENAI_API_KEY is set in .env AND synced to data/env/env

    line 128
  11. Very specific:

    Verify key works: curl -s https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY" | head -c 200

    line 129
  12. Distinctive:

    Check OpenAI billing — Whisper requires a funded account

    line 130
  13. Distinctive:

    Check logs for the specific error.

    line 134
  14. Distinctive:

    Verify the chat is registered and the agent is running.

    line 141

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Add Voice Transcription

This skill adds automatic voice message transcription to MatClaw's WhatsApp channel using OpenAI's Whisper API. When a voice note arrives, it is downloaded, transcribed, and delivered to the agent as [Voice: <transcript>].

Phase 1: Pre-flight

Check if already applied

Read .matclaw/state.yaml. If voice-transcription is in applied_skills, skip to Phase 3 (Configure). The code changes are already in place.

Ask the user

Use AskUserQuestion to collect information:

AskUserQuestion: Do you have an OpenAI API key for Whisper transcription?

If yes, collect it now. If no, direct them to create one at https://platform.openai.com/api-keys.

Phase 2: Apply Code Changes

Run the skills engine to apply this skill's code package.

Initialize skills system (if needed)

If .matclaw/ directory doesn't exist yet:

npx tsx scripts/apply-skill.ts --init

Apply the skill

npx tsx scripts/apply-skill.ts .claude/skills/add-voice-transcription

This deterministically:

  • Adds src/transcription.ts (voice transcription module using OpenAI Whisper)
  • Three-way merges voice handling into src/channels/whatsapp.ts (isVoiceMessage check, transcribeAudioMessage call)
  • Three-way merges transcription tests into src/channels/whatsapp.test.ts (mock + 3 test cases)
  • Installs the openai npm dependency
  • Updates .env.example with OPENAI_API_KEY
  • Records the application in .matclaw/state.yaml

If the apply reports merge conflicts, read the intent files:

  • modify/src/channels/whatsapp.ts.intent.md — what changed and invariants for whatsapp.ts
  • modify/src/channels/whatsapp.test.ts.intent.md — what changed for whatsapp.test.ts

Validate code changes

npm test
npm run build

All tests must pass (including the 3 new voice transcription tests) and build must be clean before proceeding.

Phase 3: Configure

Get OpenAI API key (if needed)

If the user doesn't have an API key:

I need you to create an OpenAI API key:

  1. Go to https://platform.openai.com/api-keys
  2. Click "Create new secret key"
  3. Give it a name (e.g., "MatClaw Transcription")
  4. Copy the key (starts with sk-)

Cost: $0.006 per minute of audio ($0.003 per typical 30-second voice note)

Wait for the user to provide the key.

Add to environment

Add to .env:

OPENAI_API_KEY=<their-key>

Sync to container environment:

mkdir -p data/env && cp .env data/env/env

The container reads environment from data/env/env, not .env directly.

Build and restart

npm run build
launchctl kickstart -k gui/$(id -u)/com.matclaw  # macOS
# Linux: systemctl --user restart matclaw

Phase 4: Verify

Test with a voice note

Tell the user:

Send a voice note in any registered WhatsApp chat. The agent should receive it as [Voice: <transcript>] and respond to its content.

Check logs if needed

tail -f logs/matclaw.log | grep -i voice

Look for:

  • Transcribed voice message — successful transcription with character count
  • OPENAI_API_KEY not set — key missing from .env
  • OpenAI transcription failed — API error (check key validity, billing)
  • Failed to download audio message — media download issue

Troubleshooting

Voice notes show "[Voice Message - transcription unavailable]"

  1. Check OPENAI_API_KEY is set in .env AND synced to data/env/env
  2. Verify key works: curl -s https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY" | head -c 200
  3. Check OpenAI billing — Whisper requires a funded account

Voice notes show "[Voice Message - transcription failed]"

Check logs for the specific error. Common causes:

Agent doesn't respond to voice notes

Verify the chat is registered and the agent is running. Voice transcription only runs for registered groups.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.