README

TYPO3 Extension Upgrade Skill

A Claude Code skill for systematically upgrading TYPO3 extensions to newer LTS versions.

🔌 Compatibility

This is an Agent Skill following the open standard originally developed by Anthropic and released for cross-platform use.

Supported Platforms:

✅ Claude Code (Anthropic)
✅ Cursor
✅ GitHub Copilot
✅ Other skills-compatible AI agents

Skills are portable packages of procedural knowledge that work across any AI agent supporting the Agent Skills specification.

Overview

This skill guides extension developers through upgrading TYPO3 extensions (third-party or custom) to newer TYPO3 LTS versions with modern PHP compatibility. It covers:

Extension Scanner - Backend module for diagnosing deprecated/removed APIs
Rector - Automated PHP code migrations
Fractor - Automated non-PHP file migrations (FlexForms, TypoScript, YAML, Fluid)
PHPStan - Static analysis
PHPUnit - Testing framework setup

Scope

This skill is for extension developers upgrading extension code. It does NOT cover:

Upgrading TYPO3 project installations
TYPO3 core upgrades
Site/instance migrations

Supported Upgrade Paths

From	To	Status
v7	v8	Documented
v8	v9	Documented
v9	v10	Documented
v10	v11	Documented
v11	v12	Documented
v12	v13	Documented
v13	v14	Monitoring
v12	v12+v13 (dual)	Documented

Installation

Marketplace (Recommended)

Add the Netresearch marketplace once, then browse and install skills:

# Claude Code
/plugin marketplace add netresearch/claude-code-marketplace
/plugin install typo3-extension-upgrade@netresearch-claude-code-marketplace

Without a marketplace

Since Claude Code 2.1.157 a plugin directory under your personal skills directory loads on its own, including the commands and agents this repo ships:

mkdir -p ~/.claude/skills
git clone https://github.com/netresearch/typo3-extension-upgrade-skill.git \
  ~/.claude/skills/typo3-extension-upgrade

It loads as typo3-extension-upgrade@skills-dir on the next session. Update with git -C ~/.claude/skills/typo3-extension-upgrade pull and start a new session; remove it by deleting the directory. This route has no claude plugin update.

npx (skills.sh)

Install with any Agent Skills-compatible agent:

npx skills add https://github.com/netresearch/typo3-extension-upgrade-skill --skill typo3-extension-upgrade

Limitation: npx skills installs SKILL.md-based skills only. This repo also ships agents, commands, which it does not install — use the marketplace or the skills directory for those.

Download Release

Download the latest release and extract to your agent's skills directory.

Git Clone

git clone https://github.com/netresearch/typo3-extension-upgrade-skill.git

Composer (PHP Projects)

composer require netresearch/typo3-extension-upgrade-skill

Requires netresearch/composer-agent-skill-plugin.

Usage

The skill activates automatically when Claude detects:

TYPO3 extension upgrade requests
Compatibility issues with newer TYPO3 versions
Extension modernization tasks

Example prompts:

"Upgrade this extension to TYPO3 v13"
"Make this extension compatible with TYPO3 12 and 13"
"Fix the deprecated API usage in this TYPO3 extension"

typo3-extension-upgrade-skill/
├── README.md                          # This file
├── agents/upgrade-planner.md          # Upgrade planning agent
├── commands/                          # /assess and /rector slash commands
└── skills/typo3-extension-upgrade/
    ├── SKILL.md                       # Main skill instructions
    ├── checkpoints.yaml               # Assessment checkpoints
    ├── assets/                        # Configuration templates
    │   ├── rector.php                 # Rector configuration
    │   ├── fractor.php                # Fractor configuration
    │   ├── phpstan.neon               # PHPStan configuration
    │   ├── phpunit.xml                # PHPUnit configuration
    │   └── .php-cs-fixer.php          # PHP-CS-Fixer configuration
    ├── references/                    # Detailed documentation (14 files)
    │   ├── api-changes.md             # Version-specific API migrations (v7-v14)
    │   ├── pre-upgrade.md             # Pre-upgrade checklist
    │   └── ...                        # Version guides, dual compatibility, verification, troubleshooting
    └── scripts/
        └── scan-deprecations.sh       # Report-only grep scan for deprecated APIs and traps

Key Resources

Official TYPO3 Changelogs

Tools

TYPO3 Rector - PHP migrations
TYPO3 Fractor - Non-PHP migrations
Extension Scanner - API diagnostics

Contributing

Changes are proposed as pull requests against main. New or changed behaviour of a script needs a test in tests/test_scripts.py in the same pull request.

Tests

