ai-counsel: Skill for Claude Code

Config Schema Migrator Skill

When to Use This Skill

Activate this skill when you need to:

• Evolve Pydantic configuration schemas (add fields, change types, restructure sections)
• Maintain backward compatibility with existing config files
• Write migration scripts to automate config updates
• Implement environment variable substitution in config fields
• Add deprecation warnings for old config patterns
• Validate config schemas with field validators
• Create discriminated unions for config type discrimination

Key Principles

1. Backward Compatibility First: Never break existing configs without a migration path
2. Deprecation Before Removal: Warn users before removing old config sections
3. Automatic Migration: Provide scripts to automate config updates (don't force manual editing)
4. Type Safety: Use Pydantic validators to catch config errors at load time
5. Environment Variables: Support ${VAR_NAME} substitution for secrets
6. Clear Messaging: Provide helpful error messages with migration instructions

Pattern 1: Adding New Config Sections with Backward Compatibility

Example: Adding adapters Section While Keeping cli_tools

Problem: You need to add a new config section (adapters) to replace an old one (cli_tools) without breaking existing configs.

Solution Pattern (from models/config.py):

from typing import Optional
from pydantic import BaseModel
import warnings

class Config(BaseModel):
    """Root configuration model."""

    # New section (preferred)
    adapters: Optional[dict[str, AdapterConfig]] = None

    # Legacy section (deprecated)
    cli_tools: Optional[dict[str, CLIToolConfig]] = None

    def model_post_init(self, __context):
        """Post-initialization validation."""
        # Ensure at least one section exists
        if self.adapters is None and self.cli_tools is None:
            raise ValueError(
                "Configuration must include either 'adapters' or 'cli_tools' section"
            )

        # Emit deprecation warning for old section
        if self.cli_tools is not None and self.adapters is None:
            warnings.warn(
                "The 'cli_tools' configuration section is deprecated. "
                "Please migrate to 'adapters' section with explicit 'type' field. "
                "See migration guide: docs/migration/cli_tools_to_adapters.md",
                DeprecationWarning,
                stacklevel=2,
            )