ax-python-audio

Use when writing Python code with `axllm` for audio input/output, OpenAI Responses audio mapping, realtime event folding, and generated package audio examples.

Quality

74%

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 ./packages/python/skills/ax-python-audio/SKILL.md

Quality

Content

71%Weight 40%Scale 1-5

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

A lean, fact-dense reference for the generated axllm audio API: concrete keys, provider defaults, and guardrails with essentially no filler. Its weaknesses are the absence of any complete inline example for the main audio flows, references to files that are not present in the skill bundle, and spec-like detail inlined in SKILL.md that belongs in a separate reference file.

Suggestions

Include a minimal complete inline example (e.g., a full `speak()` call and one realtime event fold) so the core flows are copy-paste executable without relying on the external `examples/` directory.

Move the flat API-surface name list and the dense speech-field mapping rules into a bundled reference file (e.g., `references/api-surface.md`) and link to it from SKILL.md.

Ensure the referenced files (`API.md`, `axir-api.json`, `axir-capabilities.json`, `examples/`) are actually included in the skill bundle, or rephrase Package Facts to make clear they live in the generated package repository rather than the skill.

Dimension	Reasoning	Score
Conciseness	The body is fact-dense and assumes Claude's competence — no concept explanations, no filler — but a few bullets (the JSON-body parsing rules, the speech request mapping) are long run-on sentences that could be tightened, and the flat ~40-name API-surface list is a token-heavy block. Efficient with minor trim opportunities.	4 / 5
Actionability	Provides one executable snippet (`llm = ai("openai", api_key=...)`) plus concrete field names, provider defaults ('gpt-4o-mini-tts' with 'alloy'), and error semantics. However, no complete runnable example of the core audio flows (speak() usage, realtime event folding) is inline — the skill leans on an `examples/` directory that is not part of the bundle — so it is not fully copy-paste ready.	4 / 5
Workflow Clarity	This is a reference-style skill with no multi-step process to sequence; the guardrails ('Start from package examples', 'Use no-key examples for deterministic local checks and provider request mapping') make the approach unambiguous, which satisfies the simple-skill exception. It stays at 4 rather than 5 because there is no explicit sequence or checkpoint for accomplishing the main tasks (e.g., how to actually run a no-key example).	4 / 5
Progressive Disclosure	Sections are well-organized, but the body references `API.md`, `axir-api.json`, `axir-capabilities.json`, and `examples/` that do not exist in the skill bundle (no references/, scripts/, or assets/ directories), so navigation depends on files outside the skill. Reference-grade material — the long flat API-surface name list and the dense speech-field mapping rules — is inlined in SKILL.md rather than split into a bundled reference file.	3 / 5
	Total	15 / 20 Passed

Description

67%Weight 40%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 opens with an explicit 'Use when' trigger and names concrete, domain-specific tasks, giving it good specificity and low conflict risk. Its main weaknesses are missing natural user synonyms ('speech', 'voice', 'transcription') and a capability statement ('what') that only exists embedded inside the when-clause.

Suggestions

Add the natural trigger synonyms users would actually say — e.g. 'speech, voice, transcription, text-to-speech (TTS)' — alongside 'audio input/output'.

State the 'what' as its own clause before the trigger, e.g. 'Documents axllm's speech, transcription, and realtime audio APIs for Python. Use when...' so the capability statement is explicit rather than embedded.

Replace internal jargon in the description — 'realtime event folding' — with a user-facing phrase such as 'handling realtime audio and transcription events'.

Dimension	Reasoning	Score
Specificity	Lists several concrete tasks — 'audio input/output', 'OpenAI Responses audio mapping', 'realtime event folding', 'generated package audio examples' — matching the several-specific-actions anchor. Not comprehensive (speech synthesis and transcription covered in the body are absent), so not a 5.	4 / 5
Completeness	The 'Use when writing Python code with `axllm` for...' clause explicitly answers 'when', and the enumerated tasks convey 'what'. The what is only embedded inside the when-clause rather than stated as its own capability sentence, which keeps it below the explicit-both anchor 5.	4 / 5
Trigger Term Quality	Includes relevant keywords ('Python', 'audio', 'realtime', 'OpenAI Responses') but misses the common natural variations users would actually say — 'speech', 'voice', 'transcription', 'text-to-speech' — and 'realtime event folding' is internal jargon rather than a user phrase. Fits the some-keywords-missing-synonyms anchor better than good-coverage.	3 / 5
Distinctiveness Conflict Risk	The `axllm` + Python audio niche is clearly differentiated with distinct trigger terms, but 'writing Python code with axllm' can overlap with sibling axllm skills (the body itself defers audio output rendering to a separate 'gen skill'), giving minor overlap risk — the mostly-distinct anchor.	4 / 5
	Total	15 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: ax-llm/ax
Path: packages/python/skills/ax-python-audio/SKILL.md
Commit: 3f630a0

Reviewed: 3 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.