ax-java-signature

Use when writing Java code with `dev.axllm:ax` for string signatures, field descriptors, JSON schema output, validation, and typed tool argument shapes.

Quality

80%

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 ./website/static/java/.well-known/agent-skills/ax-java-signature/SKILL.md

Quality

Content

75%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 well-organized, reference-style skill with concrete, executable code patterns covering the signature/schema core and useful guardrails. The main gaps are the codeless Typesafe/Jev section (the longest part of the body) and inline spec density that would fit better in a reference file.

Suggestions

Add one short Java snippet to the Typesafe / Jev section (e.g., a boolean or class output with trueThreshold set) — it is the longest section yet has no executable example.

Show how a client is constructed before "program.forward(client, inputs)", and add a minimal Ax.fn/Tool example since tools are listed in the API surface but never demonstrated.

Move the Typesafe/Jev spec details (naming variants, probability tolerance rules, balancer behavior) into a separate reference file with a one-line pointer, keeping SKILL.md as the lean overview.

Dimension	Reasoning	Score
Conciseness	The body is lean with no explanations of concepts Claude already knows, and every code example is tight. Not 5 because minor tokens could be trimmed — cross-language comparisons ("C++ uses valueDescriptions on its existing field descriptors", "only TypeScript can infer literal question keys") and triple naming listings ("system_one / systemOne / SystemOne") add little for a Java-focused skill; not 3 because there is no real padding or over-explanation.	4 / 5
Actionability	Concrete executable patterns for the signature core: "Ax.s(\"question:string -> answer:string\")", "sig.toJsonSchema(\"outputs\", java.util.Map.of())", and the full fluent builder chain. Not 5 because the ~25-line Typesafe/Jev section contains no code at all, "program.forward(client, inputs)" uses a client that is never constructed, and "Ax.fn"/"Tool" are listed in the API surface but never demonstrated; not 3 because the guidance that is present is concrete and executable rather than pseudocode.	4 / 5
Workflow Clarity	Decision points are labeled ("Use the string form when field names and types are enough") and Guardrails provide checkpoints ("if package docs disagree with source code, update the compiler and regenerate packages", "Use no-key examples for deterministic local checks", plus explicit probability tolerance rules). Not 5 because there is no explicit sequence from pattern choice to verified running code; not 3 because validation-relevant guidance is present rather than absent.	4 / 5
Progressive Disclosure	Clear sections (When To Use, Package Facts, Core Pattern, More Patterns, Typesafe/Jev, Relevant API Surface, Guardrails) with package references signaled up front ("Package API docs: API.md and axir-api.json", "Runnable examples: examples/"). Not 5 because the dense Typesafe/Jev spec (thresholds, probability tolerances, naming variants, balancer behavior) is inlined in SKILL.md where a separate reference file would keep the overview lean; not 3 because the structure and reference signaling are good, not merely "some structure".	4 / 5
	Total	16 / 20 Passed

Description

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

A strong, concise, well-scoped description with an explicit "Use when" trigger clause and concrete capability objects. The main improvement is stating the capabilities as an explicit action sentence (rather than only embedding them in the trigger clause) and adding a few natural synonyms to broaden trigger coverage.

Suggestions

Lead with a capability sentence (e.g., "Declare Ax signatures, field descriptors, and JSON-schema outputs in Java with dev.axllm:ax") before the "Use when" clause so the "what" is explicit.

Add one or two natural trigger synonyms such as "output contracts" or "program generation" to widen keyword coverage.

Dimension	Reasoning	Score
Specificity	Quotes: "writing Java code with dev.axllm:ax for string signatures, field descriptors, JSON schema output, validation, and typed tool argument shapes" — five concrete capability objects tied to a named package. Not 5 because coverage has gaps (the body's programs/AxGen, fluent builders, and typesafe/Jev scoring are absent); not 3 because it lists far more than 1-2 concrete items.	4 / 5
Completeness	The explicit clause "Use when writing Java code with dev.axllm:ax" clearly answers "when", and the purpose list (signatures, field descriptors, JSON schema, validation, tool shapes) conveys "what" — but the what is embedded in the trigger clause rather than stated as an explicit action sentence. Not 5 because anchor-5 descriptions state capabilities as verbs in their own sentence; not 3 because the when is explicit, not "missing or only weakly implied".	4 / 5
Trigger Term Quality	Natural terms present: "Java code", "string signatures", "JSON schema output", "validation", "typed tool argument shapes" — a user needing this skill would plausibly say these. Not 5 because synonyms and variations are missing ("Ax", "output contracts", "typesafe", "Jev", "program generation"); not 3 because coverage is good rather than just "some relevant keywords".	4 / 5
Distinctiveness Conflict Risk	Quotes: "writing Java code with dev.axllm:ax for string signatures, field descriptors..." — scoped to one language, one specific package, and specific artifacts, giving a clear niche with distinct triggers and minimal conflict risk even against sibling language skills for the same package family.	5 / 5
	Total	17 / 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: website/static/java/.well-known/agent-skills/ax-java-signature/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.