CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

moai-jev-skill-suggestion

Guidance for a display-only skill-suggestion capability: how a caller should suggest a skill to the operator, how the emitted answer is read, and what must never happen (selection, auto-loading, judgment). The capability gate ships off; this skill carries mechanism and contract ONLY — never the call path; where and how to reach the capability is the catalogue's concern.

Quality

64%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/moai-jev-skill-suggestion/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

53%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 a well-organized, jargon-consistent contract document that records concrete mechanisms (gate key, credential file, doctor probe) and a specific operational checklist. Its weaknesses are redundancy — the display-only contract and gate-off state are each restated multiple times — and the absence of validation checkpoints or navigable references, since the actionable detail is deferred to skills outside this bundle.

Suggestions

Merge "What this skill is not" into "What a suggestion is" — the not-a-verdict and not-an-availability-promise points largely restate the four prohibitions and the gate-off rule already given, cutting roughly a dozen lines of redundancy.

State the gate-off and catalogue-ownership facts once each instead of three times (opening section, rejected-mechanisms section, and closing section) to tighten conciseness.

Add a concrete validation step to the operational checklist (e.g., how a caller verifies the doctor readiness output before proceeding, or how to confirm a skill was filtered rather than merely suggested) so the sequence has an explicit checkpoint.

Reference the question-design skill and the product catalogue by path or linkable identifier rather than by name alone, so the external pointers are navigable instead of descriptive.

DimensionReasoningScore

Conciseness

The body is dense with no padding over concepts Claude already knows, but it repeats its core contract structurally: the not-selection/not-auto-load/not-judgment rules appear in "What a suggestion is" and again nearly verbatim in "What this skill is not" ("never close cards, approve merges, or mutate queues"), and both "the gate ships off" and "the catalogue owns the call path" are stated multiple times. It fits anchor 3 — mostly efficient but could be tightened by merging the redundant closing section.

3 / 5

Actionability

There is genuinely concrete guidance (the gate key `workflow.jev.enabled`, the credentials file `~/.moai/.env.typesafe`, the TCP-only doctor probe, and a specific 6-item checklist covering logging, task-origin filtering, `disable-model-invocation` filtering, session caching, duplicate-injection guards, and name canonicalization). However, the bulk of the body is definitional contract and rejected-mechanism record, and the actionable question-design rules are explicitly deferred elsewhere ("Those rules live in the question-design reference skill"), leaving the guidance incomplete for anchor 4.

3 / 5

Workflow Clarity

The gate-first flow has one explicit conditional checkpoint ("A caller that cannot confirm all three proceeds as if the gate were off") and the operational checklist is numbered, but the checklist items are conditional guidance with no validation or verification steps, and the sequence presumes a caller that the skill itself says does not exist. Steps are listed with checkpoints missing or implicit — anchor 3, and the under-50-line simple-skill exception does not apply to this ~92-line body.

3 / 5

Progressive Disclosure

The body is well-organized into six clearly-headed sections with no inlined reference-dump content, and no bundle files exist to misplace. It misses anchor 5 because it is a monolithic single file over 50 lines whose only external pointers ("the question-design reference skill", "the product catalogue") are named without paths or links, giving no navigable reference structure.

4 / 5

Total

13

/

20

Passed

Description

58%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 specific and well-scoped about the capability and its prohibitions, but it omits any 'when to use' trigger guidance from the description field itself and leans on internal jargon (gate, catalogue, call path) rather than natural user phrases. It is clearly distinguishable from other skills and avoids over-claims, though the trigger surface for discovery is narrow.

Suggestions

Add an explicit 'Use when...' sentence to the description itself (e.g., 'Use when designing or reviewing a skill-suggestion feature, or diagnosing a suggestion that auto-selected or auto-loaded a skill') so the when-guidance is not confined to the separate when_to_use field.

Replace internal jargon ('mechanism and contract ONLY', 'the call path', 'the catalogue's concern') with natural terms a user would say — 'suggest a skill', 'skill suggestions', 'display-only' — and include common variations to improve trigger-term coverage.

Trim the second half of the description (the catalogue/call-path ownership note) into the when-clause, which would raise both completeness and trigger-term quality without adding length.

DimensionReasoningScore

Specificity

The description names the domain ("display-only skill-suggestion capability") and enumerates several specific facets — "how a caller should suggest a skill to the operator", "how the emitted answer is read", and "what must never happen (selection, auto-loading, judgment)". It stops short of anchor 5 because coverage is not comprehensive (readiness surfaces, the operational checklist, and the rejected-mechanism record are absent), but it lists more than the 1-2 actions of anchor 3.

4 / 5

Completeness

The 'what' is clear and concrete (guidance for a display-only suggestion capability with explicit prohibitions), but the description field itself contains no 'Use when...' clause or equivalent trigger guidance — the when-guidance lives in a separate when_to_use frontmatter field outside the evaluated target. Per the judging guideline this caps completeness at 3.

3 / 5

Trigger Term Quality

Some natural phrases appear ("suggest a skill to the operator", "skill-suggestion"), but the text leans heavily on internal jargon — "the capability gate ships off", "mechanism and contract ONLY", "the call path", "the catalogue's concern" — that a user would never say. This matches anchor 3 (relevant keywords present, common variations and synonyms missing) better than anchor 4's good coverage.

3 / 5

Distinctiveness Conflict Risk

"Display-only skill-suggestion capability" with explicit scope limits ("never the call path") carves a clear niche distinct from adjacent skills like question design or the catalogue. It is not anchor 5 because adjacent skills are named in the ecosystem and the "Guidance for..." framing leaves minor overlap risk with general skill-selection or wiring guidance.

4 / 5

Total

14

/

20

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

modu-ai/moai-adk

Path

.claude/skills/moai-jev-skill-suggestion/SKILL.md

Reviewed

Table of Contents

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.