gh-otoshek-claude-code-toolkit/skills/django-setup/README.md

Django Setup Skill (HTTPS Development)

For HTTPS-only Django projects using mkcert SSL certificates.

Skill Overview

This skill sets up Django projects specifically for HTTPS local development, which is required for:

• WebAuthn/Passkeys (MFA)
• Secure cookies
• Service workers
• Modern browser APIs

Key Features

• ✅ Automatic Python version selection - Uses highest available 3.8-3.13, installs 3.13 if none found
• ✅ HTTPS by default - Integrated mkcert setup
• ✅ Core dependencies - Django, python-dotenv, djangorestframework, django-cors-headers; adds uvicorn[standard] for SSL serving
• ✅ Uvicorn ASGI server - With SSL support
• ✅ Manual, guided setup - No automation scripts, full control

Progressive Disclosure Structure

django-setup/
├── SKILL.md                   # ⭐ Core skill (HTTPS-focused)
├── README.md                  # This file
│
├── platform-https/            # 🔒 mkcert + Uvicorn setup per OS
│   ├── mkcert-https-setup-macos.md
│   ├── mkcert-https-setup-linux.md
│   └── mkcert-https-setup-windows.md
│
├── platform-install/          # 📦 Platform-specific Python installation
│   ├── macos.md
│   ├── linux-ubuntu.md
│   ├── linux-fedora.md
│   └── windows.md
│
├── troubleshooting/           # 🔧 Problem-solving guides
│   ├── venv-issues.md
│   ├── pip-problems.md
│   └── django-errors.md
│
└── examples/                 # 📋 Templates
    └── .gitignore-template

What's Different from Standard Django Setup?

Standard Django	This Skill
HTTP only (port 8000)	HTTPS with mkcert
python manage.py runserver	./run.sh / run.bat (Uvicorn with SSL)
No SSL certificates	SSL certs in certs/
Optional HTTPS	HTTPS required
Any dependencies	Focused: Django, dotenv, DRF, django-cors-headers + uvicorn

Quick Setup Flow

1. Check/install Python 3.8-3.13 (uses highest, installs 3.13 if needed)
2. Create venv with selected Python version
3. Install core dependencies (Django, python-dotenv, djangorestframework, django-cors-headers)
4. Create Django project (django-admin startproject backend .)
5. Set up mkcert HTTPS + Uvicorn (platform-https guides install uvicorn[standard], generate certs, create run script)
6. Configure settings.py for CORS/CSRF (adds corsheaders middleware & allowed origins)
7. Add health + CSRF helper endpoints (api/health, api/csrf)
8. Run migrations (python manage.py migrate)
9. Optional VS Code launch config (.vscode/launch.json)
10. Test with HTTPS (./run.sh or run.bat → https://localhost:8000)

Why These Dependencies?

Authentication packages (allauth, etc.) are intentionally excluded and should be added later via the django-allauth-config skill to keep the base setup lean. django-cors-headers is included because the skill configures CORS/CSRF for a typical HTTPS frontend, and uvicorn[standard] is used to serve Django over SSL in development.

Core dependencies:

pip install Django python-dotenv djangorestframework django-cors-headers

HTTPS server:

pip install 'uvicorn[standard]'

Add authentication later:

# Use django-allauth-config skill
pip install django-allauth[socialaccount,mfa] django-cors-headers

Integration with Other Skills

This skill integrates with:

• mkcert-https-setup - SSL certificate setup (referenced inline via platform-https guides)
• django-allauth-config - Add authentication after base setup

Token Efficiency

Core SKILL.md: ~2,500 tokens (HTTPS-focused, no automation) Platform guides: ~400-600 tokens (loaded only when needed) Troubleshooting: ~300-500 tokens (loaded only on errors)

Average context usage: ~2,800 tokens Compared to v1.0 monolithic: 65% reduction

Usage

# User says: "Set up Django project for HTTPS"
# Claude loads: django-project-setup skill
# Guides through: Python → venv → Django → mkcert → test HTTPS

Final Project Structure

project-root/
├── backend/                  # Django project
├── backend/views.py          # Health + CSRF token endpoints
├── certs/                    # mkcert SSL certificates
│   ├── localhost+2.pem
│   └── localhost+2-key.pem
├── venv/                     # Virtual environment
├── .gitignore
├── db.sqlite3                # Database
├── manage.py
├── requirements.txt          # Django, dotenv, DRF, cors-headers, uvicorn
├── run.sh                    # HTTPS server script (macOS/Linux)
├── run.bat                   # HTTPS server script (Windows)
└── .vscode/launch.json       # Optional VS Code debug config

Version History

• v3.0.0 - HTTPS-only, mkcert integration, uvicorn server, CORS/CSRF defaults, minimal automation
• v2.0.0 - Progressive disclosure with bundled content (deprecated)
• v1.0.0 - Initial monolithic skill (deprecated)

Security Notes

🔒 Local development only - mkcert certificates only work on your machine 🔐 Never commit - certs/, *.pem, .env must be in .gitignore ⚠️ Production - Use real SSL certificates (Let's Encrypt, etc.)