hig-project-context

Create or update a shared Apple design context document that other HIG skills use to tailor guidance.

Quality

58%

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-project-context/SKILL.md

Quality

Content

63%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 reasonably well-structured skill for creating a shared design context document. Its strengths are the auto-discovery approach (checking existing project files before asking questions) and the concrete template output. Weaknesses include some verbosity in the questionnaire sections, lack of executable discovery commands, and the absence of a validation/confirmation step after document generation.

Suggestions

Add specific grep/find commands for the auto-discovery steps (e.g., `grep -r 'import SwiftUI\|import UIKit' --include='*.swift'`) to make the discovery phase more actionable.

Add a confirmation step after generating the context document where Claude presents the completed document to the user for review before writing it.

Trim the questionnaire sections by removing options Claude can infer (e.g., don't list all six Apple platforms—just ask which platforms are targeted).

Remove the generic 'When to Use' section and the marketing footer, which add no value for Claude.

Dimension	Reasoning	Score
Conciseness	The skill includes some unnecessary verbosity—the full 7-section questionnaire and the complete markdown template are somewhat lengthy, though most content is genuinely useful context-gathering guidance. The auto-discovery section is efficient, but the questionnaire sections explain things Claude could infer (e.g., listing out every Apple platform). The trailing marketing line and generic 'When to Use' section waste tokens.	3 / 5
Actionability	The skill provides a concrete template to generate, clear file paths, and specific auto-discovery steps (check README.md, Package.swift, Info.plist, etc.). However, it lacks executable code examples—e.g., actual grep commands for the accessibility audit, or specific patterns to look for in import statements. The guidance is mostly concrete but has minor gaps in execution specifics.	4 / 5
Workflow Clarity	The workflow has a clear sequence: auto-discover → present findings → ask for missing info → generate document. The update workflow is also clearly sequenced (read → ask → update → preserve). However, there's no explicit validation step to verify the generated document is complete or well-formed, and no feedback loop for confirming the output with the user before finalizing. Since this isn't a destructive operation, the missing validation doesn't cap the score at 3.	4 / 5
Progressive Disclosure	The skill references related skills (hig-platforms, hig-foundations, etc.) which is good for navigation, but all content is inlined in a single file with no bundle files to support it. The full template and all 7 questionnaire sections are inline when some could be separated. For a skill of this length (~120 lines of content), the structure is adequate but not optimally organized.	3 / 5
	Total	14 / 20 Passed

Description

53%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 identifies a specific domain (Apple design context for HIG skills) and two actions (create/update), giving it moderate specificity and distinctiveness. However, it lacks an explicit 'Use when...' clause and misses natural trigger terms users would say, which limits its effectiveness for skill selection among many options.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user describes their app, target platform, or design preferences that should inform HIG guidance across sessions.'

Include natural trigger terms and synonyms such as 'Human Interface Guidelines', 'iOS', 'macOS', 'app context', 'design system', 'platform targeting'.

Briefly elaborate on what the context document contains (e.g., 'Captures app type, target platforms, design preferences, and branding details') to improve specificity.

Dimension	Reasoning	Score
Specificity	Names the domain (Apple design context document) and describes two concrete actions (create or update), but doesn't elaborate on what the document contains or what 'tailoring guidance' entails in practice.	3 / 5
Completeness	The 'what' is reasonably clear (create/update a shared Apple design context document), but there is no explicit 'when' clause. The phrase 'that other HIG skills use to tailor guidance' hints at purpose but doesn't tell Claude when to select this skill.	3 / 5
Trigger Term Quality	Includes some relevant terms like 'Apple design', 'HIG', and 'context document', but misses natural user phrases like 'design system', 'Human Interface Guidelines', 'app context', 'platform', or 'iOS/macOS'. Users may not naturally say 'shared design context document'.	3 / 5
Distinctiveness Conflict Risk	The description carves out a fairly specific niche — a shared context document for HIG skills — which is unlikely to overlap with most other skills. However, it could potentially conflict with other Apple/HIG-related skills since the boundary between this and those other HIG skills isn't fully explicit.	4 / 5
	Total	13 / 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-project-context/SKILL.md
Commit: fbdfd63

Reviewed: 1 day 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.