hig-components-controls

Check for .claude/apple-design-context.md before asking questions. Use existing context and only ask for information not already covered.

Quality

36%

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 ./skills/hig-components-controls/SKILL.md

Quality

Content

61%Scale 1-5

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

This is a well-structured design guidance skill that efficiently organizes Apple HIG selection/input control knowledge with a clean reference index and clear principles. Its main weakness is the lack of concrete, executable examples (no SwiftUI code, no before/after patterns) and the absence of an explicit step-by-step workflow for control selection decisions. The progressive disclosure structure is strong but unverifiable without bundle files.

Suggestions

Add concrete SwiftUI code examples for at least the most common controls (Toggle, Picker, Slider) to improve actionability from advisory to executable.

Define an explicit numbered workflow: e.g., 1. Check apple-design-context.md → 2. Ask diagnostic questions → 3. Recommend control with rationale → 4. Provide implementation snippet → 5. Verify accessibility compliance.

Remove the boilerplate 'When to Use' section and the marketing footer to improve conciseness.

Dimension	Reasoning	Score
Conciseness	The content is mostly efficient, presenting key principles as concise numbered items without over-explaining concepts Claude already knows. Minor verbosity exists in some descriptions (e.g., explaining what gauges and rating indicators are), and the trailing 'When to Use' section and marketing footer add no value.	4 / 5
Actionability	The skill provides guidance on which control to use for which scenario and includes an output format and diagnostic questions, but lacks any concrete code examples, SwiftUI snippets, or copy-paste ready implementations. It's more of a decision framework than executable guidance.	3 / 5
Workflow Clarity	The 'Questions to Ask' and 'Output Format' sections imply a workflow (gather info → recommend control → specify state/validation/accessibility), but the sequence is not explicitly laid out as steps. There are no validation checkpoints or feedback loops. For a non-destructive advisory skill this is acceptable but still lacks explicit sequencing.	3 / 5
Progressive Disclosure	The reference index table is well-structured with 14 clearly signaled one-level-deep references to specific topics. However, no bundle files were provided to verify these references actually exist, and the related skills section adds useful cross-references. Minor gap: the overview could more explicitly direct when to consult which reference file.	4 / 5
	Total	14 / 20 Passed

Description

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

This description is fundamentally flawed because it describes an internal procedural instruction rather than the skill's actual capabilities and purpose. It fails to communicate what the skill does, when it should be selected, or what domain it covers beyond a vague reference to Apple design context. Claude would have almost no basis for selecting this skill appropriately from a list of available skills.

Suggestions

Rewrite the description to clearly state what the skill does (e.g., 'Guides Apple platform UI/UX design following Human Interface Guidelines for iOS, macOS, watchOS, and tvOS apps').

Add an explicit 'Use when...' clause with natural trigger terms like 'Apple design', 'iOS UI', 'HIG', 'SwiftUI layout', 'app design guidelines'.

Move the procedural instruction about checking .claude/apple-design-context.md into the skill body rather than the description, as it is an implementation detail not useful for skill selection.

Dimension	Reasoning	Score
Specificity	The description contains no concrete actions or capabilities. It only describes a procedural instruction about checking a file and avoiding redundant questions, with no indication of what the skill actually does.	1 / 5
Completeness	The description fails to answer both 'what does this do' and 'when should Claude use it'. It only describes an internal behavior (check a file before asking questions) without explaining the skill's purpose or trigger conditions.	1 / 5
Trigger Term Quality	The only potentially useful trigger terms are 'apple-design-context' and the file path, but these are internal references rather than natural keywords a user would say. A user would likely say things like 'Apple design', 'iOS design', or 'HIG' but none of these appear.	2 / 5
Distinctiveness Conflict Risk	The mention of 'apple-design-context.md' provides some specificity, but the description is so vague about what the skill does that it could easily conflict with any Apple-related or design-related skill. The lack of concrete actions makes it hard to distinguish.	2 / 5
	Total	6 / 20 Passed

Validation

90%

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

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: skills/hig-components-controls/SKILL.md
Commit: 57c135b

Reviewed: 4 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.