ax-python-agent

Use when writing Python code with `axllm` for agents, child delegation, tools, MCP, citations, persistent playbook learning, stage instructions, runtime state, final typed responses, and direct-respond executor skipping.

Quality

62%

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

Quality

Content

32%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 reads as an inlined API reference rather than a working skill: dense multi-clause paragraphs, half of the session section devoted to non-Python languages, version-history notes inline, and only one small code example. The genuinely useful parts (core pattern, package facts, API surface, guardrails) are buried in material that belongs in separate reference files.

Suggestions

Move the Astra session-work, streaming, and flat-namespace reference material into separate reference files (e.g. references/sessions.md, references/streaming.md) and keep SKILL.md to When To Use, the core pattern, package facts, and guardrails.

Replace prose descriptions of key operations with short executable snippets (agent construction, add_child_agent registration, streaming_forward usage) so the guidance is copy-paste usable rather than descriptive.

Delete or relocate non-Python detail (Java/C++/Rust/Go adapter behavior) and version-history notes ('since 25.0.0', 'as the ports did before 25.0.0') to a migration reference or remove them; they consume context without guiding Python code.

Dimension	Reasoning	Score
Conciseness	The body is dense stacked-caveat prose ('Queued and applied are different states. HTTP applies updates at a response boundary; an optional host WebSocket enables native steering...'), and roughly half the 'Astra Session Work' section describes Java, C++, Rust, and Go behavior in a skill for Python. Version-sensitive statements ('the default since 25.0.0', 'as the ports did before 25.0.0') sit inline rather than in a migration/deprecated section, matching 'noticeably verbose; several unnecessary explanations or padded sections' rather than the mostly-efficient 3 anchor.	2 / 5
Actionability	There is one complete runnable snippet (the 4-line core pattern) and a concrete API-surface list (AxAgent.add_child_agent, AxMCPStreamableHTTPTransport, ...), but the bulk is descriptive prose with no executable examples; the skill even defers ('Start from package examples for exact native syntax before inventing a new call shape') instead of showing them. Fits 'some concrete guidance but incomplete; missing key details'.	3 / 5
Workflow Clarity	The body is a topical reference dump with no ordered steps and no validation checkpoints anywhere (nothing verifies a run, output, or state), and it is not a simple single-action skill that could earn the simple-skill exception. Fits 'rough sequence present but many gaps; steps poorly defined; validation absent' — organization exists, but no workflow is ever sequenced.	2 / 5
Progressive Disclosure	About 105 lines of dense API reference (Astra session semantics, streaming rules, flat namespace modes) are inlined in SKILL.md itself — the same material the 'Package Facts' section says lives in `API.md`, `axir-api.json`, and `examples/`, none of which exist as bundle files. Section headers exist, so above the floor, but the content that clearly belongs in separate files dominates, matching the score-2 anchor.	2 / 5
	Total	9 / 20 Passed

Description

75%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 is well-scoped: it names a concrete domain (Python with `axllm`) with an explicit 'Use when' trigger and a broad, package-specific capability list. Its weaknesses are the absence of any stated action the skill performs (only noun-topics) and jargon-laden trigger terms ('direct-respond executor skipping', 'stage instructions') that no user would naturally say.

Suggestions

State what the skill does in third-person action verbs before the 'Use when' clause, e.g. 'Writes Python agents with the `axllm` package: builds tools, MCP clients, child-agent delegation, citations, and runtime state management.'

Trim internal jargon from the trigger list ('direct-respond executor skipping', 'stage instructions', 'persistent playbook learning') in favor of terms a user would actually say, such as 'agent framework', 'MCP integration', or 'child agents'.

Lead with the most common natural phrasing (Python, axllm, agents, MCP, citations) at the front of the description so the strongest trigger terms surface first.

Dimension	Reasoning	Score
Specificity	Names the domain ('Python code with `axllm`') and a long list of concrete capability areas ('agents, child delegation, tools, MCP, citations, persistent playbook learning, stage instructions, runtime state, final typed responses, and direct-respond executor skipping'), matching the 'lists several specific actions; minor gaps' anchor. Not 5 because the items are noun-topics rather than stated actions; not 3 because coverage is far broader and more package-scoped than 1-2 items.	4 / 5
Completeness	An explicit 'Use when...' trigger is present ('Use when writing Python code with `axllm` for...') along with an implied what (guidance for the listed features), matching 'has both what and when; when could be more explicit or specific'. Not 5 because the what is only implied by the topic list and never states what the skill itself does.	4 / 5
Trigger Term Quality	Natural user terms are present ('Python code', 'agents', 'tools', 'MCP', 'citations') but are interleaved with package-internal jargon users would not say ('direct-respond executor skipping', 'stage instructions'). Fits 'good keyword coverage; a few natural terms missing' rather than 5, which requires synonyms and natural variations without jargon dilution.	4 / 5
Distinctiveness Conflict Risk	The `axllm` qualifier carves out a clear niche that other skills would not match, but generic terms ('agents', 'tools', 'MCP', 'citations') overlap with general agent-building skills. Fits 'mostly distinct; minor overlap risk' rather than the minimal-conflict 5 anchor.	4 / 5
	Total	16 / 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-agent/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.