How to use the Cheat State Migrator agent skill (cheat-migrate)

What is an agent skill?

An agent skill is a folder containing a SKILL.md file with instructions that an AI coding agent such as Claude Code can load and follow when you ask for a matching task. The skill name and description tell the agent when to use it.

This skill is named cheat-migrate and its SKILL.md is the only file in the package.

What does the cheat-migrate skill make the agent do?

The agent reads your .cheat-state.json to find its current schema_version, then reads migrations/registry.md to find the target version (LATEST_SCHEMA) and the chain of upgrade steps between them. It shows a dry-run plan first, backs up the file, applies each step's migration instructions in order, verifies the result, and reports what changed.

If a step fails, the state stays at the last version that succeeded. The skill does not roll back and does not downgrade.

• Dry-run is on by default, so the plan is shown before any file changes.
• A backup named .cheat-state.json.backup-<timestamp> is written before any write.
• Each step is saved atomically (write to a temp file, then rename).
• Running it again on an up-to-date state exits with 'no migration needed'.

How do you install the cheat-migrate skill?

Download the ZIP for skills/cheat-migrate from the directory page. Then choose one of two options.

For Claude Code, unzip it into your user skills folder ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill limited to one project.

In the Claude apps, you can upload the skill under Settings → Capabilities → Skills instead.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside your project

What do you need before running it?

The skill needs an agent with Bash, Read, Write and Edit tools, such as Claude Code. It also needs the cheat-on-content repository itself, because the skill reads migrations/registry.md and the migration files. Those files are not included in the skill ZIP, so the skill cannot run on its own.

You also need an existing .cheat-state.json in your project root. If you have no state file, there is nothing to migrate; the cheat-init skill writes the latest format directly.

• Claude Code or a compatible agent with Bash, Read, Write and Edit tools
• The cheat-on-content repository, including migrations/registry.md and migration files
• An existing .cheat-state.json in the project root

How do you trigger the skill with natural requests?

You can ask in natural language. The skill description lists these trigger phrases: 迁移, 升级 state, migrate, 我的 state 是老版本, and schema 版本不对. Chinese phrases are used in the source, so either language works as long as the phrase matches the intent.

You can also call it directly as /cheat-migrate. The source documents optional arguments: --from to set a starting version, --to to stop at a specific version, and --dry-run to control dry-run mode. Check the argument-hint in SKILL.md for the exact syntax your agent expects.

• 迁移
• 升级 state
• migrate
• 我的 state 是老版本
• schema 版本不对

What does a typical run look like?

The agent first prints a plan listing each step, such as 1.0 → 1.1, with (MAJOR) or (MINOR) labels. You reply yes to continue, no to stop, or ask for details. After you confirm, it creates the backup, applies each step, checks that the file parses and that schema_version matches the target, and prints a report.

If a step fails, you see which file and step failed. Fix the problem in .cheat-state.json and run the skill again; it resumes from the last successful version.

• Example: a state at 1.0 with target 1.2 runs two steps, 1.0→1.1 then 1.1→1.2.
• Example: a failure at step 3 leaves schema_version at 1.2; rerunning continues from 1.2.

What safety notes should you know?

The skill is allowed to run scripts (the source says it runs scripts) and it uses Bash, so review what it is about to do in the dry-run plan. The source says the skill does not use the network. It only changes .cheat-state.json; it does not touch predictions, rubric or video data.

Downgrades are refused, because schema changes are one-way. A MAJOR change can also break older versions of the other skills, so you should not switch back to an older skill version after a MAJOR migration. If you skip the dry-run, the backup is still made.

• Runs scripts: yes. Uses network: no.
• Refuses downgrades when the state is newer than the target.
• Always makes a backup before writing, even with dry-run turned off.
• Keeps the backup until you delete it or a later successful init clears it.

What tips help a migration go smoothly?

Commit or copy your project before migrating, and keep the backup file until you have checked the dashboard. Run the status skill afterwards to confirm things still work. If your hooks need reinstalling, the source says to run install.sh --reinstall-hooks from the skill repository, because migrations do not reinstall hook scripts.

• Read the dry-run plan before answering yes.
• Keep the .backup file until you have verified the result.
• Run /cheat-status after a migration.
• Do not run migrate while cheat-bump or cheat-predict is running.