macOS System Migration Assistant

A two-phase design: old-system collection → new-system restoration. The two phases are connected through a JSON manifest file.

Prerequisites (Do This First)

Make a full Time Machine backup on the old system first. This is the migration's safety net—any problem on the new system can be recovered from this full backup. The restoration phase also reads data directly from the Time Machine mount point.

Do not begin the migration without a full Time Machine backup.

Runtime Mode Detection

Whether to collect or restore depends on only one signal: whether the manifest file exists.

bash

ls ~/migration-manifest.json 2>/dev/null

Condition	Mode
No manifest file	Collection mode (on the old system, generate a manifest)
Manifest file exists	Restoration mode (on the new system, read the manifest and restore)

Time Machine is only the data source for the restoration phase and does not participate in mode detection. The user can also explicitly specify: “Collect,” “Back Up,” “Restore,” or “Migrate.”

Step Zero: Homebrew Check (Required in Both Modes)

bash

which brew && brew --version || echo "NOT_INSTALLED"

Installed → Continue
Not installed → Guide the user to manually run the installation command in a terminal. This step requires an administrator password (sudo) and cannot be completed silently:
bash
```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
After installation, follow the instructions to add brew to PATH (Apple Silicon:
```
eval "$(/opt/homebrew/bin/brew shellenv)"
```
), then continue.

Mode A: Collection on the Old System

Run this on the old system to scan all software, configuration, and development environments and generate

~/migration-manifest.json

A1. Homebrew Packages

bash

brew list --formula
brew list --cask
brew tap

A2. System Applications

bash

ls /Applications/
ls ~/Applications/ 2>/dev/null

Compare the results with the Homebrew cask list and mark which applications were installed through Homebrew and which were installed manually or from the App Store.

A3. Mac App Store Applications

bash

mas list 2>/dev/null || echo "mas not installed"

mas

is not installed, ask the user whether to install it (

brew install mas

A4. npm Global Packages

bash

npm ls -g --depth=0 2>/dev/null

A5. uv Tools

bash

uv tool list 2>/dev/null

A6. pip/pipx Packages

bash

pip list 2>/dev/null
pipx list 2>/dev/null

A7. Go Global Tools

bash

ls ~/go/bin/ 2>/dev/null

A8. Configuration File Scan

Scan dotfiles and configuration directories under the home directory:

bash

ls -la ~/

Focus on collecting:

Shell:

.zshrc

.zshenv

.zprofile

.bashrc

.bash_profile

Git:
```
.gitconfig
```
,
```
.gitignore_global
```
SSH:
```
.ssh/
```
Editors:
```
.claude/
```
,
```
.codex/
```
,
```
.config/
```
,
```
.cursor/
```
,
```
.zed/
```
Containers:
```
.docker/
```
,
```
.kube/
```
Package managers:
```
.npm/
```
,
```
.nvm/
```
,
```
.bun/
```
,
```
.cargo/
```
,
```
.rustup/
```
Other application configurations:
```
.SwitchHosts/
```
,
```
.ollama/
```
,
```
.syncthing/
```
, etc.

Ask before collecting sensitive data:

.ssh/

(private keys), tokens that may exist in dotfiles,

.aws/

.kube/

, keychains, and similar key-level information are highly sensitive. Before collecting these items, ask the user whether they should be included:

User agrees → Collect them normally and explicitly warn the user: “The manifest and backup contain private keys and credentials. When transferring, storing, or sending them through cloud storage or chat tools, take care not to disclose them.”
User declines → Skip these items and record them in the manifest as
```
"skipped_sensitive": [...]
```
so the user can migrate them manually later. They will also be listed again in the discrepancy report.

A9. LaunchAgents (Startup Services)

bash

ls ~/Library/LaunchAgents/

A10. User Project Directories

List non-dotfile top-level directories under the home directory:

bash

ls -d ~/*/ 2>/dev/null

Exclude system directories such as Library, Applications, and Public, and record user-created project and data directories.

A11. Shell Environment

bash

# 当前 shell 版本
zsh --version
# Homebrew 路径 / 版本管理器（nvm、fnm 等）配置
grep -iE 'brew|nvm|fnm' ~/.zshrc

A12. Other Easily Missed Items

These categories are most commonly missed during migration and can be particularly troublesome to recover:

bash

# 编辑器扩展
code --list-extensions 2>/dev/null
cursor --list-extensions 2>/dev/null

# 自购/自装字体
ls ~/Library/Fonts/ 2>/dev/null

# 定时任务
crontab -l 2>/dev/null

# 手动装到非 Homebrew 路径的命令行工具
ls /usr/local/bin/ 2>/dev/null
ls /opt/ 2>/dev/null

System preferences (
defaults
) are extensive and highly dependent on the machine model, so they are not collected automatically. If the user cares about them, remind the user in the restoration discrepancy report to verify them manually, including the keyboard, trackpad, Dock, shortcuts, and other settings.

A13. Generate the Manifest File

Write all the information above into

~/migration-manifest.json

json

{
  "version": 1,
  "captured_at": "2026-06-28T16:00:00+08:00",
  "source_macos": "15.5",
  "source_hostname": "old-macbook",

  "homebrew": {
    "taps": ["user/repo", "..."],
    "formulas": ["git", "node@22", "..."],
    "casks": ["1password", "docker-desktop", "..."]
  },

  "applications": {
    "homebrew_casks": ["claude", "firefox", "..."],
    "app_store": [{"id": 123456, "name": "App Name"}],
    "manual": ["Final Cut Pro.app", "..."]
  },

  "package_managers": {
    "npm_global": ["@anthropic-ai/claude-code", "..."],
    "uv_tools": ["nano-pdf", "..."],
    "pip_packages": ["package1", "..."],
    "go_binaries": ["tool1", "..."]
  },

  "configs": {
    "dotfiles": [".zshrc", ".gitconfig", ".ssh", "..."],
    "config_dirs": [".claude", ".codex", ".config", ".docker", "..."],
    "app_support_keys": ["Syncthing", "obs-studio", "..."]
  },

  "editor_extensions": {
    "vscode": ["ms-python.python", "..."],
    "cursor": ["..."]
  },

  "fonts": ["MyFont.otf", "..."],
  "crontab": "<crontab -l 原文，无则空>",
  "manual_bins": ["/usr/local/bin/foo", "/opt/bar", "..."],

  "launch_agents": ["com.github.syncthing.plist", "..."],

  "user_dirs": ["Projects", "Sites", "..."],

  "shell": {
    "shell": "zsh",
    "brew_in_path": true,
    "nvm_installed": true,
    "custom_env_vars": {}
  },

  "skipped_sensitive": []
}

A14. Collection Complete

Output a manifest summary and prompt the user:

✅ 采集完成！清单已保存到 ~/migration-manifest.json

采集内容：
- Homebrew: X taps, Y formulas, Z casks
- 应用: X 个 Homebrew, Y 个 App Store, Z 个手动安装
- npm 全局包: X 个
- 配置文件: X 个 dotfiles, Y 个配置目录
- 编辑器扩展: X 个 / 字体: Y 个 / 定时任务: 有/无
- 自启动服务: X 个
- 用户目录: X 个
- 跳过的敏感项: X 个（用户选择不采集）

⚠️ 若采集了 .ssh / dotfiles 中的凭据，清单与备份含私钥，传输存放注意不要外泄。

下一步：确认已有 Time Machine 全量备份，将 migration-manifest.json 复制到新系统，
再次运行此 skill。

Mode B: Restoration on the New System

Run this on the new system to read

migration-manifest.json

and restore the system step by step.

B0. Obtain the Manifest

bash

ls ~/migration-manifest.json

If it does not exist:

找不到 migration-manifest.json。

请将旧系统上采集的清单文件复制到新系统的 home 目录：
  scp old-mac:~/migration-manifest.json ~/migration-manifest.json

或者手动指定路径。

B1. Homebrew Software Installation

Prerequisite: Homebrew has been confirmed as installed in Step Zero. The user must manually enter the password to install it. This step can run only after Homebrew is ready.

Read the

homebrew

field from the manifest.

bash

# 添加 taps（逐个）
brew tap <user>/<repo>

# 信任第三方 taps
brew trust <user>/<repo>

# 安装 formulas（批量，失败不回滚整批）
brew install <formula1> <formula2> ...

# 安装 casks（逐个，避免回滚）
for cask in <cask1> <cask2> ...; do
  brew install --cask "$cask" 2>&1 | tail -3
done

Record anything that could not be installed, such as packages requiring sudo or those that failed due to network issues, and present it to the user in the discrepancy report in B7.

B2. Other Package Managers

Read the

package_managers

field from the manifest.

bash

# npm
npm install -g <pkg1> <pkg2> ...

# uv
uv tool install <pkg1> <pkg2> ...

# pip（如果需要）
pip install <pkg1> <pkg2> ...

# go binaries
go install <pkg1>@latest <pkg2>@latest ...

B3. Configuration File Restoration

Read the

configs

field from the manifest.

There are two possible data sources, in priority order:

Copy directly from Time Machine if it is mounted
Provided manually by the user if the manifest was obtained through another method

bash

TM="<Time Machine 用户目录路径>"
LOCAL="/Users/<username>"

# dotfiles
rsync -av --ignore-existing "$TM/.zshrc" "$LOCAL/"
rsync -av --ignore-existing "$TM/.gitconfig" "$LOCAL/"
rsync -av --ignore-existing "$TM/.ssh/" "$LOCAL/.ssh/"

# 配置目录
for dir in .claude .codex .config .docker .SwitchHosts ...; do
  rsync -av --ignore-existing "$TM/$dir/" "$LOCAL/$dir/"
done

After restoring
.ssh/
, verify the permissions:
chmod 700 ~/.ssh && chmod 600 ~/.ssh/id_*
. If Time Machine is unavailable, ask the user to provide the source path for the configuration files.

B4. Key Library Subdirectories

Restore these from Time Machine if available:

Subdirectory	Command	Description
Preferences	`cp -rn`	Application preferences
Keychains	`cp -rn`	Keychains
Containers	`cp -rn`	Sandboxed application data
Group Containers	`cp -rn`	Shared containers
Mail	`cp -rn`	Mail data
Safari	`cp -rn`	Bookmarks/history

rsync
reports
io_read_flush
errors on Time Machine APFS snapshots. Use
cp -rn
for Library subdirectories.

B5. LaunchAgents (Startup Services)

Read the

launch_agents

field from the manifest.

Check and create the corresponding plist files one by one, and then run

launchctl load

B6. Restoration of Other Easily Missed Items

These correspond to A12 in the collection phase:

bash

# 编辑器扩展（逐个装）
for ext in <清单 editor_extensions.vscode>; do code --install-extension "$ext"; done

# 字体
rsync -av --ignore-existing "$TM/Library/Fonts/" "$LOCAL/Library/Fonts/"

# 定时任务：先看新机器有没有现成的，再决定是否合并写入，避免覆盖
crontab -l 2>/dev/null

Manually installed tools in
/usr/local/bin
and
/opt
cannot be restored automatically. List them in the discrepancy report in B7 and remind the user about them.

B7. Handling Items That Could Not Be Installed

Compare the manifest with the actual installation results and output the differences:

## 还原差异报告

### ❌ 安装失败（需手动处理）
- docker-desktop: 需要 sudo → 手动执行 `brew install --cask docker-desktop`
- tailscale-app: 需要 sudo → 手动执行 `brew install --cask tailscale-app`
- android-platform-tools: 网络问题 → 稍后重试

### ⚠️ 清单中有但无 Homebrew cask
- Final Cut Pro: App Store 应用
- DaVinci Resolve Studio: 手动下载 → blackmagicdesign.com

### ℹ️ App Store 应用（需手动安装或用 mas）
- GarageBand
- Infuse

### 🔧 需手动核对（非软件）
- 系统偏好 defaults：键盘 / 触控板 / Dock / 快捷键
- /usr/local/bin、/opt 手动工具：<manual_bins 列表>
- 拒绝采集的敏感项：<skipped_sensitive 列表>

Troubleshooting Notes

brew bundle

Rolls Back the Entire Batch When One Item Fails

Problem: If any cask download fails in

brew bundle --file=Brewfile

, the entire batch of installed packages is rolled back.

Solution: Do not use

brew bundle

. Add taps one by one, install formulas in a batch, and install casks one at a time.

2. Third-Party Taps Are Not Trusted

Problem: Homebrew 6+ requires third-party taps to be explicitly trusted; otherwise, it reports

Refusing to load cask from untrusted tap

Solution:

brew trust <user>/<repo>

rsync

Reports an Error on Time Machine APFS Snapshots

Problem:

rsync -av --ignore-existing

reports an

io_read_flush

error when copying Library subdirectories.

Solution: Use

cp -rn

for Library subdirectories.

cp -rn

Reports "Operation not permitted"

Problem: Files protected by macOS SIP/TCC cannot be copied directly, including system Preferences and Mail databases.

Impact: This does not affect usage. The system or applications rebuild these files automatically on first launch.

cp -rn

Reports "Not a directory"

Problem: Some system containers in Containers use symbolic links that point to standard directories.

Impact: This does not affect usage. User application container data has been copied correctly.

6. Casks That Require sudo

Problem: Packages such as

docker-desktop

tailscale-app

, and

adobe-creative-cloud

require sudo during installation.

Solution: Record them in the discrepancy report and have the user run the commands manually.

7. node Version Conflict

Problem:

brew link

fails after running

brew install node@22

Solution:

brew link --overwrite node@22

8. Homebrew Cannot Detect Software Not Installed Through Homebrew

Problem: Software installed on the old system through DMG, PKG, or the App Store is invisible to Homebrew.

Solution: During collection, scan

/Applications/

and compare it with

brew list --cask

, mark manually installed applications, and handle them separately during restoration.

Principles

Make a full Time Machine backup before starting: It is the only fallback in case of failure and the data source for restoration
Have the user install Homebrew manually: It requires a password through sudo, so guide the user to run the command in a terminal and continue only after installation is complete
Separate the two phases: Collection and restoration are independent steps connected through a JSON file
Ask before collecting sensitive data: The user decides whether private keys and credentials should be collected; if they are collected, warn the user about the risk of disclosure
Never overwrite existing files: Every rsync and cp operation includes
```
--ignore-existing
```
or
```
-n
```
Start small and work up: Copy directories in ascending order of size to make validation easier
Make a plan before taking action: Before restoration, output a manifest summary and ask the user for confirmation
Record discrepancies: After restoration, output a discrepancy report listing items that require manual handling
Install casks one by one: Avoid the rollback problem caused by
```
brew bundle
```
Verify every step: Confirm installations with
```
brew list
```
and verify copied sizes with
```
du -sh
```
Skip caches: Do not restore cache data under Library/Application Support

macos-migration

NPX Install

Tags

SKILL.md Content (Chinese)

macOS System Migration Assistant

Prerequisites (Do This First)

Runtime Mode Detection

Step Zero: Homebrew Check (Required in Both Modes)

Mode A: Collection on the Old System

A1. Homebrew Packages

A2. System Applications

A3. Mac App Store Applications

A4. npm Global Packages

A5. uv Tools

A6. pip/pipx Packages

A7. Go Global Tools

A8. Configuration File Scan

A9. LaunchAgents (Startup Services)

A10. User Project Directories

A11. Shell Environment

A12. Other Easily Missed Items

A13. Generate the Manifest File

A14. Collection Complete

Mode B: Restoration on the New System

B0. Obtain the Manifest

B1. Homebrew Software Installation

B2. Other Package Managers

B3. Configuration File Restoration

B4. Key Library Subdirectories

B5. LaunchAgents (Startup Services)

B6. Restoration of Other Easily Missed Items

B7. Handling Items That Could Not Be Installed

Troubleshooting Notes

1. brew bundle Rolls Back the Entire Batch When One Item Fails

2. Third-Party Taps Are Not Trusted

3. rsync Reports an Error on Time Machine APFS Snapshots

4. cp -rn Reports "Operation not permitted"

5. cp -rn Reports "Not a directory"

6. Casks That Require sudo

7. node Version Conflict

8. Homebrew Cannot Detect Software Not Installed Through Homebrew

Principles

1.
`brew bundle`
Rolls Back the Entire Batch When One Item Fails

3.
`rsync`
Reports an Error on Time Machine APFS Snapshots

4.
`cp -rn`
Reports "Operation not permitted"

5.
`cp -rn`
Reports "Not a directory"