Skip to main content
skill CX Codex

voice-to-report — Claude Code skill: what it does, how to install

The voice-to-report skill for Claude Code converts voice recordings into structured construction reports. It activates when field workers need to quickly log site data, such as daily updates or safety observations.

MIT 115 installs ★ 434 updated 2026-10-19

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --skill voice-to-report -a claude-code
Open on GitHub

What voice-to-report does

The voice-to-report skill automates the creation of construction reports from spoken input. It uses the Whisper API for speech-to-text transcription, then GPT-4o to structure the information according to predefined schemas. The skill supports daily reports, safety observations, and progress updates.

To function, the skill requires python3 to be installed and an OPENAI_API_KEY environment variable with an OpenAI API key. These are essential for processing audio and generating reports in formats suitable for databases or PDF documents. For instance, an n8n workflow can integrate it to receive voice messages via Telegram, save data to PostgreSQL, and generate PDFs through an external service.

The skill can automatically detect the language of a recording and translate it to English if needed, preserving construction terminology. This feature benefits field workers who find it easier to speak their observations than to type them on a mobile device.

What it helps with

  • Generating quick site reports
  • Transcribing voice notes into text
  • Structuring data for daily construction logs
  • Creating safety observation and progress reports
  • Processing multilingual voice recordings

Example prompts for the agent

  • "Convert this voice recording into a daily report"
  • "Create a safety report from safety_note.mp3"
  • "Generate a progress update from the voice message"

How to install voice-to-report

1Skills CLI (Vercel)

npx skills add datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --skill voice-to-report -a claude-code

2Manually: put the files in place

~/.claude/skills/voice-to-report/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/voice-to-report/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about voice-to-report

How to install voice-to-report in Claude Code?

To install, use the command npx skills add datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --skill voice-to-report -a claude-code. The skill will then be available at ~/.claude/skills/voice-to-report/SKILL.md.

What does the voice-to-report skill do?

It transforms voice recordings from field workers into structured construction reports. The skill transcribes speech and formats it into data for daily logs, safety observations, or progress updates.

What is needed for voice-to-report to work?

The skill requires python3 to be installed and an OPENAI_API_KEY environment variable containing an OpenAI API key. These components are necessary for transcription and data processing.

Source text

SKILL.md · MIT
---
name: "voice-to-report"
description: "Convert voice recordings to structured construction reports. Field workers speak, AI transcribes and formats. Supports daily reports, safety observations, progress updates."
homepage: "https://datadrivenconstruction.io"
metadata: {"openclaw": {"emoji": "📱", "os": ["darwin", "linux", "win32"], "homepage": "https://datadrivenconstruction.io", "requires": {"bins": ["python3"], "env": ["OPENAI_API_KEY"]}, "primaryEnv": "OPENAI_API_KEY"}}
---
# Voice to Report

## Overview

Field workers prefer talking over typing. This skill converts voice recordings into structured construction reports using speech-to-text and LLM processing.

## Why Voice?

| Typing | Voice |
|--------|-------|
| Slow on mobile | 3x faster |
| Requires attention | Hands-free |
| Limited in cold/rain | Works anywhere |
| Formal language | Natural expression |
| Short messages | Detailed descriptions |

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                    VOICE TO REPORT PIPELINE                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  🎤 Voice      →    📝 Transcribe    →    🤖 Structure    →    📊 Report │
│  Recording         Whisper API           GPT-4o               Formatted  │
│                                                                  │
│  "We finished      "We finished         {                    Daily Report │
│   the foundation    the foundation       "activity":         ──────────── │
│   pour today,       pour today,          "foundation",       Foundation   │
│   about 500         about 500            "quantity": 500,    pour: 500m³  │
│   cubic meters"     cubic meters"        "unit": "m³"        Complete ✓   │
│                                          }                               │
└─────────────────────────────────────────────────────────────────┘
```

## Quick Start

```python
from openai import OpenAI
import json

client = OpenAI()

def voice_to_report(audio_path: str, report_type: str = "daily") -> dict:
    """Convert voice recording to structured report"""

    # Step 1: Transcribe audio
    with open(audio_path, "rb") as audio_file:
        transcript = client.audio.transcriptions.create(
            model="whisper-1",
            file=audio_file,
            language="en"
        )

    # Step 2: Structure with LLM
    schema = get_report_schema(report_type)

    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {
                "role": "system",
                "content": f"""You are a construction report assistant.
                Convert the voice transcript into a structured report.
                Extract all relevant information and format as JSON.

                Report type: {report_type}
                Schema: {json.dumps(schema, indent=2)}

                Rules:
                - Extract quantities with units
                - Identify activities and locations
                - Note any issues or concerns
                - Capture weather if mentioned
                - List workers/trades if mentioned
                """
            },
            {
                "role": "user",
                "content": f"Transcript:\n{transcript.text}"
            }
        ],
        response_format={"type": "json_object"}
    )

    return {
        "transcript": transcript.text,
        "structured_report": json.loads(response.choices[0].message.content)
    }
