Initial commit

.claude/skills/dynaconf-config/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: dynaconf-config
+description: Automatically applies when adding configuration settings. Ensures proper dynaconf pattern with @env, @int, @bool type casting in settings.toml and environment-specific overrides.
+---
+
+# Dynaconf Configuration Pattern Enforcer
+
+When adding new configuration to `settings.toml`, always follow the dynaconf pattern.
+
+## ✅ Correct Pattern
+
+```toml
+# settings.toml
+
+[default]
+# Base configuration with type casting
+api_base_url = "@env API_BASE_URL|http://localhost:8080"
+api_timeout = "@int 30"
+feature_enabled = "@bool true"
+max_retries = "@int 3"
+
+# API endpoints (no @ prefix for strings)
+api_endpoint = "/api/v1/endpoint"
+
+[dev_local]
+# Override for local development
+api_base_url = "@env API_BASE_URL|http://localhost:8080"
+
+[dev_remote]
+# Override for remote development
+api_base_url = "@env API_BASE_URL|http://gateway-service"
+
+[production]
+# Production overrides
+api_base_url = "@env API_BASE_URL|https://api.production.com"
+api_timeout = "@int 60"
+```
+
+## Type Casting Directives
+
+**Use appropriate prefixes:**
+- `@env VAR|default` - Environment variable with fallback
+- `@int 123` - Cast to integer
+- `@bool true` - Cast to boolean
+- `@float 1.5` - Cast to float
+- `@path ./dir` - Convert to Path object
+- No prefix - String value
+
+## Environment Variable Override
+
+**Pattern:** `APPNAME_SETTING_NAME`
+
+Example:
+```toml
+# In settings.toml
+api_timeout = "@int 30"
+
+# Override via environment
+export APP_API_TIMEOUT=60
+```
+
+## Configuration Access
+
+```python
+from dynaconf import Dynaconf
+
+settings = Dynaconf(
+    settings_files=['settings.toml', '.secrets.toml'],
+    environments=True,
+    load_dotenv=True,
+)
+
+timeout = settings.api_timeout  # Returns int 30
+url = settings.api_base_url     # Returns string
+```
+
+## Common Patterns
+
+**API Configuration:**
+```toml
+service_api_base_url = "@env SERVICE_API_URL|http://localhost:8080"
+service_endpoint = "/api/v1/endpoint/{param}"
+service_timeout = "@int 30"
+```
+
+**Feature Flags:**
+```toml
+feature_enabled = "@bool true"
+feature_beta_mode = "@bool false"
+```
+
+**Database Paths:**
+```toml
+db_path = "@path data/database.db"
+```
+
+**Secrets Management:**
+```toml
+# settings.toml (checked into git)
+api_key = "@env API_KEY"
+
+# .secrets.toml (gitignored)
+api_key = "actual-secret-key"
+```
+
+## ❌ Anti-Patterns
+
+```toml
+# ❌ Don't hardcode secrets
+api_key = "sk-1234567890"
+
+# ❌ Don't forget type casting for numbers
+timeout = "30"  # Will be string, not int
+
+# ❌ Don't mix environments in same section
+[default]
+api_url = "https://production.com"  # Should be in [production]
+```
+
+## Best Practices Checklist
+
+- ✅ Add to `[default]` section first
+- ✅ Use appropriate `@` type casting
+- ✅ Add environment variable overrides with `@env`
+- ✅ Add to environment-specific sections as needed
+- ✅ Document in comments what the setting does
+- ✅ Keep secrets in `.secrets.toml` (gitignored)
+- ✅ Use consistent naming conventions (snake_case)
+- ✅ Provide sensible defaults
+
+## Auto-Apply
+
+When adding configuration:
+1. Add to `[default]` section first
+2. Use appropriate `@` type casting
+3. Add environment variable overrides
+4. Add to environment-specific sections as needed
+5. Document in comments what the setting does
+
+## Related Skills
+
+- structured-errors - For validation errors
+- pydantic-models - For settings validation with Pydantic