blueprint-skill-creator

Original source / Raw SKILL.md

---
name: blueprint-skill-creator
description: Creates blueprint-driven skills for infrastructure and deployment tasks. This skill should be used when creating new skills that require templates, patterns, or reference configurations (e.g., Dockerfiles, Helm charts, Kubernetes manifests, CI/CD pipelines). It enforces impact analysis before containerization, identifies environment requirements, network topology changes, and auth/CORS implications. Use this skill when building deployment-related skills or when containerizing applications.
---

# 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:**
```typescript
// 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:
```bash
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`):**
```markdown
# 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`):**
```markdown
# 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:**
```dockerfile
# ===== 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:**
```yaml
# ===== 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.


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/impact-checklist.md

```markdown
# Pre-Containerization Impact Checklist

Use this checklist before creating any containerization blueprint.

## 1. Environment Variables

### Discovery
```bash
# Find all env var usage in Python
grep -r "os.environ\|os.getenv\|environ.get" --include="*.py"

# Find all env var usage in TypeScript/JavaScript
grep -r "process.env" --include="*.ts" --include="*.tsx" --include="*.js"

# Find .env files
find . -name ".env*" -type f
```

### Classification

| Variable | Build-time | Runtime | Secret? | Docker Value |
|----------|------------|---------|---------|--------------|
| `DATABASE_URL` | | X | Yes | From secrets |
| `NEXT_PUBLIC_API_URL` | X | | No | Build ARG |
| `API_SECRET_KEY` | | X | Yes | From secrets |
| `NODE_ENV` | X | X | No | `production` |

### Rules
- [ ] Build-time vars (NEXT_PUBLIC_*) → Use ARG in Dockerfile
- [ ] Runtime vars → Use ENV or docker-compose environment
- [ ] Secrets → Never in Dockerfile, use K8s secrets or Docker secrets
- [ ] URLs → Must be updated for container networking

---

## 2. Network Topology

### Discovery
```bash
# Find localhost references
grep -r "localhost\|127.0.0.1" --include="*.ts" --include="*.py" --include="*.json"

# Find port references
grep -r ":3000\|:8000\|:5432\|:6379" --include="*.ts" --include="*.py"
```

### Mapping Table

| Local URL | Docker Compose | Kubernetes |
|-----------|----------------|------------|
| `localhost:3000` | `web:3000` | `frontend-svc:3000` |
| `localhost:8000` | `api:8000` | `backend-svc:8000` |
| `localhost:5432` | `db:5432` | External (Neon) |
| `localhost:3001` | `sso:3001` | `sso-svc:3001` |

### Rules
- [ ] All localhost refs identified
- [ ] Docker service names defined
- [ ] External services (Neon, etc.) use actual URLs
- [ ] Internal services use Docker/K8s service names

---

## 3. Auth/SSO Impact (Better Auth)

### Discovery
```bash
# Find Better Auth config
grep -r "trustedOrigins\|baseURL\|BETTER_AUTH" --include="*.ts"

# Find CORS config
grep -r "cors\|origins\|allowedOrigins" --include="*.ts" --include="*.py"
```

### Critical Checks

**trustedOrigins must include:**
```typescript
trustedOrigins: [
  // Local development
  "http://localhost:3000",
  "http://localhost:8000",

  // Docker Compose
  "http://web:3000",
  "http://api:8000",

  // Kubernetes (if applicable)
  "http://frontend-svc:3000",
  "http://backend-svc:8000",

  // Production domain
  "https://yourdomain.com",
]
```

**Backend CORS must include:**
```python
origins = [
    "http://localhost:3000",
    "http://web:3000",          # Docker service name
    "http://frontend-svc:3000", # K8s service name
    os.getenv("FRONTEND_URL"),  # Dynamic
]
```

### Rules
- [ ] trustedOrigins includes Docker service names
- [ ] Backend CORS includes Docker service names
- [ ] Callback URLs work with container networking
- [ ] JWT secret shared between services (via env/secrets)

---

## 4. Service Dependencies

### Dependency Graph
```
web (frontend)
├── depends_on: api
└── depends_on: sso (if separate)

api (backend)
├── depends_on: db (or external Neon)
└── depends_on: redis (if used)
└── depends_on: kafka (Phase V)

mcp-server
└── depends_on: api
```

### Startup Order
1. Database (or verify Neon connection)
2. Redis (if used)
3. API backend
4. SSO service (if separate)
5. MCP server
6. Frontend

### Health Checks
```yaml
# Each service needs health check
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:PORT/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s
```

### Rules
- [ ] Dependency order documented
- [ ] Health checks defined for all services
- [ ] `depends_on` with `condition: service_healthy`
- [ ] Startup timeouts configured

---

## 5. Build vs Runtime Configuration

### Build-Time (Baked into image)
- NEXT_PUBLIC_* variables
- Static assets
- Compiled code
- Cannot change without rebuild

### Runtime (Can change per deployment)
- Database URLs
- API endpoints (non-NEXT_PUBLIC)
- Feature flags
- Secrets

### Rules
- [ ] Build-time vars documented
- [ ] Runtime vars use environment/secrets
- [ ] No secrets baked into image
- [ ] next.config.js uses `output: "standalone"`

---

## 6. Production Mode Differences

### Next.js (NODE_ENV=production)
- API routes may behave differently
- Some dev-only features disabled
- Static optimization kicks in
- **Auth callbacks must use production URLs**

### FastAPI (Environment checks)
- Debug mode should be off
- CORS may be stricter
- Logging level changes

### Rules
- [ ] Tested with NODE_ENV=production locally
- [ ] Auth flows verified in production mode
- [ ] No localhost-only code paths

---

## 7. File System & Volumes

### Stateless Requirements
- [ ] No local file storage for user data
- [ ] Logs go to stdout/stderr
- [ ] Temp files cleaned up

### Volume Needs
```yaml
volumes:
  # Only if needed
  - ./data:/app/data  # Persistent data
  - /tmp:/tmp         # Temp files (usually not needed)
```

---

## 8. Final Verification

### Pre-Build Checks
- [ ] All env vars documented
- [ ] Network topology mapped
- [ ] Auth origins updated
- [ ] Dependencies ordered
- [ ] Health checks defined

### Post-Build Checks
- [ ] `docker compose up` starts all services
- [ ] Services can communicate (test API calls)
- [ ] Auth/login flow works
- [ ] No localhost errors in logs

### Production Readiness
- [ ] Images use specific tags (not `latest`)
- [ ] Non-root user configured
- [ ] Resource limits set
- [ ] Secrets externalized

```