blueprint-skill-creator

Overview

This skill creates infrastructure skills that bundle blueprints (reusable templates and patterns) with impact analysis (understanding what changes when containerizing/deploying). It ensures deployment skills don't just generate configs—they understand and document the full impact.

Core Principle: Impact-Aware Blueprints

Traditional approach (fragile):

Request: "Create a Dockerfile"
Result: Generic Dockerfile that breaks in production

Blueprint-driven approach (robust):

Request: "Create a Dockerfile"
Process:
1. Analyze project for containerization requirements
2. Identify environment variables (build-time vs runtime)
3. Map localhost references → Docker service names
4. Check auth/CORS origins for container network
5. Generate Dockerfile with documented gotchas
6. Create docker-compose with proper networking

Workflow: Creating Blueprint-Driven Skills

Step 1: Define the Skill's Domain

Identify what infrastructure domain the skill covers:

| Domain | Examples | Key Concerns | |--------|----------|--------------| | Containerization | Dockerfiles, docker-compose | Env vars, networking, multi-stage builds | | Orchestration | Helm, Kubernetes manifests | Service discovery, secrets, resource limits | | CI/CD | GitHub Actions, pipelines | Build vs deploy stages, secrets injection | | Event Systems | Kafka, Dapr | Topics, schemas, authentication |

Step 2: Conduct Impact Analysis

Before creating any blueprint, analyze the target project:

2.1 Environment Analysis

Scan for:
├── .env files → What variables exist?
├── process.env / os.environ usage → What's expected at runtime?
├── Build-time variables → NEXT_PUBLIC_*, ARG in Dockerfiles
└── Sensitive values → API keys, secrets, connection strings

2.2 Network Topology Analysis

Identify:
├── localhost references → Must become service names
├── Port bindings → What ports are exposed?
├── Service dependencies → What talks to what?
└── External services → Databases, APIs, auth providers

2.3 Auth/CORS Impact Analysis

Critical for SSO/Better Auth:

Check auth configuration for:
├── Allowed origins → Must include Docker service names
├── Callback URLs → localhost:3000 → web:3000
├── API URLs → localhost:8000 → api:8000
└── NODE_ENV behavior → Some features disabled in production

Common gotcha:

// better-auth config - WILL BREAK in Docker if not updated
trustedOrigins: [
  "http://localhost:3000",     // Works locally
  // MISSING: "http://web:3000"  // Needed for Docker
  // MISSING: "http://frontend:3000"  // Needed for K8s
]

Step 3: Create Skill Structure

Initialize using skill-creator:

python3 .claude/skills/engineering/skill-creator/scripts/init_skill.py \
  <skill-name> --path .claude/skills/engineering/

Organize with blueprints:

.claude/skills/engineering/<skill-name>/
├── SKILL.md                    # Instructions + impact analysis guidance
├── references/                 # Blueprint documentation
│   ├── patterns.md             # Common patterns and when to use them
│   ├── impact-checklist.md     # What to check before containerizing
│   └── gotchas.md              # Known issues and solutions
└── assets/                     # Template files
    ├── Dockerfile.template     # Base template
    ├── docker-compose.template # Compose template
    └── .env.example            # Environment template

Step 4: Write Blueprint References

Each reference file should include:

Pattern documentation (references/patterns.md):

# Pattern: Multi-Stage Build

## When to Use
- Production deployments
- When image size matters
- When build dependencies differ from runtime

## Template
[Include actual template code]

## Variables to Replace
- `{{BASE_IMAGE}}` - Base image (e.g., python:3.13-slim)
- `{{APP_MODULE}}` - Entry point (e.g., main:app)
- `{{PORT}}` - Exposed port

## Impact Notes
- Build-time ARGs are baked in - cannot change at runtime
- Use ENV for runtime configuration

Impact checklist (references/impact-checklist.md):

# Pre-Containerization Checklist

## Environment Variables
- [ ] List all env vars used in application
- [ ] Categorize: build-time vs runtime
- [ ] Identify secrets (should use K8s secrets, not ENV)

