sdk-config-validator

vanman2024's avatarfrom vanman2024

Validates Claude Agent SDK configuration files, environment setup, dependencies, and project structure

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 29, 2025
[Developer Tools]

When & Why to Use This Skill

The SDK Configuration Validator is a specialized Claude skill designed to automate the verification and troubleshooting of Claude Agent SDK environments. It ensures that project structures, dependency versions, and environment variables are correctly configured for both TypeScript and Python projects, significantly reducing setup time and preventing common initialization failures through actionable validation reports.

Use Cases

  • Initial Project Setup: Automatically verify that all required files, dependencies, and directory structures are correctly in place before starting SDK development.
  • Environment Troubleshooting: Diagnose 'SDK not working' or initialization errors by checking for missing environment variables like ANTHROPIC_API_KEY or incorrect MCP transport settings.
  • Dependency Audit: Ensure version compatibility between the Claude Agent SDK and the local Node.js or Python environment to prevent runtime crashes.
  • Configuration Standardization: Generate and validate standardized configuration templates (tsconfig.json, pyproject.toml, .env) to maintain consistency across multiple agent projects.
namesdk-config-validator
descriptionValidates Claude Agent SDK configuration files, environment setup, dependencies, and project structure
allowed-toolsBash, Read, Grep, Glob
categoryvalidation
complexitysimple

SDK Configuration Validator

Validates Claude Agent SDK project configuration, environment setup, and dependencies.

Use when...

  • User mentions "validate SDK setup", "check SDK configuration", or "SDK not working"
  • User reports SDK initialization errors or import failures
  • User asks "is my SDK project configured correctly?"
  • User requests "troubleshoot SDK issues" or "debug SDK setup"
  • Before starting SDK development work in a new project
  • After installing SDK dependencies to verify correctness

Capabilities

  • Validates TypeScript/Python SDK configuration files
  • Checks SDK version compatibility and dependencies
  • Verifies environment variable setup (.env files)
  • Validates project structure and required files
  • Generates validation reports with actionable fixes
  • Provides configuration templates for common setups

Usage

Basic Validation

# Validate TypeScript SDK setup
bash scripts/validate-typescript.sh /path/to/project

# Validate Python SDK setup
bash scripts/validate-python.sh /path/to/project

# Check SDK version compatibility
bash scripts/check-sdk-version.sh /path/to/project

Environment Validation

# Validate .env file setup
bash scripts/validate-env-setup.sh /path/to/project

Generate Templates

# Copy environment template
cp templates/.env.example.template /path/to/project/.env.example

# Copy TypeScript config
cp templates/tsconfig-sdk.json /path/to/project/tsconfig.json

# Copy Python config
cp templates/pyproject-sdk.toml /path/to/project/pyproject.toml

Validation Workflow

  1. Detect Project Type: Check for package.json (TS) or pyproject.toml (Python)
  2. Run Configuration Validation: Execute appropriate validation script
  3. Check Dependencies: Verify SDK package is installed with correct version
  4. Validate Environment: Check .env files for required variables
  5. Generate Report: Create validation report with findings and fixes
  6. Apply Fixes: Offer to apply recommended configuration changes

Common Issues Detected

  • Wrong package name (anthropic-agent-sdk instead of claude-agent-sdk) ⚠️
  • Missing SDK dependency in package.json/requirements.txt
  • Incorrect TypeScript compiler options for SDK
  • Missing required environment variables (ANTHROPIC_API_KEY)
  • Missing FastMCP Cloud API key when using MCP servers
  • Wrong MCP transport type ("sse" instead of "http" for FastMCP Cloud) ⚠️
  • SDK version incompatibility with Node/Python version
  • Missing configuration files (tsconfig.json, .env)
  • Incorrect module resolution settings
  • Missing async/await pattern in Python code

Exit Codes

  • 0: All validations passed
  • 1: Configuration errors found (see report)
  • 2: Critical errors (missing SDK, invalid structure)

Examples

See examples/ directory for sample validation reports and common fix patterns.