ax-java-llm

Use when writing Java code with `dev.axllm:ax` for using the generated Ax package, factory functions, package docs, examples, and API reference.

Quality

69%

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/java/skills/ax-java-llm/SKILL.md

Quality

Content

63%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 compact, well-sectioned quick reference with one executable core snippet and sensible guardrails, held back by an inline wall of bare API names with no signatures and references to bundle files that are not present. Moving the API surface into a real reference file and shipping the referenced docs would resolve its main weaknesses.

Suggestions

Move the "Relevant API Surface" name lists into a bundled reference file (e.g. references/api-surface.md) and keep only the top entrypoints inline, so the reference is one level deep and navigable.

Ship the referenced artifacts (API.md, axir-api.json, axir-capabilities.json, examples/) or remove/replace the pointers, since none exist in the bundle.

Add one or two more executable snippets beyond the single Core Pattern — e.g. a signature (Ax.s) and an agent (Ax.agent) call — so the listed API surface is actionable without leaving the file.

Dimension	Reasoning	Score
Conciseness	The body is lean: sections are compact, it never explains concepts Claude already knows, and the dense "Relevant API Surface" lists function as a quick index rather than padding. The intro paragraph mildly repeats the frontmatter description and the unstructured name wall could be trimmed, so it sits just below the every-token-earns-its-place 5 anchor.	4 / 5
Actionability	The "Core Pattern" snippet (`Ax.ai("openai", java.util.Map.of("apiKey", ...))`) is executable, and "Guardrails" gives concrete rules (e.g. "Use `no-key` examples for deterministic local checks"), but the bulk of the API surface is bare names with no signatures or call shapes, and the pointed-to `examples/` directory is not present in the bundle. Guidance is concrete but incomplete, matching the 3 anchor.	3 / 5
Workflow Clarity	"When To Use" and "Guardrails" give clear, mostly sequenced directives — start from package examples before inventing a call shape, prefer no-key examples, treat AxIR as source of truth — and the skill involves no destructive or batch operations requiring validation checkpoints. It falls short of 5 because the directives are presented in parallel without a priority order for cases where they conflict.	4 / 5
Progressive Disclosure	The body references `API.md`, `axir-api.json`, `axir-capabilities.json`, and `examples/`, but no bundle files (references/, scripts/, assets/) exist, so the navigation is dangling. Meanwhile the long inline "Relevant API Surface" name lists are content that belongs in a separate reference file. Structure is present but organization and signaling are imperfect, matching the 3 anchor.	3 / 5
	Total	14 / 20 Passed

Description

62%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 has an explicit trigger and a clearly named niche, but the "what" half is a resource list rather than a set of concrete actions, and natural trigger synonyms (LLM, AI, axllm) are absent. Rewriting it as action-first sentences would lift both specificity and completeness.

Suggestions

Rewrite as third-person action statements, e.g. "Writes Java code against the generated `dev.axllm:ax` package: calls factory functions (Ax.ai, Ax.s, Ax.agent), runs examples, and consults the API reference."

Add natural trigger synonyms users would actually say — "Ax", "axllm", "LLM", "AI" — alongside the existing "Java" and package-coordinate terms.

Tighten the grammar: "for using the generated Ax package" is a vague trailing clause; replace it with what the skill concretely does.

Dimension	Reasoning	Score
Specificity	The description names the domain ("writing Java code with `dev.axllm:ax`") but its remaining content — "the generated Ax package, factory functions, package docs, examples, and API reference" — enumerates resources rather than concrete actions, and the phrase "for using" adds no specific verb. It lists a domain plus one real action, matching the 3 anchor rather than the several-specific-actions of 4.	3 / 5
Completeness	Both parts are present: an explicit "Use when writing Java code with `dev.axllm:ax`" trigger and a "what" ("using the generated Ax package, factory functions, package docs, examples, and API reference"). The "what" is vague, so it does not reach the 5 anchor's concrete what-and-when pairing, but the "when" is explicit rather than weakly implied, keeping it above 3.	4 / 5
Trigger Term Quality	Trigger terms include "Java", "`dev.axllm:ax`", "Ax package", "factory functions", and "API reference", which are relevant, but common variations a user would naturally say are missing — notably "LLM"/"AI" (this is an LLM library), "axllm", or "Java SDK". Coverage is partial rather than good, fitting the 3 anchor.	3 / 5
Distinctiveness Conflict Risk	The `dev.axllm:ax` package qualifier establishes a clear niche with minimal conflict risk, but the description opens with the broad phrase "Use when writing Java code", which overlaps any general Java skill before the Ax qualifier narrows it. Mostly distinct with minor overlap risk, matching the 4 anchor.	4 / 5
	Total	14 / 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/java/skills/ax-java-llm/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.