audio-transcriber

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

Quality

35%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

17%Scale 1-5

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

This skill is severely bloated and poorly organized. It explains concepts Claude already knows, includes extensive UI mockups and multiple verbose examples that add little instructional value, skips critical workflow steps (the actual transcription), and relies on placeholder functions that aren't executable. The mixed English/Portuguese content and missing steps (2 and 4) suggest an incomplete draft rather than a polished skill.

Suggestions

Cut the content by 70-80%: remove installation scripts, UI mockups with box-drawing characters, basic file validation code, and multiple usage examples. Focus on the core workflow steps Claude needs.

Add the missing Step 2 (actual transcription) with executable Faster-Whisper code showing how to call the transcription engine and get segments back.

Replace placeholder functions (cluster_by_topic, call_ai_model, extract_action_items) with actual executable implementations or remove them and describe the approach concisely.

Move installation instructions, output templates, and examples into separate referenced files (e.g., INSTALL.md, TEMPLATES.md, EXAMPLES.md) to improve progressive disclosure.

Dimension	Reasoning	Score
Conciseness	Extremely verbose — the skill is hundreds of lines long, explains basic concepts Claude already knows (what audio formats are, how to check if a file exists), includes extensive UI mockups with box-drawing characters, mixes languages (English/Portuguese), and repeats information across multiple examples. Much of this content (installation scripts, progress bar mockups, multiple usage examples) adds no instructional value for Claude.	1 / 5
Actionability	While there are code snippets, many are pseudocode or incomplete (e.g., `cluster_by_topic()`, `extract_action_items()`, `call_ai_model()` are undefined placeholders). The workflow skips from Step 1 to Step 3 to Step 5, missing the actual transcription step (Step 2). The Python code mixes paradigms and isn't copy-paste executable. Key functions like the actual Whisper transcription call are never shown.	2 / 5
Workflow Clarity	Steps are numbered but skip from Step 0 to Step 1 to Step 3 to Step 5, with Step 2 (the actual transcription) and Step 4 missing entirely. There are no validation checkpoints after transcription. The batch processing example (Example 3) shows no validation or error recovery for failed files, which should cap this score. The workflow is disjointed and hard to follow as a coherent sequence.	2 / 5
Progressive Disclosure	The content is a monolithic wall of text with no references to external files despite being extremely long. The installation script, output templates, LLM processing logic, and multiple examples are all inlined when they should be in separate files. References to `scripts/install-requirements.sh` exist but no bundle files are provided, and the skill doesn't organize its content into a navigable structure.	2 / 5
	Total	7 / 20 Passed

Description

53%Scale 1-5

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 niche (audio-to-Markdown with summaries) but lacks a 'Use when...' clause, which limits its effectiveness for skill selection. It would benefit from more specific capability details and natural trigger terms users would actually say, such as 'transcribe', 'meeting recording', or audio file extensions.

Suggestions

Add a 'Use when...' clause with trigger terms like 'transcribe audio', 'meeting recording', 'convert speech to text', 'audio notes'.

Include common audio file extensions (.mp3, .wav, .m4a) and synonyms like 'transcription', 'voice memo', 'meeting notes' to improve trigger term coverage.

List more specific capabilities such as speaker identification, timestamp generation, or supported audio formats to increase specificity.

Dimension	Reasoning	Score
Specificity	Names the domain (audio recordings, Markdown documentation) and describes a couple of concrete actions (transform, summarize with LLM integration), but lacks comprehensive detail about specific capabilities like supported formats, transcription steps, or output options.	3 / 5
Completeness	Provides a clear 'what' (transform audio to Markdown with summaries) but has no explicit 'when' clause or trigger guidance. Per rubric guidelines, the missing 'Use when...' clause caps this at 3.	3 / 5
Trigger Term Quality	Includes some relevant keywords like 'audio recordings', 'Markdown documentation', and 'summaries', but misses natural user phrases like 'transcribe', 'meeting notes', 'voice memo', audio file extensions (.mp3, .wav), or 'speech-to-text'.	3 / 5
Distinctiveness Conflict Risk	The combination of audio-to-Markdown transformation with LLM-based summarization is fairly distinctive and unlikely to overlap heavily with other skills. Minor overlap risk with general transcription or general Markdown generation skills.	4 / 5
	Total	13 / 20 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 (555 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: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: skills/audio-transcriber/SKILL.md
Commit: debb2ec

Reviewed: 12 hours 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.