Initial commit

skills/python-project-setup/SKILL.md

@@ -0,0 +1,76 @@
+# Python Project Setup Skill
+
+Set up new Python projects following modern best practices with uv, ruff, pytest, and proper project structure.
+
+## When to Use This Skill
+
+Use this skill when:
+- User requests to create a new Python project
+- User wants to initialize Python tooling in an existing directory
+- User mentions setting up a Python development environment
+- User asks about Python project structure or best practices
+
+## Core Capabilities
+
+1. **Project Initialization**
+   - Initialize projects with `uv init`
+   - Set up proper directory structure
+   - Configure Python version with pyenv
+
+2. **Dependency Management**
+   - Install and configure uv package manager
+   - Add essential dependencies (pytest, ruff, mypy, pydantic)
+   - Set up development vs runtime dependencies
+
+3. **Configuration Files**
+   - Create `pyproject.toml` with tool configurations
+   - Set up `.gitignore` for Python projects
+   - Configure VSCode settings for Python development
+   - Create `.python-version` for version management
+
+4. **Project Structure**
+   - Create `src/<project_name>/` for source code
+   - Set up `tests/` directory for test files
+   - Create `docs/` for documentation
+   - Set up `.vscode/` for editor configuration
+
+## Context Files
+
+This skill references the following context files in this directory:
+- `project-structure-template.md` - Standard directory layout
+- `pyproject-toml-template.md` - Configuration template
+- `vscode-settings-template.json` - Editor configuration
+- `gitignore-template.md` - Python gitignore patterns
+- `readme-template.md` - README structure
+
+## Key Tools and Commands
+
+```bash
+# Project initialization
+uv init <project-name>
+
+# Dependency management
+uv add pytest --dev
+uv add ruff --dev
+uv add mypy --dev
+uv add pydantic
+
+# Sync dependencies
+uv sync
+```
+
+## Expected Outcomes
+
+After using this skill, the user should have:
+- A fully initialized Python project with modern tooling
+- Proper project structure following best practices
+- All essential dependencies installed
+- Configuration files set up correctly
+- Version control initialized (git)
+- Documentation scaffolding in place
+
+## Integration with Other Skills
+
+- Works with `python-code-quality` skill for linting setup
+- Works with `python-testing` skill for test framework configuration
+- Complements the `python-project-setup` agent for full orchestration

skills/python-project-setup/gitignore-template.md

@@ -0,0 +1,209 @@
+# Python .gitignore Template
+
+```gitignore
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Ruff
+.ruff_cache/
+
+# uv
+uv.lock
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Project specific
+*.db
+*.sqlite
+*.sqlite3
+data/
+logs/
+tmp/
+temp/
+```
+
+## Explanation of Key Patterns
+
+### Python Runtime Files
+- `__pycache__/` - Compiled bytecode cache
+- `*.pyc`, `*.pyo`, `*.pyd` - Compiled Python files
+- `*.so` - Compiled C extensions
+
+### Package/Build Artifacts
+- `dist/`, `build/` - Build output directories
+- `*.egg-info/` - Package metadata
+- `.eggs/` - Installed packages directory
+
+### Virtual Environments
+- `.venv/`, `venv/`, `env/` - Virtual environment directories
+- Always create virtual environments, never commit them
+
+### Testing & Coverage
+- `.pytest_cache/` - Pytest cache
+- `.coverage` - Coverage data files
+- `htmlcov/` - HTML coverage reports
+
+### Type Checking & Linting
+- `.mypy_cache/` - Mypy cache
+- `.ruff_cache/` - Ruff cache
+- `.pytype/` - Pytype cache
+
+### Documentation
+- `docs/_build/` - Sphinx build output
+- `/site` - MkDocs build output
+
+### Environment Variables
+- `.env` - Environment variable files (NEVER commit these)
+- Should contain secrets, API keys, database URLs
+
+### IDE Files
+- `.vscode/` - VSCode settings (some teams commit this)
+- `.idea/` - PyCharm settings
+- `.DS_Store` - macOS file system metadata
+
+## Customization Tips
+
+1. **Commit `.vscode/` if desired**: Remove from .gitignore to share editor settings
+2. **Project-specific data**: Add custom directories for data files, logs, etc.
+3. **Lock files**: Consider keeping `uv.lock` for reproducible builds
+4. **Documentation**: Remove `docs/_build/` if you want to commit built docs

