Skip to content
Skills Library
Programming · Tool integration

speak-local-dev-loop

/speak-local-dev-loop

Configure Speak local development with mocked tutors and audio testing. Use when setting up a development environment, configuring test workflows, or building language learning features locally. Trigger with phrases like "speak dev setup", "speak local development", "speak dev environment", "develop with speak".

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Configure Speak local development with mocked tutors and audio testing. Use when setting up a development environment, configuring test workflows, or building language learning features locally. Trigger with phrases like "speak dev setup", "speak local development", "speak dev environment", "develop with speak".

Triggers from the description

speak dev setupspeak local developmentspeak dev environmentdevelop with speak
Original author description

Configure Speak local development with mocked tutors and audio testing. Use when setting up a development environment, configuring test workflows, or building language learning features locally. Trigger with phrases like "speak dev setup", "speak local development", "speak dev environment", "develop with speak".

How it works

  1. Overview
  2. Prerequisites
  3. Instructions
  4. Output
  5. Error Handling
  6. Resources
  7. Next Steps
  8. Examples
Original SKILL.md headings · 151 lines, 550 words
SKILL.md preview
---
name: speak-local-dev-loop
description: 'Configure Speak local development with mocked tutors and audio testing.

  Use when setting up a development environment, configuring test workflows,

  or building language learning features locally.

  Trigger with phrases like "speak dev setup", "speak local development",

  "speak dev environment", "develop with speak".

  '
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(pnpm:*), Grep
version: 1.14.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- speak
- testing
- workflow
compatibility: Designed for Claude Code
---
# Speak Local Dev Loop

## Overview

Set up a fast local development workflow for Speak language learning integrations. Includes mock tutor responses for offline development, audio test fixtures, and a debug mode for scoring analysis.

## Prerequisites

- Completed `speak-install-auth` setup
- Node.js 18+ with npm/pnpm
- ffmpeg installed (for audio conversion)

## Instructions

### Step 1: Project Structure

```
speak-app/
  src/
    speak/client.ts       # Speak API client
    speak/tutor.ts        # AI tutor conversation manager
    speak/pronunciation.ts # Pronunciation assessment
    speak/audio.ts        # Audio recording and preprocessing
  tests/
    mocks/                # Mock responses for offline dev
    fixtures/             # Sample audio files for testing
    unit/                 # Unit tests with mocked API
    integration/          # Integration tests (needs API key)
  .env.development        # Dev credentials
  .env.test              # Test credentials (mock mode)
```

### Step 2: Mock Tutor for Offline Development

```typescript
// tests/mocks/mock-speak-client.ts
export class MockSpeakClient {
  async startConversation(config: any) {
    return {
      id: 'mock-session-123',
      firstPrompt: {
        text: 'Hola! Bienvenido. Como te llamas?',
        audioUrl: null,
      },
    };
  }

  async sendTurn(sessionId: string, input: any) {
    return {
      tutorText: 'Muy bien! Tu pronunciacion es buena.',
      pronunciationScore: 85,
      corrections: [],
      vocabularyNotes: ['llamo = I call myself'],
    };
  }

  async assessPronunciation(config: any) {
    return {
      score: 82,
      words: [
        { text: 'Hola', score: 95, phonemes: [] },
        { text: 'como', score: 78, phonemes: [
          { symbol: 'o', score: 65, suggestion: 'Round lips more' }
        ]},
      ],
    };
  }
}
```

### Step 3: Audio Test Fixtures

```bash
# Generate test audio files using text-to-speech
# macOS:
say -v "Paulina" "Hola, como estas" -o tests/fixtures/hola-es.wav
# Linux:
espeak -v es "Hola, como estas" -w tests/fixtures/hola-es.wav

# Convert to required format
ffmpeg -i tests/fixtures/hola-es.wav -ar 16000 -ac 1 tests/fixtures/hola-es-16k.wav
```

### Step 4: Development Scripts

```json
{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "dev:mock": "SPEAK_MOCK_MODE=true tsx watch src/index.ts",
    "test": "vitest run",
    "test:watch": "vitest",
    "lesson:test": "tsx src/test-lesson.ts"
  }
}
```

### Step 5: Debug Mode

```typescript
// Enable detailed scoring output
const DEBUG = process.env.SPEAK_DEBUG === 'true';

function logAssessment(result: PronunciationResult) {
  if (!DEBUG) return;
  console.log('=== Pronunciation Debug ===');
  for (const word of result.words) {
    const flag = word.score < 70 ? 'WEAK' : 'OK';
    console.log(`  [${flag}] "${word.text}": ${word.score}/100`);
    for (const p of word.phonemes || []) {
      if (p.score < 70) {
        console.log(`    phoneme "${p.symbol}": ${p.score} - ${p.suggestion}`);
      }
    }
  }
}
```

## Output

- Project structure with client, tests, and mocks
- Mock tutor client for offline development
- Audio test fixtures generated with TTS
- Debug mode for pronunciation analysis
- Development scripts for fast iteration

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| ffmpeg not found | Not installed | Install via `brew install ffmpeg` or `apt install ffmpeg` |
| Mock mode not activating | Env var not set | Check `SPEAK_MOCK_MODE=true` |
| Audio file too large | Long recording | Trim to 30 seconds max for testing |
| Test timeout | Slow API response | Use mock mode for unit tests |

## Resources

- [Vitest](https://vitest.dev/)
- [ffmpeg](https://ffmpeg.org/documentation.html)
- [Web Speech API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API)

## Next Steps

See `speak-sdk-patterns` for production-ready code patterns.

## Examples

**Mock-first development**: Run `npm run dev:mock` to iterate on UI and conversation flow without API calls. Switch to real API for integration testing.

**Audio quality testing**: Record samples at different quality levels and compare pronunciation scores to calibrate your recording pipeline.
Files in this package (2)
  • SKILL.md 5 KB
  • references/implementation-guide.md 6 KB

Versions

The database has no other skills named speak-local-dev-loop.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 75900f9f87c3 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100linear-local-dev-loop
    Set up local Linear development environment and testing workflow. Use when configuring local development, testing integrations, or setting up a development workflow with Linear. Trigger with phrases like "linear local development", "linear dev setup", "test linear locally",…
  • 100exa-local-dev-loop
    Configure Exa local development with hot reload and testing. Use when setting up a development environment, configuring test workflows, or establishing a fast iteration cycle with Exa. Trigger with phrases like "exa dev setup", "exa local development", "exa dev environment", "develop with exa".
  • 100apollo-local-dev-loop
    Configure Apollo.io local development workflow. Use when setting up development environment, testing API calls locally, or establishing team development practices. Trigger with phrases like "apollo local dev", "apollo development setup", "apollo dev environment", "apollo testing locally".
  • 100hex-local-dev-loop
    Configure Hex local development with hot reload and testing. Use when setting up a development environment, configuring test workflows, or establishing a fast iteration cycle with Hex. Trigger with phrases like "hex dev setup", "hex local development", "hex dev environment", "develop with hex".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.