App Store Preflight: An Agent Skill That Scans iOS and macOS Projects Before Submission

The rejection patterns this skill is built to catch

Apple's review process rejects apps for reasons that are largely predictable and largely documented. The project's premise is that those reasons can be enumerated as rules and checked mechanically before upload. The README frames it as catching 'potential App Store Review guideline violations before submitting their app' by scanning the Xcode project, source code, metadata and configuration files.

The audience is narrow and specific: iOS and macOS developers who already have a build and a set of App Store Connect metadata, and who want a pre-submission pass. It is not a general code quality tool. Every rule in the repository maps to a numbered Apple guideline, and the checks are about submission artefacts (review notes, subscription copy, privacy manifests, entitlements), not about whether your Swift compiles.

The rules are organised by category: metadata, subscription, privacy, design and entitlements. A few examples from the README show the flavour. The review_notes_new_submission rule targets guideline 2.1 and looks for incomplete review notes on a new submission, such as a missing screen recording, missing test credentials, or missing regional and regulatory information. The competitor_terms rule targets 2.3.1 and flags Android and Google Play references. The minimum_functionality rule targets 4.2 and flags WebView wrappers and apps with fewer than three screens. These are the kinds of findings a reviewer would raise in a rejection message, moved earlier in the pipeline.

How the agent reads your project: checklists, rules, and asc metadata

The mechanism is a set of markdown files that an AI agent loads and applies. The README describes a five-step flow: identify the app type and load the matching checklist from references/guidelines/by-app-type/, pull metadata with the asc CLI, scan against the rules in references/rules/, report findings with severity, affected files and resolution steps, then autofix and re-run the affected checks.

The by-app-type checklists are the routing layer. Ten are listed: all_apps.md for universal submissions, plus subscription_iap, social_ugc, kids, health_fitness, games, macos, ai_apps, crypto_finance and vpn. Alongside them, references/guidelines/ is described as a complete index of all 100+ Apple Review Guidelines. So the agent has two documents in play: a broad index of the guidelines themselves, and a narrower checklist for the category your app falls into.

The rules directory is the detection layer, and each rule is a markdown file with a fixed shape. The README shows the template: a title, the guideline number, a severity of REJECTION or WARNING, a category, then sections for What to Check, How to Detect, Resolution and Example Rejection. That structure is what makes the output presentable. A finding can cite the guideline, name the file, and propose a fix, rather than emitting a vague warning.

Metadata handling depends on the asc CLI. The README states that most metadata examples assume the canonical JSON layout written by asc metadata pull, and warns that if you are starting from fastlane metadata you should adapt the path examples or pull the canonical asc layout first. That is a real constraint, not a footnote: the rules that inspect metadata are written against one directory shape, and fastlane's shape is different.

Installing App Store Preflight and running a first scan

The skill installs through the skills CLI. One command, no build step.

npx skills add truongduy2611/app-store-preflight-skills

After that, the skill files are available to your agent runtime. The README points to SKILL.md as the full set of AI agent instructions, so that is the file to read first if you want to know what the agent will actually do.

The metadata side needs the asc CLI, which the README says installs with Homebrew.

brew install asc

The scan itself starts with a metadata pull. The README gives this exact form, with the app ID and version substituted:

asc metadata pull --app "<APP_ID>" --version "<VERSION>" --dir ./metadata

That writes the canonical JSON layout into ./metadata, which is the layout the rule files expect. If you already have metadata from another source, the README suggests the asc-metadata-sync skill as an alternative path. What you should see after the pull is a populated metadata directory that the agent can read alongside your Xcode project.

Adding a rule of your own is a matter of dropping a markdown file into the right subdirectory under references/rules/ and following the template. The README's example uses the same headings as the built-in rules.

# Rule: [Short Title]
- **Guideline**: [Apple Guideline Number]
- **Severity**: REJECTION | WARNING
- **Category**: metadata | subscription | privacy | design | entitlements

## What to Check
## How to Detect
## Resolution
## Example Rejection

