From bbe1e0e1d076757f98f5dacab9695e4bd9d7cb29 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 13 Feb 2026 17:49:17 +0000 Subject: [PATCH 1/3] Initial plan From fa68b048a60f8c4abc1b2cf06f3880aaec430c88 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 13 Feb 2026 19:01:02 +0000 Subject: [PATCH 2/3] Add comprehensive agent skills for wizard-template Co-authored-by: fschuch <37457501+fschuch@users.noreply.github.com> --- .../skills/python-wizard-template/README.md | 115 ++++ .../skills/python-wizard-template/SKILL.md | 524 ++++++++++++++++++ .../examples/docs_example.md | 111 ++++ .../examples/module_example.py | 81 +++ .../examples/test_example.py | 92 +++ .../templates/check-template-updates.sh | 50 ++ .../templates/module_template.py | 58 ++ .../templates/test_template.py | 58 ++ README.md | 14 +- docs/_toc.yml | 1 + docs/user-guide/agent-skills.md | 273 +++++++++ 11 files changed, 1372 insertions(+), 5 deletions(-) create mode 100644 .agents/skills/python-wizard-template/README.md create mode 100644 .agents/skills/python-wizard-template/SKILL.md create mode 100644 .agents/skills/python-wizard-template/examples/docs_example.md create mode 100644 .agents/skills/python-wizard-template/examples/module_example.py create mode 100644 .agents/skills/python-wizard-template/examples/test_example.py create mode 100644 .agents/skills/python-wizard-template/templates/check-template-updates.sh create mode 100644 .agents/skills/python-wizard-template/templates/module_template.py create mode 100644 .agents/skills/python-wizard-template/templates/test_template.py create mode 100644 docs/user-guide/agent-skills.md diff --git a/.agents/skills/python-wizard-template/README.md b/.agents/skills/python-wizard-template/README.md new file mode 100644 index 0000000..75b2e68 --- /dev/null +++ b/.agents/skills/python-wizard-template/README.md @@ -0,0 +1,115 @@ +# Python Wizard Template Agent Skill + +This directory contains an [Agent Skill](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills) for GitHub Copilot and other AI assistants. + +## What is This? + +This skill teaches AI assistants how to work effectively with Python projects that use the wizard-template. It provides comprehensive guidance for: + +1. **New projects** - Starting fresh from the template +2. **Migration** - Applying template structure to existing projects +3. **Updates** - Incorporating template changes into your project +4. **Best practices** - Following wizard-template conventions + +## How AI Assistants Use This + +When you work with a project that uses wizard-template: + +- AI assistants (like GitHub Copilot) automatically load this skill +- They learn about Hatch commands, code quality standards, and project structure +- They can help with common tasks like adding modules, writing tests, and updating configurations +- They provide better suggestions that follow wizard-template conventions + +## Installation Options + +### Option 1: Comes with Template (Default) + +If you created your project from wizard-template, this skill is already included! AI assistants will automatically use it when working in your repository. + +### Option 2: User-Level Installation + +To use this skill across **all** your repositories (not just template-based ones): + +```bash +# Copy to your user skills directory +mkdir -p ~/.agents/skills +cp -r .agents/skills/python-wizard-template ~/.agents/skills/ + +# Or symlink if you have wizard-template cloned locally +ln -s /path/to/wizard-template/.agents/skills/python-wizard-template ~/.agents/skills/python-wizard-template +``` + +### Option 3: Add to Existing Project + +To add this skill to a project that didn't start from wizard-template: + +```bash +# In your project directory +mkdir -p .agents/skills +cp -r /path/to/wizard-template/.agents/skills/python-wizard-template .agents/skills/ +git add .agents +git commit -m "Add wizard-template agent skill" +``` + +## What's Inside + +``` +python-wizard-template/ +├── SKILL.md # Main skill definition (comprehensive guide) +├── examples/ # Example code following best practices +│ ├── module_example.py # Example module with proper style +│ ├── test_example.py # Example tests with various patterns +│ └── docs_example.md # Example documentation page +└── templates/ # Code templates + ├── module_template.py # Template for new modules + ├── test_template.py # Template for new tests + └── check-template-updates.sh # Helper script for checking updates +``` + +## Covered Scenarios + +The skill provides guidance for: + +### For New Projects +- Running the renaming wizard (`hatch run _wizard`) +- Setting up development environment +- Installing pre-commit hooks +- Understanding project structure + +### For Existing Projects (Migration) +- Assessing current project structure +- Choosing migration strategy (full vs. gradual) +- Applying template configurations selectively +- Testing after migration + +### For Updates +- Tracking template changes +- Selectively applying updates +- Avoiding common pitfalls +- Testing changes + +### For Daily Development +- Using Hatch commands correctly +- Following code quality standards +- Writing proper docstrings +- Maintaining test coverage +- Building documentation + +## Relationship with copilot-instructions.md + +This skill **complements** `.github/copilot-instructions.md`: + +- **copilot-instructions.md**: Quick reference, always loaded +- **This skill**: Comprehensive guide, loaded on-demand + +Both files serve different purposes and are maintained separately. The skill provides deeper guidance for complex scenarios like migration and updates, while copilot-instructions.md provides quick context for everyday development. + +## Learn More + +- [Full wizard-template documentation](https://docs.fschuch.com/wizard-template) +- [GitHub Copilot Agent Skills](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills) +- [Template repository](https://github.com/fschuch/wizard-template) + +## Contributing + +Found an issue or have a suggestion? Please [open an issue](https://github.com/fschuch/wizard-template/issues) in the wizard-template repository. diff --git a/.agents/skills/python-wizard-template/SKILL.md b/.agents/skills/python-wizard-template/SKILL.md new file mode 100644 index 0000000..0f32bd7 --- /dev/null +++ b/.agents/skills/python-wizard-template/SKILL.md @@ -0,0 +1,524 @@ +--- +name: python-wizard-template +description: Expert guidance for working with Python projects using the wizard-template, including new projects, migrations, updates, and best practices for Hatch workflows and quality standards. +license: MIT +--- + +# Python Wizard Template Skill + +This skill provides comprehensive guidance for AI assistants working with Python projects that use or want to use the [wizard-template](https://github.com/fschuch/wizard-template). It covers three main scenarios: new projects from template, applying template to existing projects, and updating projects with template changes. + +## When to Use This Skill + +### Automatic Detection + +This skill applies when ANY of these conditions are met: + +- Repository has a "Wizard Template" badge in README.md +- File `src/wizard_template/` directory exists (pre-renamed template) +- File `pyproject.toml` references `wizard-template` in URLs or comments +- File `.github/copilot-instructions.md` references wizard-template +- User explicitly mentions using wizard-template + +### User Requests + +This skill also applies when users ask to: + +- Start a new Python project with quality tools +- Apply wizard-template structure to an existing project +- Update their project with latest template changes +- Set up Hatch, testing, documentation, or CI/CD from wizard-template + +## Scenario 1: New Project from Template (Fresh Clone) + +### CRITICAL First Step + +**When `src/wizard_template/` exists, you MUST run the renaming wizard FIRST:** + +```bash +hatch run _wizard +``` + +This script: +- Detects the git repository URL automatically +- Replaces all `wizard-template` references with the actual project name +- Replaces all `fschuch` references with the actual username +- Renames `src/wizard_template/` to `src/{project_name}/` +- Removes itself after completion (cleanup) + +**DO NOT** make any other changes before running this script! + +### After Renaming + +1. Install pre-commit hooks: + ```bash + hatch run pre-commit-install + ``` + +2. Verify the setup: + ```bash + hatch run qa + ``` + +3. Update documentation in `docs/intro.md` with project-specific content + +## Scenario 2: Applying Template to Existing Project + +When a user wants to apply wizard-template structure to an existing Python project that has a different structure, follow this **gradual migration approach**: + +### Assessment Phase + +1. **Analyze current structure:** + - Identify package layout (flat vs src layout) + - Check existing tools (pytest, linting, docs) + - Review current dependencies and build system + - Note any custom CI/CD configurations + +2. **Determine migration strategy:** + - Full migration (recommended for small/new projects) + - Gradual migration (recommended for large/established projects) + +### Full Migration Steps + +Use when project is small, young, or highly compatible: + +1. **Backup current state:** + ```bash + git checkout -b backup-before-wizard-template + git checkout -b migrate-to-wizard-template + ``` + +2. **Clone template reference:** + ```bash + cd /tmp + git clone https://github.com/fschuch/wizard-template.git wizard-ref + ``` + +3. **Copy core configuration files:** + - `pyproject.toml` (merge dependencies, keep project metadata) + - `.pre-commit-config.yaml` + - `.github/workflows/` (CI/CD workflows) + - `docs/` structure (merge with existing docs) + +4. **Migrate to src/ layout:** + ```bash + # If package is currently at project root + mkdir -p src + mv {package_name} src/ + ``` + +5. **Update import paths** in tests and code if needed + +6. **Run quality checks:** + ```bash + hatch run qa + ``` + +### Gradual Migration Steps + +Use when project is large, established, or has significant customizations: + +1. **Phase 1 - Build System:** + - Add Hatch configuration to `pyproject.toml` + - Keep existing build system temporarily + - Test with: `hatch run test-no-cov` + +2. **Phase 2 - Code Quality:** + - Add Ruff configuration + - Add MyPy configuration + - Run and fix issues: `hatch run lint`, `hatch run type` + +3. **Phase 3 - Testing:** + - Add pytest configuration + - Add coverage configuration + - Migrate existing tests to pytest if needed + +4. **Phase 4 - Documentation:** + - Add Jupyter Book structure + - Migrate existing docs to MyST markdown + - Set up docs build: `hatch run docs:build` + +5. **Phase 5 - CI/CD:** + - Copy GitHub Actions workflows + - Adapt to project-specific needs + - Test in feature branch + +6. **Phase 6 - Pre-commit Hooks:** + - Add pre-commit configuration + - Install: `hatch run pre-commit-install` + +### Key Files to Customize + +When migrating, **DO NOT** blindly copy these - customize them: + +- `pyproject.toml` - Keep your project name, description, dependencies +- `README.md` - Keep your project content, add wizard badge +- `docs/intro.md` - Replace with your project documentation +- `LICENSE` - Keep your license (unless changing) + +### Files Safe to Copy + +These can typically be copied directly: + +- `.pre-commit-config.yaml` +- `.github/workflows/ci.yaml` +- `.github/workflows/docs.yaml` +- `.github/workflows/check-links.yaml` +- `.github/copilot-instructions.md` +- `.agents/` (this skill!) + +## Scenario 3: Updating Project with Template Changes + +When wizard-template releases updates and you want to incorporate them: + +### Tracking Template Updates + +1. **Add template as remote (one-time setup):** + ```bash + git remote add template https://github.com/fschuch/wizard-template.git + git fetch template + ``` + +2. **Check for template changes:** + ```bash + git fetch template + git log HEAD..template/main --oneline + ``` + +3. **Review template changes:** + ```bash + git diff HEAD...template/main + ``` + +### Selective Update Strategy + +**IMPORTANT:** Never merge template directly! It will break your project. + +Instead, **selectively apply changes:** + +1. **Identify what changed:** + ```bash + # See changed files + git diff --name-only HEAD...template/main + + # See specific file changes + git diff HEAD...template/main -- pyproject.toml + ``` + +2. **Common update patterns:** + + **Update tool configurations:** + ```bash + # Compare configurations + git show template/main:pyproject.toml > /tmp/template-pyproject.toml + # Manually merge relevant sections + ``` + + **Update workflows:** + ```bash + # Copy specific workflow + git show template/main:.github/workflows/ci.yaml > .github/workflows/ci.yaml + # Review and adjust for your project + ``` + + **Update dependencies:** + ```bash + # Check template dependency versions + git show template/main:pyproject.toml | grep -A 20 "dependencies" + # Update your versions as needed + ``` + +3. **Test after each update:** + ```bash + hatch run qa + ``` + +### Automated Update Helper + +Create a script to compare configurations: + +```bash +#!/bin/bash +# tools/check-template-updates.sh + +echo "Fetching template updates..." +git fetch template + +echo -e "\n=== Changed files in template ===" +git diff --name-only HEAD...template/main + +echo -e "\n=== Tool configuration changes ===" +git diff HEAD...template/main -- pyproject.toml .pre-commit-config.yaml + +echo -e "\n=== Workflow changes ===" +git diff HEAD...template/main -- .github/workflows/ +``` + +## Project Management Tool: Hatch + +All projects using wizard-template use [Hatch](https://hatch.pypa.io/) as the primary project management tool. + +### Essential Hatch Commands + +```bash +# Development workflow +hatch run test # Run tests with coverage +hatch run test-no-cov # Run tests without coverage (faster) +hatch run lint # Run ruff linter +hatch run format # Check code formatting +hatch run type # Run mypy type checking +hatch run check # Run pre-commit checks +hatch run qa # Run ALL quality checks + tests + +# Documentation +hatch run docs:build # Build documentation +hatch run docs:serve # Serve docs with live reload + +# Pre-commit +hatch run pre-commit-install # Install pre-commit hooks +``` + +### Hatch Environment Configuration + +Configure Hatch to keep virtual environments in project folder: + +```bash +hatch config set dirs.env.virtual .venv +``` + +## Code Quality Standards + +### Required Conventions + +1. **Google-style docstrings** for all public functions/classes +2. **Type hints** on all function signatures +3. **90% test coverage** minimum (configured in pyproject.toml) +4. **Ruff** for linting and formatting +5. **MyPy** for static type checking + +### Example: Adding a New Module + +```python +# src/{project_name}/my_module.py +"""Module for doing something useful. + +This module provides functionality for... +""" + +def calculate_something(value: int, multiplier: float = 1.5) -> float: + """Calculate something useful. + + Args: + value: The input value to process. + multiplier: The multiplication factor. + + Returns: + The calculated result. + + Raises: + ValueError: If value is negative. + + Examples: + >>> calculate_something(10) + 15.0 + >>> calculate_something(10, multiplier=2.0) + 20.0 + """ + if value < 0: + raise ValueError("Value must be non-negative") + return value * multiplier +``` + +### Example: Corresponding Test + +```python +# tests/test_my_module.py +"""Tests for my_module.""" + +import pytest + +from my_project.my_module import calculate_something + + +def test_calculate_something_basic(): + """Test basic calculation.""" + result = calculate_something(10) + assert result == 15.0 + + +def test_calculate_something_with_multiplier(): + """Test calculation with custom multiplier.""" + result = calculate_something(10, multiplier=2.0) + assert result == 20.0 + + +def test_calculate_something_negative_value(): + """Test that negative values raise ValueError.""" + with pytest.raises(ValueError, match="non-negative"): + calculate_something(-1) +``` + +## Project Structure + +Standard wizard-template structure: + +``` +. +├── src/{project_name}/ # Main package (after renaming) +│ ├── __init__.py +│ └── core.py +├── tests/ # Test files +│ ├── __init__.py +│ └── test_core.py +├── docs/ # Documentation (Jupyter Book) +│ ├── intro.md +│ ├── getting-started/ +│ ├── user-guide/ +│ └── references/ +├── tools/ # Helper scripts +│ └── rename_project_content.py +├── .github/ # GitHub-specific files +│ ├── workflows/ # CI/CD workflows +│ ├── copilot-instructions.md +│ └── dependabot.yml +├── .agents/ # Agent skills (you are here!) +│ └── skills/ +├── pyproject.toml # Project configuration +├── .pre-commit-config.yaml # Pre-commit hooks +└── README.md # Project README +``` + +## CI/CD Workflows + +Template includes these GitHub Actions workflows: + +- **ci.yaml**: Runs tests on Python 3.10-3.14 +- **docs.yaml**: Builds and deploys docs to GitHub Pages +- **check-links.yaml**: Validates documentation links +- **update-pre-commits.yaml**: Auto-updates pre-commit hooks + +## Development Workflow Checklist + +For any change to code: + +- [ ] Create feature branch +- [ ] Make code changes with type hints +- [ ] Add Google-style docstrings +- [ ] Add/update tests (maintain 90% coverage) +- [ ] Run `hatch run qa` (all quality checks pass) +- [ ] Commit changes +- [ ] Push and create pull request + +## Common Pitfalls to Avoid + +1. **DON'T** skip the renaming wizard on new projects +2. **DON'T** use pip/pytest directly - use `hatch run` commands +3. **DON'T** commit `__pycache__`, `.venv`, `build/`, or other artifacts +4. **DON'T** merge template directly when updating - selectively apply changes +5. **DON'T** remove the Wizard Template badge from README +6. **DON'T** forget to run `hatch run qa` before committing +7. **DON'T** add dependencies without checking pyproject.toml structure + +## Troubleshooting + +### "hatch: command not found" + +```bash +pip install hatch +# or +pipx install hatch +``` + +### "Module not found" errors in tests + +Ensure you're using src layout correctly: + +```bash +# Install in development mode +hatch run test +``` + +### Pre-commit hooks fail + +```bash +# Update hooks +hatch run check + +# Fix auto-fixable issues +hatch run format +``` + +### Coverage below 90% + +```bash +# See coverage report +hatch run test + +# Add missing tests for uncovered lines +``` + +## Cross-Repository Usage + +### Using This Skill in Other Repositories + +This skill is designed to be portable. You can use it in any repository: + +#### Option 1: Project-Level (Recommended for Teams) + +Copy this skill directory to your project: + +```bash +# In your project repository +mkdir -p .agents/skills +cp -r /path/to/wizard-template/.agents/skills/python-wizard-template .agents/skills/ +git add .agents +git commit -m "Add wizard-template agent skill" +``` + +All team members working on the repository will automatically benefit. + +#### Option 2: User-Level (Personal Use Across All Projects) + +Install for your user account to use across all repositories: + +```bash +# Copy to user-level skills directory +mkdir -p ~/.agents/skills +cp -r /path/to/wizard-template/.agents/skills/python-wizard-template ~/.agents/skills/ + +# Or clone template and symlink +git clone https://github.com/fschuch/wizard-template.git ~/wizard-template +ln -s ~/wizard-template/.agents/skills/python-wizard-template ~/.agents/skills/python-wizard-template +``` + +This makes the skill available in ALL repositories you work on. + +#### Option 3: Organization-Level (Future) + +GitHub is developing organization-wide skills support. When available, organizations will be able to deploy skills centrally for all members and repositories. + +### When to Use Each Option + +- **Project-level**: Working on a specific project that uses wizard-template patterns +- **User-level**: You want wizard-template guidance available everywhere you work +- **Organization-level**: Your organization has standardized on wizard-template + +## References and Resources + +- Full documentation: +- Template repository: +- Report issues: +- Hatch documentation: +- Ruff documentation: +- Jupyter Book documentation: + +## Relationship with copilot-instructions.md + +This skill **complements** `.github/copilot-instructions.md`: + +- **copilot-instructions.md**: Always loaded, provides quick reference +- **This skill**: Loaded on-demand, provides comprehensive guidance including migration and updates + +Both files are maintained and serve different purposes: +- Use copilot-instructions.md for quick lookup and context +- Use this skill for detailed workflows, migration, and troubleshooting diff --git a/.agents/skills/python-wizard-template/examples/docs_example.md b/.agents/skills/python-wizard-template/examples/docs_example.md new file mode 100644 index 0000000..d2180d1 --- /dev/null +++ b/.agents/skills/python-wizard-template/examples/docs_example.md @@ -0,0 +1,111 @@ +# Example Documentation Page + +This is an example of how documentation should be structured in projects +using the wizard-template. + +## Overview + +Use MyST Markdown for documentation. It supports both standard Markdown +and reStructuredText directives. + +## Code Examples + +Include code blocks with syntax highlighting: + +```python +from my_package import DataProcessor + +# Create a processor +processor = DataProcessor(multiplier=2.0) + +# Process a value +result = processor.process(10) +print(result) # Output: 20.0 +``` + +## Admonitions + +Use admonitions for important information: + +```{note} +This is a note admonition. Use it for helpful tips. +``` + +```{warning} +This is a warning admonition. Use it for important caveats. +``` + +```{tip} +This is a tip admonition. Use it for best practices. +``` + +## Cross-References + +Link to other documentation pages: + +- [Getting Started](../getting-started/index.md) +- [API Reference](../references/api.md) + +## API Documentation + +Include docstrings in your API docs: + +```{eval-rst} +.. automodule:: my_package.module_example + :members: + :undoc-members: + :show-inheritance: +``` + +## Tables + +Use Markdown tables: + +| Command | Description | +|---------|-------------| +| `hatch run test` | Run tests with coverage | +| `hatch run lint` | Run linter | +| `hatch run qa` | Run all quality checks | + +## Lists + +Ordered lists: + +1. First step +2. Second step +3. Third step + +Unordered lists: + +- Item one +- Item two +- Item three + +## Images + +Include images with captions: + +```{figure} ../logo.png +:alt: Project logo +:width: 300px + +The project logo. +``` + +## Math + +Include mathematical expressions using LaTeX: + +```{math} +E = mc^2 +``` + +Inline math: $a^2 + b^2 = c^2$ + +## Links + +- External link: [Hatch documentation](https://hatch.pypa.io/) +- Internal link: [Introduction](intro.md) +- Reference link: [About the Project][project-link] + +[project-link]: https://github.com/your-user/your-project diff --git a/.agents/skills/python-wizard-template/examples/module_example.py b/.agents/skills/python-wizard-template/examples/module_example.py new file mode 100644 index 0000000..6c320e8 --- /dev/null +++ b/.agents/skills/python-wizard-template/examples/module_example.py @@ -0,0 +1,81 @@ +"""Example module following wizard-template conventions. + +This module demonstrates the coding standards and patterns expected in +projects created from the wizard-template. +""" + +from typing import Any + + +def process_data(data: list[Any], *, filter_empty: bool = True) -> list[Any]: + """Process a list of data items. + + This function demonstrates proper docstring format, type hints, + and keyword-only arguments. + + Args: + data: List of items to process. + filter_empty: Whether to filter out empty items. + + Returns: + Processed list of items. + + Raises: + ValueError: If data is None. + + Examples: + >>> process_data([1, 2, 3]) + [1, 2, 3] + >>> process_data([1, "", 3], filter_empty=True) + [1, 3] + >>> process_data([1, "", 3], filter_empty=False) + [1, '', 3] + """ + if data is None: + raise ValueError("data cannot be None") + + if filter_empty: + return [item for item in data if item] + return data + + +class DataProcessor: + """A class for processing data with state. + + This class demonstrates proper class documentation and initialization. + + Attributes: + multiplier: Factor to multiply processed values. + strict_mode: Whether to raise errors on invalid data. + + Examples: + >>> processor = DataProcessor(multiplier=2.0) + >>> processor.process(5) + 10.0 + """ + + def __init__(self, multiplier: float = 1.0, *, strict_mode: bool = False) -> None: + """Initialize the DataProcessor. + + Args: + multiplier: Factor to multiply processed values. + strict_mode: Whether to raise errors on invalid data. + """ + self.multiplier = multiplier + self.strict_mode = strict_mode + + def process(self, value: int | float) -> float: + """Process a single value. + + Args: + value: The value to process. + + Returns: + The processed value. + + Raises: + ValueError: If value is negative and strict_mode is True. + """ + if self.strict_mode and value < 0: + raise ValueError("Negative values not allowed in strict mode") + return float(value) * self.multiplier diff --git a/.agents/skills/python-wizard-template/examples/test_example.py b/.agents/skills/python-wizard-template/examples/test_example.py new file mode 100644 index 0000000..624b8e5 --- /dev/null +++ b/.agents/skills/python-wizard-template/examples/test_example.py @@ -0,0 +1,92 @@ +"""Example test file following wizard-template conventions. + +This module demonstrates testing patterns expected in projects created +from the wizard-template. +""" + +import pytest + +from my_package.module_example import DataProcessor, process_data + + +class TestProcessData: + """Test suite for process_data function.""" + + def test_process_data_basic(self) -> None: + """Test basic data processing.""" + result = process_data([1, 2, 3]) + assert result == [1, 2, 3] + + def test_process_data_filter_empty(self) -> None: + """Test filtering empty items.""" + result = process_data([1, "", None, 3], filter_empty=True) + assert result == [1, 3] + + def test_process_data_no_filter(self) -> None: + """Test without filtering.""" + result = process_data([1, "", 3], filter_empty=False) + assert result == [1, "", 3] + + def test_process_data_none_raises(self) -> None: + """Test that None input raises ValueError.""" + with pytest.raises(ValueError, match="cannot be None"): + process_data(None) + + @pytest.mark.parametrize( + ("input_data", "expected"), + [ + ([1, 2, 3], [1, 2, 3]), + ([1, "", 3], [1, 3]), + ([], []), + ], + ) + def test_process_data_parametrized( + self, input_data: list, expected: list + ) -> None: + """Test process_data with various inputs using parametrize.""" + result = process_data(input_data, filter_empty=True) + assert result == expected + + +class TestDataProcessor: + """Test suite for DataProcessor class.""" + + def test_init_defaults(self) -> None: + """Test initialization with default values.""" + processor = DataProcessor() + assert processor.multiplier == 1.0 + assert processor.strict_mode is False + + def test_init_custom(self) -> None: + """Test initialization with custom values.""" + processor = DataProcessor(multiplier=2.5, strict_mode=True) + assert processor.multiplier == 2.5 + assert processor.strict_mode is True + + def test_process_basic(self) -> None: + """Test basic value processing.""" + processor = DataProcessor(multiplier=2.0) + result = processor.process(5) + assert result == 10.0 + + def test_process_negative_strict(self) -> None: + """Test that negative values raise error in strict mode.""" + processor = DataProcessor(strict_mode=True) + with pytest.raises(ValueError, match="Negative values not allowed"): + processor.process(-5) + + def test_process_negative_non_strict(self) -> None: + """Test that negative values work in non-strict mode.""" + processor = DataProcessor(multiplier=2.0, strict_mode=False) + result = processor.process(-5) + assert result == -10.0 + + @pytest.fixture + def processor(self) -> DataProcessor: + """Fixture providing a DataProcessor instance.""" + return DataProcessor(multiplier=3.0) + + def test_with_fixture(self, processor: DataProcessor) -> None: + """Test using fixture.""" + result = processor.process(4) + assert result == 12.0 diff --git a/.agents/skills/python-wizard-template/templates/check-template-updates.sh b/.agents/skills/python-wizard-template/templates/check-template-updates.sh new file mode 100644 index 0000000..5b5492a --- /dev/null +++ b/.agents/skills/python-wizard-template/templates/check-template-updates.sh @@ -0,0 +1,50 @@ +#!/bin/bash +# Script to check for template updates +# Usage: tools/check-template-updates.sh + +set -e + +echo "=== Wizard Template Update Checker ===" +echo "" + +# Check if template remote exists +if ! git remote | grep -q "^template$"; then + echo "Adding wizard-template as remote 'template'..." + git remote add template https://github.com/fschuch/wizard-template.git +fi + +echo "Fetching latest template changes..." +git fetch template + +echo "" +echo "=== Changed files in template since your last sync ===" +git diff --name-only HEAD...template/main + +echo "" +echo "=== Summary of changes ===" +git log HEAD..template/main --oneline --no-decorate | head -20 + +echo "" +echo "=== Tool configuration changes ===" +echo "Changes in pyproject.toml:" +git diff HEAD...template/main -- pyproject.toml | head -50 + +echo "" +echo "Changes in pre-commit config:" +git diff HEAD...template/main -- .pre-commit-config.yaml | head -30 + +echo "" +echo "=== Workflow changes ===" +git diff --name-only HEAD...template/main -- .github/workflows/ + +echo "" +echo "=== Next steps ===" +echo "1. Review changes above" +echo "2. Selectively apply relevant changes (DO NOT merge directly)" +echo "3. Test with: hatch run qa" +echo "" +echo "To see full diff of a file:" +echo " git diff HEAD...template/main -- path/to/file" +echo "" +echo "To copy a specific file (BE CAREFUL):" +echo " git show template/main:path/to/file > path/to/file" diff --git a/.agents/skills/python-wizard-template/templates/module_template.py b/.agents/skills/python-wizard-template/templates/module_template.py new file mode 100644 index 0000000..b5394ac --- /dev/null +++ b/.agents/skills/python-wizard-template/templates/module_template.py @@ -0,0 +1,58 @@ +"""{{MODULE_DESCRIPTION}}. + +This module provides functionality for... +""" + +from typing import Any + + +def {{FUNCTION_NAME}}({{PARAMETERS}}) -> {{RETURN_TYPE}}: + """{{FUNCTION_DESCRIPTION}}. + + Args: + {{PARAMETER_NAME}}: {{PARAMETER_DESCRIPTION}}. + + Returns: + {{RETURN_DESCRIPTION}}. + + Raises: + {{EXCEPTION_TYPE}}: {{EXCEPTION_DESCRIPTION}}. + + Examples: + >>> {{FUNCTION_NAME}}({{EXAMPLE_ARGS}}) + {{EXAMPLE_OUTPUT}} + """ + # Implementation goes here + pass + + +class {{CLASS_NAME}}: + """{{CLASS_DESCRIPTION}}. + + Attributes: + {{ATTRIBUTE_NAME}}: {{ATTRIBUTE_DESCRIPTION}}. + + Examples: + >>> obj = {{CLASS_NAME}}({{INIT_ARGS}}) + >>> obj.{{METHOD_NAME}}({{METHOD_ARGS}}) + {{METHOD_OUTPUT}} + """ + + def __init__(self, {{INIT_PARAMETERS}}) -> None: + """Initialize the {{CLASS_NAME}}. + + Args: + {{INIT_PARAM_NAME}}: {{INIT_PARAM_DESCRIPTION}}. + """ + pass + + def {{METHOD_NAME}}(self, {{METHOD_PARAMETERS}}) -> {{METHOD_RETURN_TYPE}}: + """{{METHOD_DESCRIPTION}}. + + Args: + {{METHOD_PARAM_NAME}}: {{METHOD_PARAM_DESCRIPTION}}. + + Returns: + {{METHOD_RETURN_DESCRIPTION}}. + """ + pass diff --git a/.agents/skills/python-wizard-template/templates/test_template.py b/.agents/skills/python-wizard-template/templates/test_template.py new file mode 100644 index 0000000..e7afd7f --- /dev/null +++ b/.agents/skills/python-wizard-template/templates/test_template.py @@ -0,0 +1,58 @@ +"""Tests for {{MODULE_NAME}}. + +This module contains tests for the {{MODULE_NAME}} module. +""" + +import pytest + +from {{PACKAGE_NAME}}.{{MODULE_NAME}} import {{CLASS_OR_FUNCTION_NAME}} + + +class Test{{ClassName}}: + """Test suite for {{CLASS_OR_FUNCTION_NAME}}.""" + + def test_{{test_name}}_basic(self) -> None: + """Test basic functionality.""" + # Arrange + {{ARRANGE_CODE}} + + # Act + result = {{ACT_CODE}} + + # Assert + assert result == {{EXPECTED_VALUE}} + + def test_{{test_name}}_edge_case(self) -> None: + """Test edge case handling.""" + # Test implementation + pass + + def test_{{test_name}}_raises_exception(self) -> None: + """Test that invalid input raises appropriate exception.""" + with pytest.raises({{EXCEPTION_TYPE}}, match="{{ERROR_MESSAGE}}"): + {{CODE_THAT_RAISES}} + + @pytest.mark.parametrize( + ("input_value", "expected"), + [ + ({{INPUT_1}}, {{EXPECTED_1}}), + ({{INPUT_2}}, {{EXPECTED_2}}), + ({{INPUT_3}}, {{EXPECTED_3}}), + ], + ) + def test_{{test_name}}_parametrized( + self, input_value: {{INPUT_TYPE}}, expected: {{EXPECTED_TYPE}} + ) -> None: + """Test with multiple inputs using parametrize.""" + result = {{FUNCTION_CALL}}(input_value) + assert result == expected + + @pytest.fixture + def {{fixture_name}}(self) -> {{FIXTURE_TYPE}}: + """Fixture providing {{FIXTURE_DESCRIPTION}}.""" + return {{FIXTURE_VALUE}} + + def test_with_fixture(self, {{fixture_name}}: {{FIXTURE_TYPE}}) -> None: + """Test using fixture.""" + result = {{FUNCTION_CALL}}({{fixture_name}}) + assert result is not None diff --git a/README.md b/README.md index 7afeeb4..05827b5 100644 --- a/README.md +++ b/README.md @@ -33,12 +33,16 @@ Check out the documentation for more details on how to use the template and its ### For AI Assistants -If you're an AI coding assistant (like GitHub Copilot), please read [`.github/copilot-instructions.md`](.github/copilot-instructions.md) for important context about this template, including: +This template includes an [Agent Skill](.agents/skills/python-wizard-template/) that teaches AI assistants (like GitHub Copilot) how to work effectively with wizard-template projects. The skill provides comprehensive guidance for: -- First-time setup requirements (running the renaming script) -- Project management tools (Hatch commands) -- Quality assurance workflow -- Development patterns and best practices +- **New projects**: Starting fresh from the template +- **Migration**: Applying template structure to existing projects +- **Updates**: Incorporating template changes into your project +- **Best practices**: Following wizard-template conventions + +AI assistants will automatically use this skill when working in repositories created from this template. You can also [install it at user-level](.agents/skills/python-wizard-template/README.md#installation-options) to use across all your projects. + +Additionally, [`.github/copilot-instructions.md`](.github/copilot-instructions.md) provides quick reference context for everyday development tasks. ## Copyright and License diff --git a/docs/_toc.yml b/docs/_toc.yml index 6e7dc99..04e00db 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -22,6 +22,7 @@ parts: - file: user-guide/documentation.md - file: user-guide/versioning-changelog.md - file: user-guide/ci-cd.md + - file: user-guide/agent-skills.md - caption: References chapters: - file: references/further-reading.md diff --git a/docs/user-guide/agent-skills.md b/docs/user-guide/agent-skills.md new file mode 100644 index 0000000..32e1499 --- /dev/null +++ b/docs/user-guide/agent-skills.md @@ -0,0 +1,273 @@ +# AI Agent Skills + +The wizard-template includes a comprehensive [Agent Skill](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills) for GitHub Copilot and other AI assistants. This skill teaches AI how to work effectively with projects that use wizard-template patterns and conventions. + +## What Are Agent Skills? + +Agent Skills are special instruction sets that teach AI assistants about specific workflows, patterns, and best practices. They provide: + +- **Context-aware guidance**: AI understands your project structure and conventions +- **Task-specific help**: Detailed instructions for common scenarios +- **Code examples**: Patterns and templates that follow best practices +- **Troubleshooting**: Solutions to common problems + +## Wizard-Template Agent Skill + +The wizard-template agent skill is located in `.agents/skills/python-wizard-template/` and provides comprehensive guidance for: + +### Scenario 1: New Projects from Template + +When starting a new project from wizard-template, the skill helps AI assistants: + +- Recognize the need to run `hatch run _wizard` first +- Guide through initial setup and configuration +- Explain project structure and conventions +- Help with first module and test creation + +### Scenario 2: Applying Template to Existing Projects + +When you want to migrate an existing Python project to use wizard-template structure, the skill provides: + +- **Assessment guidance**: How to analyze your current project structure +- **Migration strategies**: Full migration vs. gradual adoption +- **Step-by-step instructions**: Detailed migration phases +- **Safety practices**: Backing up and testing changes + +Example migration workflow: + +```bash +# 1. Backup current state +git checkout -b backup-before-wizard-template +git checkout -b migrate-to-wizard-template + +# 2. Clone template for reference +cd /tmp +git clone https://github.com/fschuch/wizard-template.git wizard-ref + +# 3. Copy and adapt configurations +# (AI assistant helps identify what to copy/adapt) + +# 4. Test incrementally +hatch run qa +``` + +### Scenario 3: Updating Projects with Template Changes + +When wizard-template releases updates, the skill helps: + +- Track template changes over time +- Selectively apply relevant updates +- Avoid breaking changes +- Test after each update + +Example update workflow: + +```bash +# Add template as remote (one-time) +git remote add template https://github.com/fschuch/wizard-template.git +git fetch template + +# Check for updates +git log HEAD..template/main --oneline + +# Review specific changes +git diff HEAD...template/main -- pyproject.toml + +# Apply selectively (never merge directly!) +# AI assistant helps identify what to update +``` + +A helper script is provided in the skill's templates directory. + +## Installation Options + +### Option 1: Project-Level (Default) + +If you created your project from wizard-template, the skill is already included in `.agents/skills/`. All team members working on the repository automatically benefit. + +**Pros:** +- Automatic for all contributors +- Version controlled with project +- Team-wide consistency + +**Cons:** +- Only available in this repository + +### Option 2: User-Level (Personal) + +Install the skill globally for your user account to use across **all** repositories: + +```bash +# Copy to user skills directory +mkdir -p ~/.agents/skills +cp -r .agents/skills/python-wizard-template ~/.agents/skills/ + +# Or symlink if you have wizard-template cloned locally +ln -s /path/to/wizard-template/.agents/skills/python-wizard-template ~/.agents/skills/python-wizard-template +``` + +**Pros:** +- Available in all repositories you work on +- Personal productivity boost +- Works even in non-template projects + +**Cons:** +- Not shared with team members +- Requires manual installation/updates + +### Option 3: Organization-Level (Future) + +GitHub is developing organization-wide agent skills. When available, organizations will be able to deploy skills centrally for all members and repositories. + +## How AI Assistants Use the Skill + +When you work with Copilot or other AI assistants in a wizard-template project: + +1. **Automatic detection**: The AI recognizes you're using wizard-template +2. **Skill loading**: Relevant sections of the skill are loaded based on context +3. **Enhanced suggestions**: AI provides wizard-template-specific guidance +4. **Pattern following**: Suggestions follow template conventions + +For example: + +- When adding a new module, AI suggests Google-style docstrings and type hints +- When writing tests, AI uses pytest patterns with proper fixtures +- When updating configs, AI checks template best practices +- When you ask about Hatch commands, AI provides correct usage + +## Skill Contents + +The agent skill includes: + +``` +.agents/skills/python-wizard-template/ +├── SKILL.md # Main skill definition +│ ├── Scenario 1: New projects +│ ├── Scenario 2: Migration +│ ├── Scenario 3: Updates +│ ├── Hatch commands +│ ├── Code quality standards +│ └── Troubleshooting +├── examples/ +│ ├── module_example.py # Example module with best practices +│ ├── test_example.py # Example tests with patterns +│ └── docs_example.md # Example documentation +├── templates/ +│ ├── module_template.py # Template for new modules +│ ├── test_template.py # Template for new tests +│ └── check-template-updates.sh # Helper script +└── README.md # Installation and usage guide +``` + +## Relationship with Copilot Instructions + +The agent skill **complements** `.github/copilot-instructions.md`: + +| File | Purpose | When Loaded | Best For | +|------|---------|-------------|----------| +| `.github/copilot-instructions.md` | Quick reference | Always | Everyday development | +| `.agents/skills/python-wizard-template/` | Comprehensive guide | On-demand | Complex scenarios | + +Both are maintained and serve different purposes: + +- **copilot-instructions.md**: Provides context that's always available for quick lookups +- **Agent skill**: Provides detailed workflows for migration, updates, and troubleshooting + +## Using the Skill Effectively + +### For New Projects + +When you start a new project from the template, simply work naturally with your AI assistant. It will: + +- Remind you to run `hatch run _wizard` if needed +- Suggest proper project structure +- Help with initial module creation +- Guide testing and documentation + +### For Migration + +When migrating an existing project, tell your AI assistant explicitly: + +> "I want to apply wizard-template structure to this project. Help me assess and migrate." + +The AI will: + +- Analyze your current structure +- Suggest a migration strategy +- Guide you through each phase +- Help test changes + +### For Updates + +When updating from template changes, ask: + +> "Check if there are updates in wizard-template and help me apply them." + +The AI will: + +- Help you compare with template +- Identify relevant changes +- Suggest what to update +- Warn about potential breaking changes + +## Example Interactions + +### Getting Started + +**You:** "How do I add a new module to this project?" + +**AI (with skill):** "In wizard-template projects, create your module in `src/{project_name}/` with Google-style docstrings and type hints. Here's the pattern..." + +### Migration Help + +**You:** "I have an existing Python project. How can I adopt wizard-template structure?" + +**AI (with skill):** "Let's assess your project first. I can help you either with a full migration or gradual adoption. First, let me check your current structure..." + +### Update Assistance + +**You:** "How do I update my project with the latest template changes?" + +**AI (with skill):** "Let's add the template as a remote and check for updates. Run: `git remote add template https://github.com/fschuch/wizard-template.git && git fetch template`..." + +## Troubleshooting + +### AI Not Using the Skill + +If your AI assistant doesn't seem to be using the skill: + +1. **Verify the skill exists**: Check `.agents/skills/python-wizard-template/SKILL.md` exists +2. **Update your AI tool**: Ensure you're using a version that supports agent skills +3. **Be explicit**: Mention "wizard-template" in your questions +4. **Check configuration**: Some tools require enabling agent skills in settings + +### Skill Not Found in Other Repos + +If you want to use the skill in repositories that don't include it: + +- Install at user-level (see [Installation Options](#option-2-user-level-personal) above) +- Or copy the skill directory to your project + +### Skill Conflicts + +If you have multiple skills with similar guidance: + +- Project-level skills take precedence over user-level +- More specific skills override general ones +- You can disable specific skills in your AI tool settings + +## Learn More + +- [GitHub Copilot Agent Skills Documentation](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills) +- [Wizard-Template Agent Skill README](./.../../.agents/skills/python-wizard-template/README.md) +- [Copilot Instructions](./../.github/copilot-instructions.md) + +## Contributing to the Skill + +Found an issue or have suggestions for the agent skill? + +1. [Open an issue](https://github.com/fschuch/wizard-template/issues) +2. Describe what guidance could be improved +3. Provide examples of AI mistakes or missing information + +The skill is continuously improved based on real-world usage and feedback. From 180ab5b705a7eb1cec6c8474ad45c22ca9343eff Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 13 Feb 2026 19:02:12 +0000 Subject: [PATCH 3/3] Fix documentation warnings and add cross-reference to agent skill Co-authored-by: fschuch <37457501+fschuch@users.noreply.github.com> --- .github/copilot-instructions.md | 4 +++- docs/user-guide/agent-skills.md | 6 +++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index aa4c5ef..2c0b1f1 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,6 +1,8 @@ # AI Agent Context for Wizard Template -This file provides context for AI coding assistants (like GitHub Copilot) working with projects created from this template. +This file provides quick reference context for AI coding assistants (like GitHub Copilot) working with projects created from this template. + +**For comprehensive guidance including migration and updates, see the [Agent Skill](../.agents/skills/python-wizard-template/SKILL.md) in `.agents/skills/python-wizard-template/`.** ## Template Overview diff --git a/docs/user-guide/agent-skills.md b/docs/user-guide/agent-skills.md index 32e1499..01102b8 100644 --- a/docs/user-guide/agent-skills.md +++ b/docs/user-guide/agent-skills.md @@ -245,7 +245,7 @@ If your AI assistant doesn't seem to be using the skill: If you want to use the skill in repositories that don't include it: -- Install at user-level (see [Installation Options](#option-2-user-level-personal) above) +- Install at user-level (see Installation Options section above, Option 2) - Or copy the skill directory to your project ### Skill Conflicts @@ -259,8 +259,8 @@ If you have multiple skills with similar guidance: ## Learn More - [GitHub Copilot Agent Skills Documentation](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills) -- [Wizard-Template Agent Skill README](./.../../.agents/skills/python-wizard-template/README.md) -- [Copilot Instructions](./../.github/copilot-instructions.md) +- Wizard-Template Agent Skill README (in `.agents/skills/python-wizard-template/README.md`) +- Copilot Instructions (in `.github/copilot-instructions.md`) ## Contributing to the Skill