tests/test_scripts.py holds the behaviour tests for the shell scripts. It uses the Python standard library only and needs python3, bash, GNU grep and git:

python3 tests/test_scripts.py

What the tests cover:

skills/typo3-extension-upgrade/scripts/scan-deprecations.sh: each of the 45 checks against a fixture it must match (a fixture can match other checks too, for example ->connect( matches checks 06 and 09), negative cases, the summaries, a missing path and the default target.
Build/Scripts/check-plugin-version.sh and the Build/hooks/pre-push hook that calls it: untagged, matching, mismatching and non-semver tags in a temporary git repository.
scripts/verify-harness.sh: harness layouts from empty to complete, over-long AGENTS.md, broken references, undocumented composer scripts, GitHub annotation output and invalid arguments.

evals/run-ab-test.sh has no test: it calls the claude CLI, which runs paid model requests.

A passing run prints a dot per test and ends with OK and exit code 0. A failure prints FAIL: with the test name; for the scan checks the check= and label= fields name the check function and the heading it should have printed, and the exit code is 1. CI runs the same file in the Skill Tests workflow (.github/workflows/tests.yml) on every pull request and every push to main.

Dependencies

Skill: the skill itself has no runtime dependency. scan-deprecations.sh needs Bash and GNU grep (its patterns use \| and \s).
Composer: composer.json requires netresearch/composer-agent-skill-plugin for installation through Composer. No composer.lock is committed (.gitignore).
Development and CI tools: pre-commit hooks are pinned by rev: in .pre-commit-config.yaml. CI tools come from the shared workflows in netresearch/.github, netresearch/skill-repo-skill and netresearch/typo3-ci-workflows, which pin every action by commit SHA.
Updates: Renovate (renovate.json, config:recommended with the pre-commit manager enabled) opens update pull requests. For pull requests opened by Renovate or Dependabot, auto-merge-deps.yml approves them and enables auto-merge through the shared workflow, unless they carry the label deps-major or deps-no-automerge; the merge waits for the required checks.
Checks: dependency review and Composer Audit (see below) check dependency changes on pull requests. New dependencies follow the licence and vulnerability rules of the organisation's handling of dependency and code analysis findings.

Governance and policies

This repository follows the Netresearch organisation policies:

Governance: ownership, roles, and how decisions are made and disputes resolved.
Roadmap: planned and explicitly excluded work for the coming year.
Handling of dependency and code analysis findings: thresholds, deadlines and the exception process for dependency (SCA) and static analysis (SAST) findings.
Secret management: how CI and release credentials are stored, accessed and rotated.
Access roster: who holds administrative access to this repository and the organisation.

The security assurance case for this skill (threat model, trust boundaries, countermeasures and limits) is in docs/SECURITY-ASSURANCE.md; components and data flow are in docs/ARCHITECTURE.md.

Checks that run on pull requests in this repository:

Every pull request: Skill Validation (lint.yml: skill structure, manifest sync, markdownlint, yamllint, actionlint, JSON syntax, ShellCheck, Ruff, checkpoint schema), Eval Validation (eval-validate.yml), Skill Tests (tests.yml: tests/test_scripts.py), the Labeler (labeler.yml) and Auto-merge dependency PRs (auto-merge-deps.yml, which acts only on Renovate and Dependabot pull requests); configured outside the workflows: CodeQL through GitHub's default setup (Analyze (actions)), SonarCloud and the DCO sign-off check; on pull requests to main that are not drafts, also the CodeRabbit review and the Copilot code review that the repository ruleset requests.
Pull requests to main: security.yml with Betterleaks (secret scanning), zizmor (workflow static analysis), dependency review (fails on vulnerabilities of severity high or above), Composer Audit and Opengrep SAST (which findings fail the check is set by the organisation rule); Harness Verification (harness-verify.yml) and Template Drift (check-template-drift.yml).
Secret detection: Betterleaks in security.yml on pull requests to main and pushes to main, and GitHub secret scanning with push protection, which is enabled for this repository.

Author

Netresearch DTT GmbH https://www.netresearch.de/

Netresearch is a Leipzig-based technology company specializing in e-commerce, logistics, and TYPO3 solutions. With extensive experience in TYPO3 extension development and maintenance, Netresearch contributes to the TYPO3 ecosystem through open-source extensions and community involvement.

License

This project uses split licensing:

Code (scripts, workflows, configs): MIT
Content (skill definitions, documentation, references): CC-BY-SA-4.0

See the individual license files for full terms.

Credits

Developed and maintained by Netresearch DTT GmbH.

netresearch / agent-typo3-extension-upgrade

Package info

Security

Statistics