Note that the template uses REJECTION and WARNING as the only two severity values, and a fixed list of five categories. A rule that does not fit one of those categories has nowhere to go in the current layout.

Where the skill stops: coverage, metadata shape, and false confidence

The rule set is not exhaustive, and the README does not claim it is. It lists roughly a dozen rules across five categories. Apple's guidelines run past 100 entries, and the project's own guideline index acknowledges that breadth, but the detection layer is much smaller than the index. A clean scan means the listed rules did not fire. It does not mean the submission is compliant.

The metadata dependency is the sharpest practical limitation. If your release process writes metadata through fastlane, the rule examples will not match your paths until you pull the canonical asc layout or adapt them. That is stated plainly in the README, and it means the metadata rules are effectively inert until the layout is right. A team that never runs asc metadata pull gets the source-code and configuration checks but loses the metadata ones.

The autofix step deserves caution. The README lists 'Autofix + Validate' as the fifth stage, applying fixes and re-running affected checks. An agent editing review notes, subscription copy or project configuration is making changes that affect a live submission. The README does not document rollback, a dry-run mode, or a diff review step before fixes are applied. Treat autofix as a change to review, not a change to trust.

Finally, the whole thing is a skill, which means it needs an agent runtime that can load skills. Without that, the repository is a well-organised set of markdown files you would have to read and apply by hand.

App Store Preflight versus fastlane precheck and manual guideline review

The closest established alternative is fastlane's precheck action, which also scans app metadata for rejection risks before submission. The difference is in what drives the checks. precheck is a deterministic Ruby action with a fixed set of validations baked into the tool; you run it and you get its findings. App Store Preflight is a set of instructions for a language model, so the checks are whatever the rule files describe and the agent interprets, and the output is prose with severity, file references and suggested resolutions rather than a fixed report format.

That difference cuts both ways. A model-driven scan can reason about context, which a fixed validator cannot: it can read your review notes and judge whether they explain an external service, rather than pattern-matching a string. It can also be inconsistent between runs, and its findings are only as good as the rule file it is applying. precheck gives you the same answer every time, including the same blind spots.

The other alternative is the one most teams actually use: reading the guidelines yourself before submission. That is slower and depends on someone remembering guideline 5.2.5 covers Apple device images in your icon. The skill's value is that the checklist is written down and applied consistently. Its cost is that you now maintain a rule set that Apple can invalidate with a guideline update, and nothing in the repository watches Apple's guidelines for changes.

Maintenance, licence, and what a fork inherits

The repository is MIT licensed, which permits commercial use, modification and redistribution provided the licence text is retained. The top-level entries are LICENSE, README.md, SKILL.md and references/, so the licence file ships with the skill. Nothing in the README describes a hosted service, telemetry, or a paid tier, so there is no separate commercial agreement to review. This is a description of the licence terms, not legal advice.

The last push to the default branch was on 2026-05-29. The repository is not archived, but that date is roughly four months before the point at which this is being written, so treat the rule set as a snapshot rather than a feed. Apple revises its review guidelines periodically, and no mechanism in the repository pulls those revisions in. If you fork it to add rules for your own app category, you are also taking on the job of tracking guideline changes.

Upgrade cost is low in the mechanical sense: the skill installs through npx skills add, so re-running that command picks up whatever is on the default branch. The real cost is re-validating your own added rules against the updated files, since a rule that references a renamed path under references/rules/ will silently stop matching.

Editorial conclusion

Adopt App Store Preflight if your team ships iOS or macOS apps regularly, already uses the asc CLI for metadata, and wants guideline checks to run from the same agent that writes your code. Skip it if you have no agent runtime that loads skills, if your metadata lives only in fastlane without a canonical asc pull, or if you expect the tool to prove a submission will pass. Before relying on it, install it, run asc metadata pull against a real version, and read SKILL.md plus the by-app-type checklist for your category to see which rules actually fire on your project.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. truongduy2611/app-store-preflight-skills on GitHub