skills/python-project-setup/project-structure-template.md

@@ -0,0 +1,112 @@
+# Python Project Structure Template
+
+## Standard Directory Layout
+
+```
+project_name/
+├── .vscode/                    # VSCode editor configuration
+│   ├── settings.json          # Python, ruff, mypy settings
+│   └── launch.json            # Debug configurations
+├── src/                       # Source code directory
+│   └── project_name/          # Main package (use underscores)
+│       ├── __init__.py        # Package initialization
+│       ├── main.py            # Entry point (if applicable)
+│       ├── models/            # Data models (Pydantic)
+│       ├── services/          # Business logic
+│       ├── api/               # API routes (if using FastAPI)
+│       └── utils/             # Utility functions
+├── tests/                     # Test directory
+│   ├── __init__.py
+│   ├── conftest.py            # Pytest fixtures
+│   ├── test_main.py           # Test files (prefix with test_)
+│   └── integration/           # Integration tests
+├── docs/                      # Documentation
+│   ├── index.md
+│   └── api/                   # API documentation
+├── .github/                   # GitHub configuration
+│   ├── workflows/             # CI/CD workflows
+│   │   └── test.yml
+│   └── dependabot.yml         # Dependency updates
+├── .gitignore                 # Git ignore patterns
+├── .python-version            # Python version for pyenv
+├── pyproject.toml             # Project metadata and dependencies
+├── README.md                  # Project documentation
+└── uv.lock                    # Locked dependencies (generated)
+```
+
+## File Naming Conventions
+
+- **Python packages**: Use underscores (e.g., `my_package`)
+- **Project names**: Use underscores (e.g., `my_project`)
+- **Test files**: Prefix with `test_` (e.g., `test_models.py`)
+- **Private modules**: Prefix with `_` (e.g., `_internal.py`)
+
+## Directory Purpose
+
+### `src/project_name/`
+Main application code organized by function:
+- `models/` - Data classes, Pydantic models, database models
+- `services/` - Business logic and service layer
+- `api/` - API endpoints and route handlers (FastAPI)
+- `utils/` - Helper functions and utilities
+- `config/` - Configuration management
+
+### `tests/`
+Test files mirroring the structure of `src/`:
+- Unit tests for each module
+- Integration tests in `integration/` subdirectory
+- `conftest.py` for shared fixtures
+- Use pytest conventions
+
+### `docs/`
+Project documentation:
+- User guides
+- API documentation
+- Architecture decisions
+- Setup instructions
+
+## Module Organization
+
+Each Python module should follow this pattern:
+
+```python
+# frozen_string_literal equivalent in Python
+"""Module docstring describing purpose."""
+
+from typing import Any, Optional
+
+import third_party_package
+
+from project_name import local_module
+
+
+class MyClass:
+    """Class docstring."""
+
+    def __init__(self, param: str) -> None:
+        """Initialize with param."""
+        self.param = param
+
+    def method(self) -> str:
+        """Method docstring."""
+        return self.param
+
+
+def public_function() -> None:
+    """Public function docstring."""
+    pass
+
+
+def _private_function() -> None:
+    """Private helper function."""
+    pass
+```
+
+## Best Practices
+
+1. **Use `src/` layout**: Prevents accidental imports of local code
+2. **Type hints everywhere**: Add type annotations to all functions
+3. **Docstrings**: Document all public classes and functions
+4. **Test organization**: Mirror source structure in tests
+5. **Configuration**: Use environment variables or config files, never hardcode
+6. **Dependencies**: Separate dev dependencies from runtime dependencies

skills/python-project-setup/pyproject-toml-template.md

