CtrlK
BlogDocsLog inGet started
Tessl Logo

clarify

Improve unclear UX copy, error messages, microcopy, labels, and instructions to make interfaces easier to understand. Use when the user mentions confusing text, unclear labels, bad error messages, hard-to-follow instructions, or wanting better UX writing.

70

Quality

63%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.codex/skills/clarify/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Discovery

100%

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 is a strong skill description that clearly defines its scope (UX copy improvement), lists specific content types it handles, and provides explicit trigger guidance with natural user language. It uses proper third-person voice and is concise without being vague. The description effectively differentiates itself from general writing or editing skills by focusing on interface-specific copy.

DimensionReasoningScore

Specificity

Lists multiple specific concrete actions: 'Improve unclear UX copy, error messages, microcopy, labels, and instructions to make interfaces easier to understand.' These are distinct, concrete content types rather than vague abstractions.

3 / 3

Completeness

Clearly answers both 'what' (improve UX copy, error messages, microcopy, labels, instructions) and 'when' with an explicit 'Use when...' clause listing specific trigger scenarios like confusing text, unclear labels, bad error messages, and wanting better UX writing.

3 / 3

Trigger Term Quality

Includes natural keywords users would actually say: 'confusing text', 'unclear labels', 'bad error messages', 'hard-to-follow instructions', 'better UX writing', 'microcopy'. These cover a good range of how users would naturally describe their needs.

3 / 3

Distinctiveness Conflict Risk

Clearly scoped to UX writing and interface copy specifically, with distinct triggers like 'microcopy', 'error messages', 'UX writing', and 'labels' that are unlikely to conflict with general writing or editing skills.

3 / 3

Total

12

/

12

Passed

Implementation

27%

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

This skill reads more like a comprehensive UX writing guide or textbook chapter than a concise, actionable skill file. While the before/after examples are genuinely useful, the content is far too verbose for a skill file — it explains many concepts Claude already understands well (active voice, avoiding jargon, being specific). The monolithic structure with nine fully-expanded copy type sections makes it hard to navigate and wastes token budget.

Suggestions

Drastically reduce content by removing explanations of basic UX writing principles Claude already knows (active voice, avoiding jargon, being concise) and keep only project-specific conventions or non-obvious guidance.

Extract the nine copy-type subsections (error messages, form labels, buttons, etc.) into a separate reference file (e.g., COPY_PATTERNS.md) and link to it from the main skill, keeping only a brief summary table inline.

Clarify the dependency references ('$frontend-design', '$teach-impeccable') — explain what these are, when they're available, and what to do if they're not found.

Add explicit validation/feedback steps in the workflow, such as 'Present improved copy side-by-side with original for user review before applying changes' to create a proper review checkpoint.

DimensionReasoningScore

Conciseness

The skill is extremely verbose at ~150+ lines, with extensive explanations of UX writing principles that Claude already knows well. Sections like 'Apply Clarity Principles' and the NEVER list are basic UX writing knowledge. The bad/good examples, while useful, are exhaustive to the point of being a textbook rather than a skill file. Much of this could be cut by 60-70% without losing actionable value.

1 / 3

Actionability

The skill provides concrete before/after examples for many copy types (error messages, buttons, empty states, etc.), which is helpful. However, it lacks executable workflows — there are no code snippets, no specific tool invocations beyond vague references to '$frontend-design' and '$teach-impeccable', and the guidance is more about principles than step-by-step execution. It describes what good copy looks like rather than giving a precise process to produce it.

2 / 3

Workflow Clarity

There is a rough sequence (gather context → assess → plan → improve → verify), but the steps are loosely defined with no explicit validation checkpoints or feedback loops. The 'Verify Improvements' section is a checklist of questions rather than concrete validation steps. For a skill involving potentially destructive changes to user-facing copy, the lack of review/approval gates is a gap.

2 / 3

Progressive Disclosure

The content is a monolithic wall of text with all details inline. Nine subsections of copy types (error messages, form labels, buttons, help text, empty states, success messages, loading states, confirmation dialogs, navigation) are all fully expanded in the main file. These could easily be referenced as separate documents or collapsed into a summary with links. The references to '$frontend-design' and '$teach-impeccable' are unclear and not well-signaled.

1 / 3

Total

6

/

12

Passed

Validation

90%

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

Validation10 / 11 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

10

/

11

Passed

Repository
pbakaus/impeccable
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.