flutter-setting-up-on-macos

flutter/agent-plugins · 7.8k installs · 3.1K stars

Skill

Marked Command Execution · External Downloads

Install

In your shell

npx -y skills add flutter/agent-plugins --skill flutter-setting-up-on-macos --agent claude-code

Run in a terminal. Claude loads the skill when a task calls for it. Check the repo's README before you run it.

SKILL.md

Ensure the following baseline requirements are met before configuring the macOS-specific toolchain:

macOS desktop development requires specific Apple toolchains to compile and debug native Swift and Objective-C code.

Xcode: Required for compiling macOS desktop applications.
CocoaPods: Required for managing native dependencies used by Flutter plugins.

Copy and follow this checklist to configure the macOS build environment.

Install Xcode: Install the latest version of Xcode from the Mac App Store or the Apple Developer portal.
Configure Command-Line Tools: Link the Xcode command-line tools to the installed Xcode version. Run the following command in the terminal:
```
sudo sh -c 'xcode-select -s /Applications/Xcode.app/Contents/Developer && xcodebuild -runFirstLaunch'
```
Conditional: If Xcode is installed in a custom directory, replace /Applications/Xcode.app with the correct absolute path.
Accept Xcode Licenses: Accept the required developer licenses by running:
```
sudo xcodebuild -license
```
Read and agree to the prompts.
Install CocoaPods: Install CocoaPods to handle native macOS plugin dependencies.
```
sudo gem install cocoapods
```
Conditional: If CocoaPods is already installed, ensure it is updated to the latest version (sudo gem update cocoapods).

Execute this feedback loop to ensure the environment is correctly configured for macOS desktop development.

Run Validator: Execute the Flutter diagnostic tool with verbose output:
```
flutter doctor -v
```
Review Errors: Check the Xcode section in the output.
Fix & Retry: If errors or missing components are reported under the Xcode section, resolve them according to the output instructions, then re-run flutter doctor -v until the Xcode section passes.
Verify Device Availability: Confirm that Flutter recognizes the macOS desktop as a valid deployment target:
```
flutter devices
```
Success Criteria: The output must contain at least one entry with macos listed as the platform.

If the validation workflow fails, apply the following resolutions:

Missing Command-Line Tools: If flutter doctor reports missing tools, ensure the xcode-select command was run with sudo and points to the correct .app directory.
CocoaPods Not Found: If CocoaPods is installed but not detected, verify that your Ruby gem binary path is included in your shell's PATH environment variable.
Device Not Listed: If flutter devices does not list macos, ensure desktop support is enabled in your Flutter configuration:
```
flutter config --enable-macos-desktop
```