legacy-bridge

Backward compatibility bridge that translates legacy @load patterns to new Skills format. Enables seamless migration with zero breaking changes during 6-month transition period.

⭐11stars🔀0forks📁View on GitHub🕐Updated Jan 1, 2026

When & Why to Use This Skill

The Legacy Bridge skill is a specialized compatibility layer designed to facilitate a seamless transition from deprecated @load patterns to the modern Claude Skills architecture. It ensures zero breaking changes for developers by automatically translating legacy syntax into the new skill-loading format, providing a stable 6-month migration window while maintaining support for existing product matrices and coding standards.

Use Cases

  • Legacy Workflow Preservation: Maintain existing CLAUDE.md configurations using @load patterns without immediate refactoring, ensuring agents continue to function during the transition period.
  • Automated Migration Auditing: Scan extensive codebases to identify deprecated loading patterns and generate comprehensive migration reports to plan infrastructure upgrades.
  • Standardized Skill Translation: Automatically map old security (SEC:*), testing (TS:*), and coding standards (CS:*) to their modern equivalents, including automatic inclusion of NIST baselines.
  • Bulk Codebase Refactoring: Utilize the built-in migration tools to automatically update legacy files to the new skill-loader syntax with integrated backup safety.
namelegacy-bridge
descriptionBackward compatibility bridge that translates legacy @load patterns to new Skills format. Enables seamless migration with zero breaking changes during 6-month transition period.

Legacy Bridge

Quick Navigation: Level 1: Quick Start (5 min) → Level 2: Implementation (30 min) → Level 3: Mastery (Extended)


Level 1: Quick Start

Overview

The legacy-bridge skill provides backward compatibility for existing @load patterns used in CLAUDE.md and the product-matrix system. This bridge enables a zero-breaking-change migration path from the legacy standards loader to the new Skills-based architecture.

Migration Timeline: 6-month transition period (deprecation warnings only, no breaking changes)

When to Use

Use this skill when:

  • You have existing code using @load product:* patterns
  • You need to maintain backward compatibility during migration
  • You want to gradually transition to the new Skills format

Quick Reference

Legacy Pattern New Skill Loading
@load product:api skill-loader.py load product:api
@load CS:python skills/coding-standards/python
@load SEC:* skills/security/* + NIST baseline

Level 2: Implementation

Pattern Translation

The legacy-bridge automatically translates old @load patterns to new skill loads:

Product Type Patterns

# Old Pattern → New Skill Loading
@load product:api         → Load: [coding-standards, testing, security, devops]
@load product:web-service → Load: [coding-standards, testing, security, frontend, devops]
@load product:frontend-web → Load: [frontend, testing, security]

Standard Code Patterns

# Coding Standards (CS)
@load CS:python       → Load: skills/coding-standards/python
@load CS:javascript   → Load: skills/coding-standards/javascript

# Testing Standards (TS)
@load TS:pytest       → Load: skills/testing/pytest
@load TS:*            → Load: skills/testing/* (all testing skills)

# Security Standards (SEC)
@load SEC:auth        → Load: skills/security/authentication
@load SEC:*           → Load: skills/security/* + NIST-IG:base

Composite Patterns

# Multiple standards combined
@load [product:api + CS:python + TS:pytest]
  → Load: product:api skills + python coding + pytest testing

Wildcard Expansion

The bridge automatically expands wildcards:

SEC:*  expands to:
  - SEC:auth
  - SEC:secrets
  - SEC:input-validation
  - NIST-IG:base  # Auto-included with security

TS:* expands to:
  - TS:unit
  - TS:integration
  - TS:e2e

Auto-Inclusion Rules

NIST Baseline Auto-Loading:

  • Any security standard (SEC:*) automatically includes NIST-IG:base
  • Explicit override available with --no-auto-nist flag

Level 3: Mastery Resources

Migration Guide

Phase 1: Compatibility Mode (Current)

Both patterns work side-by-side:

# Legacy pattern (still works)
@load product:api

# New skill pattern (recommended)
skill-loader.py load product:api

Phase 2: Deprecation Warnings (Month 3-6)

Deprecation warnings will appear in logs.

Phase 3: Legacy Removal (Month 6+)

Legacy syntax will be removed. Migration guide available.

Migration Tools

# Scan codebase for legacy patterns
skill-loader.py audit-legacy --path .

# Generate migration report
skill-loader.py migration-report --output migration-plan.md

# Auto-migrate files (with backup)
skill-loader.py migrate --path . --backup

External Resources

  • resources/legacy-mappings.yaml - Complete mapping definitions
  • config/product-matrix.yaml - Original product definitions
  • examples/legacy-patterns/ - Migration examples