## Network Changes
- [ ] Find all localhost references
- [ ] Map to Docker service names
- [ ] Update CORS/auth origins

## Auth/SSO Specific
- [ ] Check trustedOrigins includes Docker service names
- [ ] Verify callback URLs work with container networking
- [ ] Test NODE_ENV=production behavior

## Dependencies
- [ ] Identify service startup order
- [ ] Configure health checks
- [ ] Set up proper wait conditions

Step 5: Include Asset Templates

Asset templates should be parameterized and documented:

Dockerfile.template:

# ===== IMPACT NOTES =====
# This template requires:
# - ENV: {{ENV_VARS_LIST}}
# - Network: Service name "{{SERVICE_NAME}}" on port {{PORT}}
# - Auth: Ensure CORS includes http://{{SERVICE_NAME}}:{{PORT}}
# ========================

FROM {{BASE_IMAGE}} AS builder
# ... template content

docker-compose.template:

# ===== NETWORK TOPOLOGY =====
# Services communicate via Docker network using service names:
# - web → api: http://api:8000
# - api → db: postgres://db:5432
# - web → sso: http://sso:3001
# ============================

services:
  {{SERVICE_NAME}}:
    build:
      context: {{CONTEXT_PATH}}
      args:
        - NODE_ENV={{NODE_ENV}}
    environment:
      # Runtime configuration
      - DATABASE_URL=${DATABASE_URL}
      - API_URL=http://api:8000  # Docker service name, not localhost!

Creating Specific Blueprint Skills

Example: Docker Blueprint Skill

When creating a Docker blueprint skill, include:

SKILL.md sections:

1. Impact analysis workflow
2. Environment variable handling
3. Multi-stage build patterns
4. Network configuration for Docker Compose
5. Auth/CORS gotchas

References:

• references/fastapi-patterns.md - FastAPI-specific patterns
• references/nextjs-patterns.md - Next.js-specific patterns
• references/auth-impact.md - Better Auth/SSO considerations

Assets:

• assets/Dockerfile.fastapi - FastAPI template
• assets/Dockerfile.nextjs - Next.js template
• assets/docker-compose.base.yml - Base compose file

Example: Helm Blueprint Skill

When creating a Helm blueprint skill, include:

SKILL.md sections:

1. Chart structure requirements
2. Values.yaml patterns
3. Secret management (External Secrets Operator)
4. Service discovery in Kubernetes
5. Resource limits by environment

References:

• references/chart-structure.md - Helm chart anatomy
• references/security-context.md - Pod security patterns
• references/networking.md - Service/Ingress patterns

Assets:

• assets/base-chart/ - Complete Helm chart template
• assets/values-dev.yaml - Development values
• assets/values-prod.yaml - Production values

Validation Checklist

Before finalizing a blueprint skill, verify:

• [ ] SKILL.md includes impact analysis workflow
• [ ] References document all patterns with "when to use"
• [ ] Assets are parameterized with clear variable markers
• [ ] Gotchas and common failures are documented
• [ ] Network topology is explicitly documented
• [ ] Auth/CORS implications are addressed
• [ ] Environment variables are categorized (build vs runtime)
• [ ] Service dependencies and startup order documented

Anti-Patterns to Avoid

Don't create blueprints that:

• Hardcode localhost URLs
• Bake secrets into images
• Ignore NODE_ENV behavior differences
• Skip health checks
• Assume single-container deployment
• Forget about CORS/auth origins

Do create blueprints that:

• Use environment variables for all URLs
• Reference secrets from external stores
• Document production vs development differences
• Include comprehensive health checks
• Support both Docker Compose and Kubernetes
• Explicitly list required CORS origin updates

Resources

references/

Contains pattern documentation and impact checklists that inform blueprint creation.

assets/

Contains template files that serve as starting points for generated configurations.

scripts/

Contains validation scripts for checking blueprint completeness.