@@ -0,0 +1,226 @@
+# pyproject.toml Template
+
+## Complete Configuration Template
+
+```toml
+[project]
+name = "project-name"
+version = "0.1.0"
+description = "Project description"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+    {name = "Your Name", email = "you@example.com"}
+]
+keywords = ["python", "example"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "pydantic>=2.0.0",
+    # Add runtime dependencies here
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "ruff>=0.3.0",
+    "mypy>=1.8.0",
+]
+api = [
+    "fastapi>=0.110.0",
+    "uvicorn[standard]>=0.27.0",
+]
+docs = [
+    "mkdocs>=1.5.0",
+    "mkdocs-material>=9.5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/username/project-name"
+Repository = "https://github.com/username/project-name"
+Documentation = "https://project-name.readthedocs.io"
+Issues = "https://github.com/username/project-name/issues"
+
+[project.scripts]
+# Define CLI entry points
+project-cli = "project_name.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/project_name"]
+
+# Ruff configuration
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "ARG",    # flake8-unused-arguments
+    "SIM",    # flake8-simplify
+    "TCH",    # flake8-type-checking
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+    "B008",   # do not perform function calls in argument defaults
+    "B904",   # raise from None
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "ARG",    # Unused function arguments allowed in tests
+    "S101",   # Assert allowed in tests
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+
+# Pytest configuration
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+    "--showlocals",
+    "-ra",
+]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: marks tests as integration tests",
+]
+
+# Coverage configuration
+[tool.coverage.run]
+source = ["src"]
+branch = true
+omit = [
+    "*/tests/*",
+    "*/__init__.py",
+]
+
+[tool.coverage.report]
+precision = 2
+show_missing = true
+skip_covered = false
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "@abstractmethod",
+]
+
+# Mypy configuration
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+
+# UV-specific configuration (if needed)
+[tool.uv]
+dev-dependencies = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "ruff>=0.3.0",
+    "mypy>=1.8.0",
+]
+```
+
+## Configuration Sections Explained
+
+### `[project]`
+Basic project metadata used by build tools and package indexes.
+
+### `[project.optional-dependencies]`
+Groups of optional dependencies for different use cases:
+- `dev` - Development tools (testing, linting)
+- `api` - API framework dependencies (FastAPI, uvicorn)
+- `docs` - Documentation generation tools
+
+### `[tool.ruff]`
+Ruff linter and formatter configuration:
+- Fast Python linter combining multiple tools
+- Replaces isort, flake8, pyupgrade, and more
+- Automatic code formatting
+
+### `[tool.pytest.ini_options]`
+Pytest test framework configuration:
+- Test discovery patterns
+- Default command-line options
+- Custom test markers
+
+### `[tool.coverage]`
+Code coverage settings for pytest-cov:
+- Which files to measure
+- Coverage reporting options
+- Lines to exclude from coverage
+
+### `[tool.mypy]`
+Type checking configuration:
+- Strictness settings
+- Type checking rules
+- Per-directory overrides
+
+## Usage Examples
+
+```bash
+# Install project with dev dependencies
+uv sync --extra dev
+
+# Install with API dependencies
+uv sync --extra api
+
+# Install all optional dependencies
+uv sync --all-extras
+
+# Run tests with coverage
+uv run pytest --cov
+
+# Lint code
+uv run ruff check .
+
+# Format code
+uv run ruff format .
+
+# Type check
+uv run mypy src
+```

skills/python-project-setup/readme-template.md

