skills.rest
fx
fxCOMMUNITY
Explore all skills by this author →
GitHub

fx-upgrade

Migrates repository instruction files to current AGENTS.md and REVIEW.md conventions.

Updated Nov 2, 2025
Search Tags:#coderabbit#migration#conventions#claude.md#agents.md#instruction files#symlink safety
One-click install
npx skills add https://github.com/fx/skills --skill fx-upgrade-fx
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: fx-upgrade
Source: https://github.com/fx/skills/tree/main/skills/fx-upgrade
Command: npx skills add https://github.com/fx/skills --skill fx-upgrade-fx

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Repositories accumulate legacy AI instruction files — CLAUDE.md with real content, .github/copilot-instructions.md, stale task-tracking rules, symlinks pointing outside the repo — that no longer match current conventions. Manually consolidating them into AGENTS.md and REVIEW.md is error-prone and risks losing rules or leaking private machine-wide instructions. ## Core Features & Use Cases - Detect, plan, confirm, apply: Runs detectors for each registered migration, builds a concrete per-file plan, and writes nothing until the user explicitly approves it. - Safe symlink handling: Classifies symlinks before reading anything and never copies content from links that escape the repository, protecting private machine-wide instructions. - Content-preserving migration: Moves or merges every legacy rule into AGENTS.md or REVIEW.md, removes only obsolete task-tracking clauses, and leaves all changes uncommitted for review with git diff. - Use Case: After pulling a catalog update that changed conventions, run the skill to merge a 412-line CLAUDE.md into AGENTS.md, convert CLAUDE.md to an @AGENTS.md pointer, fold copilot-instructions.md into REVIEW.md, and configure .coderabbit.yaml — all in one reviewable diff. ## Quick Start Ask the agent to run fx-upgrade to migrate this repository's instruction files to the current AGENTS.md and REVIEW.md conventions.

Frequently Asked Questions about fx-upgrade

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I migrate CLAUDE.md to AGENTS.md?▼

Run the fx-upgrade skill explicitly. It detects whether CLAUDE.md holds real content, moves or merges it into AGENTS.md, then rewrites CLAUDE.md as a single @AGENTS.md pointer line, leaving everything uncommitted for review with git diff.

What is the difference between fx-setup and fx-upgrade?▼

fx-setup runs automatically and only creates missing files or appends missing marker blocks — it never moves, overwrites, or deletes anything. fx-upgrade runs only on explicit request and performs intrusive migrations: moving content, rewriting files, resolving symlinks, and deleting obsolete paths.

Does fx-upgrade handle symlinks that point outside the repository?▼

Yes, and conservatively. A symlink escaping the repo, such as CLAUDE.md pointing to ~/.claude/CLAUDE.md, is deleted and the path seeded fresh. The target's contents are never read or copied, since they may contain private machine-wide instructions.

Will the migration delete any of my existing convention rules?▼

No. Every rule in a legacy file is moved into AGENTS.md or REVIEW.md, or explicitly reported as deliberately dropped. Only obsolete task-tracking clauses are removed, and mixed sections are edited line-by-line rather than deleted.

Can fx-upgrade run automatically from another skill?▼

No. It is explicit-invocation only by design. Other skills that detect a legacy layout report it and recommend running fx-upgrade, but never trigger the migration themselves, because every change it makes should be user-approved and reviewable.

Is the fx-upgrade migration idempotent?▼

The M1 instruction-file migration is idempotent — rerunning on a migrated repo finds nothing to apply. However, the duvet adoption offer runs on every invocation when .duvet/ is absent, so a rerun can still write files if adoption is accepted.

Related Skills

Explore More Software Engineering Skills→
mujtaba3Bmujtaba3B
2

coderabbit-config

Generate a repository-specific .coderabbit.yaml with path filters and review profiles.

Community
Advanced
terakoya76terakoya76

review

Automate code review of uncommitted git changes with a reviewer subagent.

Community
Basic
bmad-code-orgbmad-code-org
52.5k

bmad-project-context

Creates and maintains verified AGENTS.md instruction blocks for AI coding agents in a repository.

Official
Advanced
TheGoatedDevTheGoatedDev

ccn:document-capture

Parse DECISION:, LEARNING:, and QUESTION: markers into timestamped .notes logs.

Community
Basic