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

Low

Low-risk findings worth noting

Quality

Content

90%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 an efficient, actionable reference with executable Java patterns covering common cases and a clear section sequence. Its one gap is that referenced bundle files are named but not actually present in the skill directory, slightly weakening progressive disclosure.

Suggestions

Either ship the referenced files (API.md, axir-api.json, axir-capabilities.json, examples/) as bundle assets or rewrite the Package Facts lines to clarify these live in the generated package rather than the skill bundle, so references resolve to real files.

Add a brief validation checkpoint in the Guardrails (e.g., "Run a no-key example to confirm the signature compiles before wiring it into a provider call") to add an explicit feedback loop.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes Java competence — short framing lines like "Use the string form when field names and types are enough" lead directly into executable code, with no padding about what Java or schemas are, matching the 5 anchor where every token earns its place.	5 / 5
Actionability	Multiple copy-paste-ready Java snippets (Ax.s string form, fluent builder with min/max/regex, toJsonSchema, program.forward) cover the common cases with concrete, executable code, matching the 5 anchor.	5 / 5
Workflow Clarity	Sections flow When To Use → Core Pattern → More Patterns → Guardrails with concrete guidance, but there is no explicit multi-step validate-then-recover sequence; it is not a destructive/batch skill so the cap does not apply, placing it at the 4 anchor (clear sequence, minor checkpoint gaps).	4 / 5
Progressive Disclosure	Structure is good with clearly signaled one-level-deep references ("Package API docs: API.md and axir-api.json", "Runnable examples: examples/"), but the referenced bundle files (API.md, axir-api.json, axir-capabilities.json, examples/) are not present alongside SKILL.md, leaving a minor organization gap per the 4 anchor.	4 / 5
	Total	18 / 20 Passed

Description

71%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 concrete, scoped to a specific package, and explicitly answers both what and when. Its main weakness is that the trigger terms lean technical rather than reflecting the natural phrasing a user would say.

Suggestions

Add natural-language trigger phrases a user might say (e.g., "Use when the user asks to define input/output contracts, build typed tool arguments, or generate JSON schemas in Java with the Ax package") to broaden trigger_term_quality beyond technical jargon.

Optionally name a synonym or two (e.g., "structured outputs" or "typed prompts") so the description matches common user wording rather than only API-internal terms.

Dimension	Reasoning	Score
Specificity	Names the domain (Java with dev.axllm:ax) and several concrete actions — "string signatures, field descriptors, JSON schema output, validation, and typed tool argument shapes" — which lists multiple specific capabilities with minor coverage gaps, matching the 4 anchor.	4 / 5
Completeness	It explicitly states what the skill does (the listed capabilities) and when to use it ("Use when writing Java code with `dev.axllm:ax`..."), with both present and concrete, matching the 4 anchor where the when could be slightly more specific.	4 / 5
Trigger Term Quality	"writing Java code" is a natural trigger, but the remaining terms ("string signatures", "JSON schema output", "typed tool argument shapes") are technical jargon rather than the natural phrases a user would say, leaving common synonyms missing per the 3 anchor.	3 / 5
Distinctiveness Conflict Risk	Scoped to a specific generated package (`dev.axllm:ax`) and Java, giving it a clear niche with distinct triggers and minimal conflict risk, matching the 5 anchor.	5 / 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/java/skills/ax-java-signature/SKILL.md
Commit: dec4f9e

Reviewed: ~23 hours 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.