@@ -0,0 +1,332 @@
+# README.md Template
+
+```markdown
+# Project Name
+
+Brief one-line description of what this project does.
+
+## Overview
+
+A more detailed description of the project, its purpose, and key features.
+
+## Features
+
+- Feature 1: Description
+- Feature 2: Description
+- Feature 3: Description
+
+## Requirements
+
+- Python 3.11 or higher
+- uv package manager
+
+## Installation
+
+### Using uv (Recommended)
+
+\`\`\`bash
+# Clone the repository
+git clone https://github.com/username/project-name.git
+cd project-name
+
+# Install dependencies
+uv sync
+
+# Activate virtual environment (optional, uv runs commands automatically)
+source .venv/bin/activate  # On Unix/macOS
+.venv\Scripts\activate     # On Windows
+\`\`\`
+
+### Using pip
+
+\`\`\`bash
+pip install -e .
+\`\`\`
+
+## Quick Start
+
+\`\`\`python
+from project_name import main_function
+
+# Example usage
+result = main_function()
+print(result)
+\`\`\`
+
+## Usage
+
+### Command Line Interface
+
+\`\`\`bash
+# Run the main application
+uv run python -m project_name
+
+# Or if you installed with pip
+project-cli --help
+\`\`\`
+
+### As a Library
+
+\`\`\`python
+from project_name import SomeClass
+
+# Create an instance
+instance = SomeClass(param="value")
+
+# Use the instance
+result = instance.method()
+\`\`\`
+
+## Development
+
+### Setup Development Environment
+
+\`\`\`bash
+# Install with development dependencies
+uv sync --extra dev
+
+# Or install all extras
+uv sync --all-extras
+\`\`\`
+
+### Running Tests
+
+\`\`\`bash
+# Run all tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov
+
+# Run specific test file
+uv run pytest tests/test_specific.py
+
+# Run with verbose output
+uv run pytest -v
+\`\`\`
+
+### Code Quality
+
+\`\`\`bash
+# Lint code
+uv run ruff check .
+
+# Fix auto-fixable issues
+uv run ruff check --fix .
+
+# Format code
+uv run ruff format .
+
+# Type checking
+uv run mypy src
+\`\`\`
+
+### Pre-commit Checks
+
+Before committing, ensure all checks pass:
+
+\`\`\`bash
+# Run all checks
+uv run ruff check . && uv run ruff format . && uv run mypy src && uv run pytest
+\`\`\`
+
+## Project Structure
+
+\`\`\`
+project-name/
+├── src/
+│   └── project_name/       # Main package
+│       ├── __init__.py
+│       ├── main.py         # Entry point
+│       ├── models/         # Data models
+│       ├── services/       # Business logic
+│       └── utils/          # Utilities
+├── tests/                  # Test files
+├── docs/                   # Documentation
+├── pyproject.toml         # Project configuration
+└── README.md              # This file
+\`\`\`
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file in the project root:
+
+\`\`\`env
+API_KEY=your_api_key_here
+DATABASE_URL=postgresql://user:pass@localhost/dbname
+DEBUG=false
+\`\`\`
+
+### Configuration File
+
+Alternatively, create a `config.yaml`:
+
+\`\`\`yaml
+api:
+  key: your_api_key
+  timeout: 30
+
+database:
+  url: postgresql://user:pass@localhost/dbname
+  pool_size: 5
+\`\`\`
+
+## API Documentation
+
+### Main Classes
+
+#### `SomeClass`
+
+Description of the class.
+
+\`\`\`python
+from project_name import SomeClass
+
+instance = SomeClass(param="value")
+result = instance.method()
+\`\`\`
+
+**Parameters:**
+- `param` (str): Description of parameter
+
+**Returns:**
+- `str`: Description of return value
+
+### Functions
+
+#### `main_function()`
+
+Description of the function.
+
+\`\`\`python
+from project_name import main_function
+
+result = main_function()
+\`\`\`
+
+## API Endpoints (if applicable)
+
+### Start the Server
+
+\`\`\`bash
+uv run uvicorn project_name.api.main:app --reload
+\`\`\`
+
+### Endpoints
+
+#### GET `/api/items`
+
+Get all items.
+
+**Response:**
+\`\`\`json
+{
+  "items": [
+    {"id": 1, "name": "Item 1"},
+    {"id": 2, "name": "Item 2"}
+  ]
+}
+\`\`\`
+
+#### POST `/api/items`
+
+Create a new item.
+
+**Request Body:**
+\`\`\`json
+{
+  "name": "New Item"
+}
+\`\`\`
+
+**Response:**
+\`\`\`json
+{
+  "id": 3,
+  "name": "New Item"
+}
+\`\`\`
+
+## Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch (\`git checkout -b feature/amazing-feature\`)
+3. Make your changes
+4. Run tests and linting (\`uv run pytest && uv run ruff check .\`)
+5. Commit your changes (\`git commit -m 'Add amazing feature'\`)
+6. Push to the branch (\`git push origin feature/amazing-feature\`)
+7. Open a Pull Request
+
+### Code Style
+
+- Follow PEP 8 guidelines
+- Use type hints for all functions
+- Write docstrings for all public APIs
+- Maintain test coverage above 80%
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Authors
+
+- Your Name - [@yourhandle](https://github.com/yourhandle)
+
+## Acknowledgments
+
+- Library or resource that inspired this project
+- Contributors who helped
+- Any other acknowledgments
+
+## Changelog
+
+### [0.1.0] - 2024-01-01
+
+#### Added
+- Initial release
+- Basic functionality
+
+#### Changed
+- Nothing yet
+
+#### Fixed
+- Nothing yet
+
+## Support
+
+For support, email support@example.com or open an issue on GitHub.
+
+## Links
+
+- [Documentation](https://project-name.readthedocs.io)
+- [Issue Tracker](https://github.com/username/project-name/issues)
+- [Changelog](CHANGELOG.md)
+```
+
+## Sections Explained
+
+1. **Title & Description**: Clear project name and one-line summary
+2. **Overview**: More detailed description of purpose and features
+3. **Installation**: Step-by-step setup instructions
+4. **Quick Start**: Minimal example to get started quickly
+5. **Usage**: Detailed usage examples (CLI and library)
+6. **Development**: Instructions for contributors
+7. **Project Structure**: Overview of codebase organization
+8. **Configuration**: How to configure the application
+9. **API Documentation**: Documentation of public API
+10. **Contributing**: Guidelines for contributions
+11. **License & Authors**: Legal and attribution information
+12. **Support**: How to get help
+
+## Tips for Good READMEs
+
+- **Keep it concise**: Users should understand the project in 30 seconds
+- **Working examples**: All code examples should be copy-paste ready
+- **Clear installation**: Step-by-step instructions that actually work
+- **Visual aids**: Consider adding screenshots, diagrams, or GIFs
+- **Badges**: Add CI status, coverage, and version badges
+- **Update regularly**: Keep it in sync with the actual codebase

