audio-transcriber

Transform audio recordings into professional Markdown documentation with intelligent summaries using LLM integration

Quality

23%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

—

The risk profile of this skill

Fix and improve this skill with Tessl

tessl review fix ./skills/audio-transcriber/SKILL.md

Quality

Content

14%Scale 1-3

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill is excessively verbose, poorly organized, and incomplete in critical areas. The core transcription step is missing from the workflow, steps are numbered inconsistently (skipping 2 and 4), and key functions are undefined placeholders. The content mixes languages, includes unnecessary terminal UI mockups, and would benefit enormously from being split into multiple files with a concise overview in SKILL.md.

Suggestions

Add the missing Step 2 (actual transcription execution) and Step 4, and renumber all steps sequentially to create a complete, coherent workflow

Reduce content by 70%+: remove installation flows, terminal UI mockups, and example outputs; move them to separate reference files (e.g., INSTALL.md, EXAMPLES.md, TEMPLATES.md)

Replace placeholder functions (cluster_by_topic, call_ai_model, extract_action_items) with actual executable implementations or remove them entirely

Add explicit validation checkpoints after transcription (verify output file exists, check word count > 0, validate markdown structure) especially for the batch processing scenario

Dimension	Reasoning	Score
Conciseness	Extremely verbose at ~400+ lines. Explains obvious concepts (what audio formats are, how file validation works), includes extensive UI mockups for terminal output, mixes languages (Portuguese/English), and repeats information. Much of this content (installation flows, interactive prompts, progress bars) is unnecessary for Claude to understand the task.	1 / 3
Actionability	Contains concrete bash and Python code snippets, but many are pseudocode or incomplete (e.g., `cluster_by_topic()`, `extract_action_items()`, `call_ai_model()` are undefined placeholders). The actual transcription step (Step 2) appears to be missing entirely—it jumps from Step 1 (validation) to Step 3 (generate output). Key implementation details are absent.	2 / 3
Workflow Clarity	The workflow is disorganized and incomplete. Steps are numbered inconsistently (0, 1, 3, 5—missing Steps 2 and 4). The core transcription step is absent. Scenarios A appears without a Scenario B introduction. There are no validation checkpoints for the actual transcription output, and batch processing is shown in examples but has no workflow steps or error handling/validation.	1 / 3
Progressive Disclosure	Monolithic wall of text with no references to external files despite the content being far too long for a single SKILL.md. Installation instructions, output templates, LLM processing details, and examples could all be split into separate files. No bundle files are provided despite references to `scripts/install-requirements.sh`.	1 / 3
	Total	5 / 12 Passed

Description

32%Scale 1-3

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description identifies a clear domain (audio-to-documentation) but suffers from vague action verbs ('transform'), buzzword-like phrasing ('intelligent summaries', 'LLM integration'), and a complete lack of explicit trigger guidance. It would benefit significantly from concrete actions, natural user keywords, and a 'Use when...' clause.

Suggestions

Add a 'Use when...' clause with trigger terms like 'transcribe audio', 'meeting recording', 'voice memo', 'audio file', '.mp3', '.wav'

Replace vague terms like 'transform' and 'intelligent summaries' with specific actions such as 'transcribe speech to text', 'generate meeting notes', 'create section summaries', 'extract action items'

Remove marketing-style language like 'professional' and 'intelligent' and 'LLM integration' in favor of concrete capability descriptions

Dimension	Reasoning	Score
Specificity	It names the domain (audio recordings) and some actions (transform, summaries), but lacks specific concrete actions like 'transcribe speech', 'generate timestamps', 'identify speakers', or 'format transcripts'. 'Transform' and 'intelligent summaries' are somewhat vague.	2 / 3
Completeness	It describes what the skill does (transform audio to Markdown with summaries) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and the 'what' portion is also somewhat vague, warranting a score of 1.	1 / 3
Trigger Term Quality	Includes 'audio recordings' and 'Markdown documentation' which are relevant, but misses common user terms like 'transcribe', 'transcription', 'meeting notes', 'voice memo', '.mp3', '.wav', 'speech-to-text', or 'recording'. Users are more likely to say 'transcribe this audio' than 'transform audio recordings.'	2 / 3
Distinctiveness Conflict Risk	The combination of audio + Markdown + LLM summaries is somewhat distinctive, but 'professional Markdown documentation' could overlap with general documentation skills, and 'LLM integration' is generic. The audio focus helps but isn't sharply delineated.	2 / 3
	Total	7 / 12 Passed

Validation

81%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 9 / 11 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (560 lines); consider splitting into references/ and linking	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	9 / 11 Passed

Repository: popey/claude-code-skills
Path: skills/audio-transcriber/SKILL.md
Commit: a5a6601

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.