AgentSkillsCN

dynaconf-config

在添加配置设置时自动应用。确保 settings.toml 中正确使用 @env、@int、@bool 类型转换，并支持环境特定的覆盖。

SKILL.md
--- frontmatter
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