HIGAgentSkills: 157 distilled Apple HIG references, a /duo workflow, and an opt-in enforce mode

One request loads 16 foundations and a single hop of related guidance

The premise is that Apple's source guidance is authoritative and too large to paste into a conversation. The package answers with 157 source-reviewed references covering iOS, iPadOS, macOS, tvOS, visionOS and watchOS, and with a loading discipline instead of one giant file. For an ordinary question the agent loads the 16 foundations, the platform and device references relevant to the request, the component references that match it, and one hop of related guidance:

Use apple-hig to review the navigation and accessibility of this iOS app.

The optional routing helper at scripts/hig_route.py resolves literal matches, while the agent passes any explicit topic exclusions separately; hosts with file access but no helper follow the same protocol by hand. Setup and help questions do not load the corpus at all, which keeps the install check cheap. Answers quote the operative source clause before applying it, and the quote keeps the conditions attached to the rule, the strength Apple gives it, since a requirement and a suggestion do not read the same, and the exact specifications where the page gives numbers. Ordinary guidance never starts enforcement, so asking a design question does not turn into a review with a score attached.

Install by copy-paste prompt, or by unzipping the whole apple-hig folder

There are two documented install paths and neither needs a server. The short one is a message you hand to your agent:

Install the apple-hig skill for me from https://github.com/justinwetch/HIGAgentSkills.git
It includes a required /duo slash command in commands/duo.md. If /duo isn't
available after installing the skill, copy that file into your custom slash-command
or custom prompt directory, then confirm /duo works.

The manual path is to extract the archive's complete apple-hig/ folder into your agent's skills directory, either scoped to one project or to all local projects. That location is named by your agent's documentation, not by this repository. Agents without skill discovery need explicit access to the extracted SKILL.md and its sibling files. The folder has to stay intact: SKILL.md, the README, the routing index, the references, the commands/ folder and the two helper scripts belong together, because a routing index pointing into a references tree that has been split up resolves to nothing. After that comes the /duo command, which is installed as a file rather than as a switch inside the skill.

Upgrades replace the folder, because the references moved out of distilled/

Upgrading means replacing, not merging. Anyone who installed the June release is told to replace the whole skill folder, because the references moved from distilled/ into references/hig/ in this release. Merging the two would leave a directory of June files beside a directory of September files with the routing index pointing into a mix. The same caution applies on the copy-paste path: after replacing the folder, check whether another copy with the same name is installed elsewhere, because two installed copies sharing one name is the outcome that instruction is aimed at. The repository's top level is small enough to read directly: README.md, SKILL.md, process.md, routing-index.md, then the commands/, references/, sources/, scripts/, tests/ and docs/ directories, with distilled/ still present for the older layout. The dated release assessment and verification for this build live under docs/release-2026-09-27/, which is where to look if you would rather see what was checked before the 2026-09-27 release than take the published totals on trust.

/duo is a slash command file, and some hosts never pick it up

The Duo workflow arrives as a file, and that is where installs most often go wrong. The command lives at commands/duo.md inside the skill folder. Some agents pick that file up from the skill folder on their own; others ignore it and need it copied into their custom slash-command or custom prompt directory, whose path your agent's documentation names. If /duo still does not appear after a restart, copy it there. The failure is quiet in a specific way: the ordinary half of the package keeps working, so 157 references still answer ordinary questions and nothing warns you that the second half is missing. There is a documented fallback for that state. Asking it to use apple-hig in Duo mode for a named journey starts the same workflow while you fix the install, and the journey can be named inline the way a slash command argument would have been. The two Duo files, references/duo.md for the workflow and references/duo-checklist.md for the checks, load only in Duo mode, so an ordinary question never pays for them.

Duo mode walks one journey through five fixed stages and leaves no mockups

Duo mode takes one named journey rather than the whole app, and you invoke it like this:

/duo the library and reading flow

