HIGAgentSkills: Apple HIG distilled into an agent skill

The context problem this skill exists to solve

Apple's Human Interface Guidelines are authoritative and, in the project's own words, too large and too prose-heavy to load directly into an agent's context. An agent asked about a macOS toolbar or a visionOS ornament has two bad options: answer from parametric memory and risk inventing a measurement, or retrieve the full HIG page and spend a large share of the window on framing paragraphs, change history, and repeated examples. HIGAgentSkills takes the second option and compresses it. The README describes the output as a corpus that fits within a practical context budget and gives the agent precise, citable answers rather than paraphrased recollections. That is the whole pitch, and it is a narrow one. This is not a design system, not a component library, and not a linter. It is a retrieval corpus with a loading protocol attached, aimed at anyone building an agent that answers Apple platform design questions and needs the answer to cite a real number.

Four tiers, seven steps, and a keyword routing index

The mechanism is a tiered corpus plus a routing table. SKILL.md defines a seven-step loading protocol: parse the request for platforms, component names and framework references; load all 16 tier-1 foundation files on every invocation; load the matching designing-for-[platform] file; keyword-scan the request against routing-index.md and load all tier-3 matches; expand one hop through each loaded file's related: frontmatter; load tier-4 files only on a direct keyword match; then answer citing exact values from loaded files. The corpus is split into tier 1 foundations (16 files, always loaded), tier 2 platform overviews (7), tier 3 components, patterns and technologies (103), and tier 4 niche and platform-specific controls (30). routing-index.md maps 1,057 trigger keywords to files across all four tiers and is described as auto-generated. Each distilled file carries YAML frontmatter with topic, tier, platforms, category, triggers and related fields, which is what makes step five possible: the agent can walk the related graph without loading every file. The interesting design choice is that tier 1 is unconditional. Sixteen files load whether or not the question touches them, which guarantees grounding in Apple's Design Principles but sets a floor you pay on every call.

The token floor is real and the README states it

According to the README, the floor cost per invocation is approximately 33,600 rough tokens for tier-1 files plus the routing index. Typical queries load 20 to 30 files and land between roughly 34,000 and 55,000 tokens. The project frames that as within a practical budget on a 200k context window, which is fair, but the framing hides the shape of the cost. The floor is not small and it is not optional. A single question about a watchOS complication pays for the same 16 foundation files as a question about macOS window toolbars. On a 200k window that leaves plenty of room, but an agent that already carries a large system prompt, tool schemas, or conversation history is spending a meaningful slice of its budget before the user's question is even parsed. The full corpus is roughly 140k rough tokens, so the routing index is doing real work: without it, loading everything would consume most of a 200k window. The tiering is what keeps the skill usable, and the tier-1 floor is the price of it.

Packaging, install, and the folder-name constraint

The README is explicit that production testing should use the script-generated runtime zip rather than the full repository. Build it with python scripts\package_runtime_zip.py (the README shows a PowerShell invocation), which writes release/apple-hig.zip. The archive contains exactly one top-level folder named apple-hig/ holding SKILL.md, README.md, routing-index.md and distilled/*.md. The packaging script writes forward-slash paths only, omits directory metadata, validates archive paths, and excludes hidden files, macOS resource forks, sources/, scripts/, process.md, .gitignore, raw Apple captures, rendered pages, caches and git metadata. That exclusion list is the part worth reading twice: the raw captures and verification material are what you would need to audit the distillation, and they are deliberately not shipped to production agents. To test locally, unzip or install the apple-hig/ folder into your agent skills directory, then ask Apple platform design questions that should trigger tier-1 foundations, platform files and component-specific files. One constraint is easy to miss and the README calls it out: the installed directory must be named apple-hig so the folder name matches the name: apple-hig metadata in SKILL.md. Rename it during extraction and the skill will not trigger. There is also a copy-paste install prompt in the README, a single line telling an agent to install the skill from the repository URL, which is convenient and also the kind of instruction you should read before pasting into an agent with shell access.

What the distillation method gives up

Each reference file was distilled from the corresponding Apple HIG source page targeting a 75% reduction in word count. The README lists what was preserved: specific measurements, sizes and spacing values; API names, class names and framework identifiers; platform distinctions and per-platform behavioral rules; and do/do not rules stated as direct directives. Removed: introductory framing, change history, repetitive examples, and prose that restated rules already expressed concisely elsewhere. Each compression pass was followed by an evaluation step to confirm no substantive rules or specifications were lost, with files accepted only when the distilled version could answer the same design questions as the source. That is a reasonable method and the acceptance criterion is the right one. The limitation is structural rather than procedural: change history is gone, so the corpus is a snapshot. The README dates the refresh to 2026-06-09 and describes it as updating the skill against the HIG corpus captured on that date. If Apple revises a guideline, nothing in the installed skill tells you the previous rule existed or when it changed. For a design reference that is usually fine, but for an agent answering a question about deprecation or migration it is a blind spot, and the agent has no way to signal that its answer is stale.

Maintenance, verification, and the licence gap

The repository's licence is not stated in the material available here, and the README contains no licence section. That is the first thing to resolve, because the content is explicitly a derived work: the attribution section states it is distilled from the Apple Human Interface Guidelines at developer.apple.com/design/human-interface-guidelines and that the repository is an independent reference tool not affiliated with or endorsed by Apple. Distillation reduces word count; it does not change provenance. How Apple's HIG terms interact with redistributing a compressed derivative is a question for someone qualified to answer it, not something to infer from the README. On the maintenance side, the project does ship an audit trail: the 2026-06-09 refresh notes a current-source review completed for every inventoried source page and a full-corpus audit and continuity sampling recorded under sources/apple-hig-2026-06-09/verification/. That directory is excluded from the runtime zip, so the evidence exists in the repository and not in the artifact you install. If you need to justify the corpus to someone, you are reading the repo, not the zip. Upgrade cost is tied to Apple's release cadence rather than to code: routing-index.md is auto-generated and the tier counts (16/7/103/30) are the contract the loading protocol depends on, so a refresh that adds files changes the token floor. The README gives no versioning scheme and no changelog beyond the dated refresh, so pinning to a specific commit is the only reproducible option.

Where a general documentation tool fits better

The obvious alternative is not another Apple-specific skill but a general retrieval pipeline over the live HIG site: fetch the relevant page at query time, chunk it, and let the agent read the part it needs. The difference in approach is where the compression happens. HIGAgentSkills compresses once, at build time, into a fixed corpus with a hand-maintained keyword index, which makes queries cheap and deterministic and makes the corpus stale the moment Apple publishes. A live-fetch pipeline compresses at query time, so it is always current and pays retrieval latency and parsing cost on every call, and it inherits the full prose the project set out to remove. The trade is currency against token efficiency, and neither wins universally. If your agent answers design questions frequently, the fixed corpus amortises; if it answers them occasionally and correctness on recent changes matters more than token spend, fetching the source page is the better default. The tier-1 floor of roughly 33,600 tokens is the number that decides it for most teams: you are paying that on every invocation whether the question needs Apple's Design Principles or not.

Editorial conclusion

Adopt it if you are building an agent that answers Apple platform design questions and you need citable measurements and API names rather than paraphrased recall. Do not adopt it if you cannot resolve the licence question, since the repository ships no licence file and the content is distilled from Apple's HIG. Before installing, run python scripts/package_runtime_zip.py, confirm release/apple-hig.zip contains exactly one top-level apple-hig/ folder, and verify that the installed directory name matches name: apple-hig in SKILL.md, because the README states the skill will not trigger otherwise.

Official sources

1. Issues
2. justinwetch/HIGAgentSkills on GitHub
3. README