```

## Report Schemas

### Daily Report Schema

```python
daily_report_schema = {
    "date": "YYYY-MM-DD",
    "project": "string",
    "weather": {
        "conditions": "string",
        "temperature": "number",
        "impact": "none|minor|major"
    },
    "workforce": [
        {
            "trade": "string",
            "count": "number",
            "hours": "number"
        }
    ],
    "activities": [
        {
            "description": "string",
            "location": "string",
            "quantity": "number",
            "unit": "string",
            "status": "in_progress|completed|delayed"
        }
    ],
    "equipment": [
        {
            "type": "string",
            "hours": "number"
        }
    ],
    "issues": [
        {
            "description": "string",
            "severity": "low|medium|high",
            "action_taken": "string"
        }
    ],
    "notes": "string"
}
```

### Safety Observation Schema

```python
safety_schema = {
    "date": "YYYY-MM-DD",
    "time": "HH:MM",
    "location": "string",
    "observer": "string",
    "observation_type": "positive|concern|incident",
    "description": "string",
    "people_involved": ["list of names/roles"],
    "immediate_action": "string",
    "follow_up_required": "boolean",
    "photos_attached": "boolean"
}
```

### Progress Update Schema

```python
progress_schema = {
    "date": "YYYY-MM-DD",
    "area": "string",
    "activity": "string",
    "planned_quantity": "number",
    "actual_quantity": "number",
    "unit": "string",
    "percent_complete": "number",
    "on_schedule": "boolean",
    "variance_reason": "string or null",
    "next_steps": "string"
}
```

## n8n Workflow

```json
{
  "workflow": "Voice to Report",
  "nodes": [
    {
      "name": "Telegram Trigger",
      "type": "Telegram",
      "event": "voice_message"
    },
    {
      "name": "Download Voice",
      "type": "Telegram",
      "action": "getFile"
    },
    {
      "name": "Transcribe",
      "type": "OpenAI",
      "operation": "transcribe",
      "model": "whisper-1"
    },
    {
      "name": "Detect Report Type",
      "type": "OpenAI",
      "prompt": "Classify: daily_report, safety, progress, issue"
    },
    {
      "name": "Structure Report",
      "type": "OpenAI",
      "operation": "chat",
      "model": "gpt-4o"
    },
    {
      "name": "Save to Database",
      "type": "PostgreSQL"
    },
    {
      "name": "Confirm to User",
      "type": "Telegram",
      "action": "sendMessage"
    },
    {
      "name": "Generate PDF",
      "type": "HTTP Request",
      "url": "pdf-service/generate"
    }
  ]
}
```

## Multi-Language Support

```python
def transcribe_multilingual(audio_path: str) -> dict:
    """Transcribe in any language, output in English"""

    with open(audio_path, "rb") as audio_file:
        # Detect language automatically
        transcript = client.audio.transcriptions.create(
            model="whisper-1",
            file=audio_file
            # language parameter omitted for auto-detection
        )

    # Translate to English if needed
    if not is_english(transcript.text):
        translation = client.chat.completions.create(
            model="gpt-4o",
            messages=[
                {"role": "system", "content": "Translate to English, preserve construction terminology."},
                {"role": "user", "content": transcript.text}
            ]
        )
        english_text = translation.choices[0].message.content
    else:
        english_text = transcript.text

    return {
        "original": transcript.text,
        "english": english_text
    }
```

## Mobile App Integration

```python
# Example: Flutter/React Native integration

# Send voice to API
async def upload_voice_report(audio_bytes, project_id):
    response = await api.post(
        "/voice-report",
        files={"audio": audio_bytes},
        data={
            "project_id": project_id,
            "report_type": "daily"
        }
    )
    return response.json()

# Response includes:
# - transcript
# - structured_report
# - report_id
# - pdf_url (if generated)
```

## Cost Optimization

```python
# Use local Whisper for high volume
import whisper

model = whisper.load_model("base")  # or "small", "medium", "large"

def transcribe_local(audio_path: str) -> str:
    """Transcribe locally to save API costs"""
    result = model.transcribe(audio_path)
    return result["text"]

# Cost comparison (per hour of audio):
# - OpenAI Whisper API: $0.36
# - Local Whisper (base): $0 (compute only)
# - Local Whisper (large): $0 (compute only, slower)
```

## Requirements

```bash
pip install openai whisper python-telegram-bot
```

## Resources

- OpenAI Whisper: https://platform.openai.com/docs/guides/speech-to-text
- Local Whisper: https://github.com/openai/whisper
- n8n Voice Processing: https://docs.n8n.io/integrations/

© datadrivenconstruction · MIT · datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction

Similar skills

All skills for AI and ML →

From the same set156

The whole set →
data-profiler data-profiler — a skill for Claude Code that inspects construction datasets. It scans tables for missing fields, duplicates, cost outliers, and industry-specific identifiers prior to ETL runs. CX Codex +1 115installs data-anomaly-detector The data-anomaly-detector Claude Code skill detects unusual values in construction data with statistical and ML-based methods. It flags cost outliers, schedule shifts, and productivity spikes. CX Codex +1 115installs productivity-analyzer productivity-analyzer — a skill for Claude Code analyzes labor output rates using jobsite progress logs. Compares planned against actual progress and detects efficiency trends. CX Codex +1 115installs duration-prediction The duration-prediction Claude Code skill estimates construction project durations with k-NN and regression, using records from past projects. It runs when an agent is asked to forecast a new project's timeline from comparable work. CX Codex +1 115installs progress-monitoring-cv The progress-monitoring-cv skill reads site photos and drone imagery to estimate construction progress, flag safety concerns, and compare built work with BIM plans. CX Codex +1 115installs cwicr-data-loader cwicr-data-loader is a Claude Code skill for loading the DDC CWICR database from Parquet, Excel, CSV, and Qdrant. It provides automatic schema detection and type validation. CX Codex +1 115installs open-data-integrator open-data-integrator connects open construction datasets to your coding agent: material cost indices, labor benchmarks, and weather records. CX Codex +1 115installs csv-handler The csv-handler skill detects CSV encodings and delimiters, cleans tables, and can combine or split files. It’s aimed at exports from construction software. CX Codex +1 115installs

Project sponsors

Companies that keep this analytics open