skills/python-project-setup/vscode-settings-template.json

@@ -0,0 +1,54 @@
+{
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+  "python.analysis.typeCheckingMode": "basic",
+  "python.analysis.autoImportCompletions": true,
+  "python.analysis.diagnosticMode": "workspace",
+
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.organizeImports": "explicit",
+      "source.fixAll": "explicit"
+    },
+    "editor.rulers": [100]
+  },
+
+  "ruff.enable": true,
+  "ruff.lint.enable": true,
+  "ruff.format.enable": true,
+  "ruff.organizeImports": true,
+
+  "python.testing.pytestEnabled": true,
+  "python.testing.unittestEnabled": false,
+  "python.testing.pytestArgs": [
+    "tests"
+  ],
+
+  "files.exclude": {
+    "**/__pycache__": true,
+    "**/*.pyc": true,
+    "**/*.pyo": true,
+    "**/.pytest_cache": true,
+    "**/.mypy_cache": true,
+    "**/.ruff_cache": true,
+    "**/*.egg-info": true
+  },
+
+  "files.watcherExclude": {
+    "**/__pycache__/**": true,
+    "**/.venv/**": true,
+    "**/.pytest_cache/**": true,
+    "**/.mypy_cache/**": true,
+    "**/.ruff_cache/**": true
+  },
+
+  "search.exclude": {
+    "**/.venv": true,
+    "**/node_modules": true,
+    "**/__pycache__": true,
+    "**/.pytest_cache": true,
+    "**/.mypy_cache": true,
+    "**/.ruff_cache": true
+  }
+}