Five stages run in a fixed order. Assess looks at the current screens, bars and layouts in your code. Match puts them against Apple's iPhone Duo guidance and tech talks and brings the sources along. Decide recommends options and stops for your choices, offering SwiftUI previews first. Build makes the changes natively, in Apple's order, so the work lands in your own code as SwiftUI or UIKit rather than as a picture of a redesign. Verify runs them in the Device Hub iPhone Duo simulator where available and reports which checks it could not run, so a missing simulator shows up as a gap in the output rather than a quiet pass. Progress is kept in a short duo-notes.md in your project, so a later /duo continue resumes where the previous pass stopped. The constraint the project states most plainly is what the mode never does: it produces no HTML and no web mockups. A redesign for a folding phone is judged against the hardware's displays, poses, reserved regions and side-mounted bars, and a mockup in a browser cannot be measured against any of them.

An enforce pass needs 90 out of 100 and will answer needs changes instead

Enforce mode is opt-in and named out loud, for example by asking it to review and fix an interface in enforce mode. What changes is the shape of the work: two independent reviewers score the interface against the HIG, the agent repairs what they find, and the pair re-reviews, for up to three cycles. The bar for a pass is 90 out of 100 or better, with complete evidence and no unresolved material finding. Anything short of that returns needs changes or blocked, which is the useful part of the design, because a score without evidence behind it is just a number. Three things have to exist before any of it runs: subagents for the two independent passes, Python 3.10 or newer for the scoring step, and a way to observe the actual artifact rather than a description of it. The procedure at references/enforce.md and the data format at references/enforce-format.md are loaded only when enforcement is requested, so the ordinary path stays cheap. Ordinary guidance never begins enforcement on its own, whatever the wording of the question.

Distillation stopped at 65.6% because fidelity beat the 75% target

The compression figures are the part to argue with, and the project argues them first. Rewriting Apple's wording took the corpus from 261,621 words down to 90,027, which is 65.6% shorter, and that is short of the roughly 75% it set as its target. The reason given is that fidelity took priority: exact values, conditions, how strongly Apple phrases a rule, API names and scoped exceptions were all kept, so the cut lands on explanation rather than on the part a reader would have to look up again. The per-topic spread is uneven and is stated as such, with short, rule-dense topics stopping at 57 to 68 percent. Every one of the 157 topics passed independent source review, and each topic rewritten during the September 23 to 24 redistillation was re-reviewed against Apple's source. Token totals are published too, in two tokenizers, because a word count hides the difference: the complete reference files come to 163,033 o200k_base tokens or 162,491 cl100k_base tokens, while the 16 foundations alone come to 27,096 or 26,936. That gap is the reason loading discipline matters more here than total size.

Setup verification is a prompt, because there is no status page

Verification is a prompt rather than a status page, which fits a package with no onboarding website, no browser intake, no dashboard and no setup server. The agent works in your conversation and your project, and ordinary guidance needs file access only; Python 3.10 or newer is what enables the optional routing helper and what enforce scoring requires, using whichever of python3 or python the host exposes. After installing, hand the agent this:

Find the installed apple-hig skill. Read its SKILL.md and report its absolute
location, release version and supported modes, and whether /duo is available
as a slash command. Do not load the HIG references or start a review for this
setup check.

What should come back is release 2026-09-27, ordinary HIG guidance, Duo mode with /duo available, and opt-in enforce mode. Anything else, including a missing skill, a missing /duo, or a version that does not match, points at the installation location rather than at the content: check where the folder landed and refresh or restart the host. The honest caveat sits in the same paragraph, since automatic discovery has not been tested in every host. That is also why asking for the paths is the right first move on a new machine, and why nothing in the README settles redistribution terms for a corpus this size when the repository's top level carries no LICENSE file.

Editorial conclusion

apple-hig earns its place for an agent that has to answer repeated Apple platform design questions and cannot load Apple's own wording every turn: 157 reviewed references, a 16 file foundation set, and a routing discipline keep the ordinary path small while preserving the exact values and conditions that make a HIG clause usable. It is a poor fit if you want a design opinion rather than a sourced clause, if your agent cannot read files from its skills directory, or if you need a guaranteed verdict on an interface, since an enforce run that misses the bar returns needs changes or blocked rather than a fix. Check three things before relying on it: that your host actually discovered commands/duo.md, that the installed copy is the 2026-09-27 release rather than a June folder merged into it, and that a 65.6% compression rate is acceptable when the project set out for 75%.

Frequently asked questions

Official sources

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