clarify

Clarify intent-expression gaps. Extracts clarified intent when what you mean differs from what you said. Type: (IntentMisarticulated, Hybrid, EXTRACT, Expression) → ClarifiedIntent. Alias: Hermeneia(ἑρμηνεία).

Quality

27%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./hermeneia/skills/clarify/SKILL.md

Quality

Discovery

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This description is heavily laden with academic jargon and a formal type-signature notation that obscures rather than clarifies its purpose. It fails to use natural language a user or Claude would recognize, lacks any explicit 'Use when...' trigger guidance, and does not describe concrete actions in accessible terms. It also uses second person ('what you mean differs from what you said'), which violates the third-person voice guideline.

Suggestions

Replace jargon with plain language describing concrete actions, e.g., 'Detects when a user's words don't match their likely intent and rephrases or clarifies the intended meaning.'

Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user says something ambiguous, contradictory, or when their request doesn't seem to match their goal — phrases like "that's not what I meant", "let me rephrase", or "I'm trying to say..."'

Remove the type-signature notation and Greek alias, which add no selection value, and rewrite in third person voice throughout.

Dimension	Reasoning	Score
Specificity	The description uses abstract, jargon-heavy language like 'intent-expression gaps', 'IntentMisarticulated', 'Hybrid', and 'EXTRACT'. It does not list concrete, understandable actions a user would recognize. The type signature notation is opaque rather than clarifying.	1 / 3
Completeness	The 'what' is vaguely stated ('extracts clarified intent') but not in concrete terms. There is no 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. This caps completeness at a maximum of 2 per the rubric, but the weak 'what' brings it to 1.	1 / 3
Trigger Term Quality	No natural keywords a user would actually say are present. Terms like 'IntentMisarticulated', 'Hermeneia(ἑρμηνεία)', and 'Expression' are technical jargon or academic references that no user would naturally use when seeking this kind of help. A user might say 'I didn't say what I meant' or 'rephrase my message' — none of these natural triggers appear.	1 / 3
Distinctiveness Conflict Risk	The description is niche enough in its academic framing (hermeneutics, intent-expression gaps) that it's unlikely to broadly conflict with common skills. However, the vagueness of 'clarify intent' could overlap with general communication or rephrasing skills, preventing a score of 3.	2 / 3
	Total	5 / 12 Passed

Implementation

47%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill provides an impressively thorough and well-structured workflow for intent clarification with excellent phase sequencing and validation checkpoints. However, it is severely over-engineered for its purpose — the formal type-theoretic notation, extensive state machine specification, and repeated rule elaborations consume enormous token budget while adding marginal actionable value over a more concise presentation. The content would benefit greatly from separating the formal specification into a reference file and keeping the SKILL.md as a lean operational guide.

Suggestions

Move the formal specification block (FLOW, MORPHISM, TYPES, E-BINDING, PHASE TRANSITIONS, TOOL GROUNDING, ELIDABLE CHECKPOINTS, MODE STATE) to a separate SPEC.md reference file, keeping only a brief summary in SKILL.md

Remove or drastically condense the 10-protocol comparison table — Claude doesn't need to understand all sibling protocols to execute this one; a 1-2 sentence boundary note suffices

Consolidate the 19 rules section — many are restatements of behavior already specified in the phases (e.g., rules 13-18 elaborate on Phase 1b behavior already described); reduce to 5-7 essential rules

Replace formal notation (Λ, Eᵥ, Gₛ, Î') with plain English in the operational sections — the notation adds cognitive overhead without improving Claude's ability to execute the protocol

Dimension	Reasoning	Score
Conciseness	Extremely verbose at ~300+ lines with extensive formal notation (morphisms, type theory, state machines) that Claude doesn't need explained in this detail. The formal specification language (Λ, Eᵥ, Gd, Gₛ, Î') adds significant token overhead. Concepts like 'gate interaction' and 'present + stop' are repeated dozens of times. The distinction table with 10 other protocols is largely unnecessary context.	1 / 3
Actionability	The protocol phases provide structured steps with concrete option templates (e.g., the confirmation dialogs in Phase 0, 1a, 1b, 2), and the gap taxonomy gives specific detection criteria. However, there are no executable code examples, and much of the guidance is abstract formal specification rather than concrete 'do this' instructions. The formal notation requires significant interpretation to translate into action.	2 / 3
Workflow Clarity	The multi-step workflow is clearly sequenced (Phase 0 → 1a → 1b → 2 → 3 → loop) with explicit validation checkpoints at each phase (user confirmation gates), clear skip conditions, convergence criteria, and error recovery paths (revise sub-step, escape hatches, termination conditions). The loop logic with re-diagnosis and gap filtering is well-specified.	3 / 3
Progressive Disclosure	There is one external reference (references/socratic-style.md) which is appropriate, and the content uses headers and tables for organization. However, the massive formal specification block at the top is a monolithic wall of notation that could be split into a separate reference file. The skill tries to be both a formal spec and an operational guide in one document, making it harder to navigate.	2 / 3
	Total	8 / 12 Passed

Validation

100%

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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: jongwony/epistemic-protocols
Commit: 9342160

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.