ax-python-refine

Use when writing Python code with `axllm` for reward-scored generation, iterative candidate improvement, evaluator feedback, and optimizer-backed refinement patterns.

Quality

70%

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-refine/SKILL.md

Quality

Content

72%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.

The body is admirably lean and well-organized with executable core code and concrete symbol names, but it stops short of a real sequenced workflow with validation checkpoints and its references are named as facts rather than clearly signaled navigation. Progressive disclosure is weakened by inlined API-surface content and referenced files that are not actually present in the bundle.

Suggestions

Add a short ordered workflow (e.g., check examples -> pick optimizer vs no-key transport -> run optimize -> inspect AxIR on disagreement) with an explicit validation/retry checkpoint.

Convert the 'Package Facts' file list into signaled navigation ('See API.md for full method reference', 'See examples/ for runnable samples') and ensure those files exist in the bundle.

Move the inlined 'Relevant API Surface' symbol list into a referenced file or expand each symbol with a one-line executable usage so the inline content is genuinely actionable.

Dimension	Reasoning	Score
Conciseness	The body is lean and well-sectioned ('Package Facts', 'Core Pattern', 'Relevant API Surface', 'Guardrails') with no padding and no explanation of concepts Claude already knows; every line earns its place. Not below 5 because there is no verbosity or over-explanation to trim.	5 / 5
Actionability	The 'Core Pattern' gives executable code (from axllm import AxGEPA; engine.optimize(request, evaluator)) and the API surface lists concrete symbols. Not a 5 because the snippet leaves key operands undefined (reflection_client, request, evaluator) and the API surface is named but not shown in usable call shapes.	4 / 5
Workflow Clarity	'When To Use' and 'Guardrails' give rough orientation and advisory checkpoints ('Start from package examples', 'Treat AxIR as source of truth'), but there is no explicit multi-step sequence or validation/retry loop. Not a 4 because no concrete ordered workflow with checkpoints is laid out, and not below 3 because the guardrails supply implicit sequencing guidance.	3 / 5
Progressive Disclosure	Sections are organized and external materials are named (API.md, axir-api.json, axir-capabilities.json, examples/), but the references are listed as 'Package Facts' rather than clearly signaled 'See X for Y' navigation, and the inlined API surface listing is content that could live in a separate file. Not a 4 because navigation to the referenced files is not clearly signaled, and the referenced files are not present in the bundle to verify.	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 clearly answers both what and when with a concrete trigger clause and a named package niche, but its trigger vocabulary is jargon-heavy and leans on category labels rather than the natural phrases a user would actually say. Specificity and distinctiveness are strong; trigger-term naturalness and 'when' explicitness are the limiting factors.

Suggestions

Add user-natural trigger phrases to the 'Use when...' clause (e.g., 'when improving LLM outputs with feedback, scoring candidates, or running an optimizer') so it matches what users actually say.

Replace abstract category labels ('optimizer-backed refinement patterns') with concrete capability verbs a user would recognize.

Broaden the 'when' beyond 'writing Python code' to name the refinement tasks specifically to reduce overlap with generic Python skills.

Dimension	Reasoning	Score
Specificity	Names the domain (Python code with axllm) and several concrete actions — 'reward-scored generation, iterative candidate improvement, evaluator feedback, and optimizer-backed refinement patterns' — with only minor abstractness in 'patterns'. Not a 5 because the actions are framed as categories rather than crisply distinct concrete capabilities.	4 / 5
Completeness	Explicit 'Use when writing Python code with axllm' supplies the when, and the clause lists the what (reward-scored generation, iterative improvement, evaluator feedback, optimizer refinement). Not a 5 because the 'when' is narrow and does not enumerate the concrete trigger phrases users would say.	4 / 5
Trigger Term Quality	Includes some natural phrases ('writing Python code', 'evaluator feedback', 'iterative candidate improvement') but leans on technical jargon ('optimizer-backed refinement', 'reward-scored generation') and misses common synonyms a user would naturally say. Not a 4 because several natural variations a user might voice are absent.	3 / 5
Distinctiveness Conflict Risk	The axllm refinement niche is mostly distinct with low overlap risk against generic Python skills. Not a 5 because 'writing Python code' is broad and could brush against general Python skills before the refinement-specific qualifiers kick in.	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-refine/SKILL.md
Commit: 781623e

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.