PitLane-AI/
├── packages/
│   └── pitlane-agent/
│       ├── src/
│       │   └── pitlane_agent/
│       │       ├── .claude/
│       │       │   └── skills/
│       │       │       ├── skill-name/           # Flat skill
│       │       │       │   └── SKILL.md
│       │       │       └── parent-skill/         # Hierarchical skill
│       │       │           ├── SKILL.md          # Parent with table
│       │       │           ├── subskill-1.md     # Subskill 1
│       │       │           └── subskill-2.md     # Subskill 2
│       │       └── scripts/
│       │           └── script_name.py
│       └── tests/
│           └── scripts/
│               └── test_script_name.py

---
name: skill-name
description: Brief description of when to use this skill. Should explain the trigger conditions.
allowed-tools: Bash(python:*), Read, Write
---

# Skill Title

Introduction paragraph explaining what this skill does and its purpose.

## When to Use This Skill

Use this skill when users ask about:
- **Use case 1**: Describe when this applies (e.g., "Race calendars and event dates")
- **Use case 2**: Another trigger scenario
- **Use case 3**: Additional context

## Step 1: Understand the Request

Provide guidance on how to parse and understand the user's request. Include:
- What parameters to extract
- Default values to use
- How to handle ambiguous requests

## Step 2: Execute the Main Task

Instructions for performing the core functionality. This might include:
- Running a script with bash
- Reading/analyzing files
- Using other tools

### Example Commands

If this skill uses scripts, provide examples:

```bash
python -m pitlane_agent.scripts.script_name --param1 value --param2 value

## Step 2: Create a Hierarchical Skill

Hierarchical skills have a parent SKILL.md that references multiple subskill markdown files.

### Instructions

1. Create the parent skill directory:
   ```bash
   mkdir -p packages/pitlane-agent/src/pitlane_agent/.claude/skills/parent-skill-name

---
name: parent-skill
description: Parent skill managing multiple related subskills. Briefly explain the domain.
allowed-tools: Skill
---

# Parent Skill Title

This skill provides access to multiple related subskills for [domain/topic area].

## Available Subskills

| Subskill | Description | Documentation |
|----------|-------------|---------------|
| subskill-1 | Brief description of what it does | [subskill-1.md](./subskill-1.md) |
| subskill-2 | Brief description of what it does | [subskill-2.md](./subskill-2.md) |
| subskill-3 | Brief description of what it does | [subskill-3.md](./subskill-3.md) |

## How to Use

When a user asks about [topic], determine which subskill is most appropriate based on:
- **Criteria 1**: Use subskill-1
- **Criteria 2**: Use subskill-2
- **Criteria 3**: Use subskill-3

Invoke the appropriate subskill using the Skill tool.

## Example Questions

Map common user questions to the right subskill:

- "Question pattern 1" → Use subskill-1
- "Question pattern 2" → Use subskill-2
- "Question pattern 3" → Use subskill-3

## Notes

Any cross-cutting concerns or general guidance for using these subskills together.

# Subskill Title

Detailed instructions for this specific subskill. This file has the same structure as a flat SKILL.md but without the YAML front matter (that's only in the parent).

## When to Use

Specific trigger conditions for this subskill.

## Step 1: [First Step]

Detailed instructions...

## Step 2: [Second Step]

More instructions...

## Example Usage

Examples specific to this subskill...

"""
Brief description of what this script does.

Usage:
    python -m pitlane_agent.scripts.script_name [OPTIONS]
"""

import json
import sys
from pathlib import Path

import click


def main_function(
    param1: str,
    param2: int,
) -> dict:
    """Business logic function.

    Separate the business logic from CLI handling to make it easier to test.

    Args:
        param1: Description of first parameter
        param2: Description of second parameter

    Returns:
        Dictionary with results in a structured format

    Raises:
        ValueError: If validation fails
        RuntimeError: If operation fails
    """
    # Input validation
    if not param1:
        raise ValueError("param1 cannot be empty")

    if param2 < 0:
        raise ValueError("param2 must be non-negative")

    # Business logic implementation
    # ... your code here ...

    # Return structured result
    result = {
        "param1": param1,
        "param2": param2,
        "status": "success",
        "data": {
            # Your actual results
        }
    }

    return result


@click.command()
@click.option(
    "--param1",
    required=True,
    help="Description of param1"
)
@click.option(
    "--param2",
    type=int,
    default=100,
    help="Description of param2 (default: 100)"
)
@click.option(
    "--output",
    type=click.Path(),
    help="Optional output file path"
)
def cli(param1: str, param2: int, output: str | None):
    """Command description that appears in --help."""
    try:
        result = main_function(param1=param1, param2=param2)

        # Pretty-print JSON output
        output_json = json.dumps(result, indent=2)

        if output:
            # Write to file if specified
            Path(output).parent.mkdir(parents=True, exist_ok=True)
            Path(output).write_text(output_json)
            click.echo(json.dumps({"status": "written", "path": output}))
        else:
            # Print to stdout
            click.echo(output_json)

    except Exception as e:
        # Error output to stderr with exit code 1
        click.echo(json.dumps({"error": str(e)}), err=True)
        sys.exit(1)


if __name__ == "__main__":
    cli()

@click.option(
    "--driver",
    multiple=True,
    help="Driver abbreviation (can specify multiple)"
)
def cli(driver: tuple[str, ...]):
    drivers = list(driver)  # Convert tuple to list

@click.option(
    "--include-testing/--no-testing",
    default=True,
    help="Include testing sessions"
)
def cli(include_testing: bool):
    pass

@click.option(
    "--session",
    type=click.Choice(['FP1', 'FP2', 'FP3', 'Q', 'S', 'R']),
    required=True,
    help="Session type"
)
def cli(session: str):
    pass

@click.option(
    "--config",
    type=click.Path(exists=True, dir_okay=False),
    help="Path to config file"
)
def cli(config: str):
    pass

"""Tests for script_name script."""

import json
from unittest.mock import MagicMock, patch

import pytest
from click.testing import CliRunner

from pitlane_agent.scripts.script_name import cli, main_function


class TestMainFunctionBusinessLogic:
    """Unit tests for business logic functions.

    These tests directly call business functions without going through the CLI.
    Mock any external dependencies (APIs, file I/O, etc.).
    """

    def test_main_function_success(self):
        """Test successful execution with valid inputs."""
        result = main_function(param1="test", param2=100)

        assert result["param1"] == "test"
        assert result["param2"] == 100
        assert result["status"] == "success"
        assert "data" in result

    def test_main_function_validation_error_empty_param1(self):
        """Test that empty param1 raises ValueError."""
        with pytest.raises(ValueError, match="param1 cannot be empty"):
            main_function(param1="", param2=100)

    def test_main_function_validation_error_negative_param2(self):
        """Test that negative param2 raises ValueError."""
        with pytest.raises(ValueError, match="param2 must be non-negative"):
            main_function(param1="test", param2=-1)

    @patch("pitlane_agent.scripts.script_name.some_external_dependency")
    def test_main_function_with_mocked_dependency(self, mock_dependency):
        """Test with mocked external dependencies."""
        # Setup mock
        mock_dependency.return_value = {"data": "mocked"}

        result = main_function(param1="test", param2=100)

        # Verify mock was called correctly
        mock_dependency.assert_called_once()
        assert result["status"] == "success"


class TestCLI:
    """Integration tests for CLI interface using CliRunner.

    These tests invoke the CLI as a user would and verify the output.
    """

    def test_cli_help(self):
        """Test that --help displays usage information."""
        runner = CliRunner()
        result = runner.invoke(cli, ["--help"])

        assert result.exit_code == 0
        assert "--param1" in result.output
        assert "--param2" in result.output
        assert "Command description" in result.output

    def test_cli_success(self):
        """Test successful CLI execution."""
        runner = CliRunner()
        result = runner.invoke(cli, [
            "--param1", "test",
            "--param2", "200"
        ])

        assert result.exit_code == 0

        # Parse JSON output
        output = json.loads(result.output)
        assert output["param1"] == "test"
        assert output["param2"] == 200
        assert output["status"] == "success"

    def test_cli_with_defaults(self):
        """Test CLI with default values for optional params."""
        runner = CliRunner()
        result = runner.invoke(cli, [
            "--param1", "test"
            # param2 should use default value of 100
        ])

        assert result.exit_code == 0
        output = json.loads(result.output)
        assert output["param2"] == 100

    def test_cli_missing_required(self):
        """Test that missing required option shows error."""
        runner = CliRunner()
        result = runner.invoke(cli, [])

        assert result.exit_code != 0
        assert "param1" in result.output or "required" in result.output.lower()

    def test_cli_error_handling(self):
        """Test that errors are properly formatted as JSON to stderr."""
        runner = CliRunner()
        result = runner.invoke(cli, [
            "--param1", "",  # This should trigger validation error
            "--param2", "100"
        ])

        assert result.exit_code == 1

        # Error should be JSON formatted
        error_output = json.loads(result.output)
        assert "error" in error_output
        assert "cannot be empty" in error_output["error"]

    def test_cli_with_output_file(self, tmp_path):
        """Test writing output to a file."""
        runner = CliRunner()
        output_file = tmp_path / "output.json"

        result = runner.invoke(cli, [
            "--param1", "test",
            "--param2", "100",
            "--output", str(output_file)
        ])

        assert result.exit_code == 0
        assert output_file.exists()

        # Verify file contents
        saved_data = json.loads(output_file.read_text())
        assert saved_data["param1"] == "test"

    @patch("pitlane_agent.scripts.script_name.main_function")
    def test_cli_calls_business_logic(self, mock_main_function):
        """Test that CLI correctly calls business logic function."""
        mock_main_function.return_value = {"status": "mocked"}

        runner = CliRunner()
        result = runner.invoke(cli, [
            "--param1", "test",
            "--param2", "100"
        ])

        # Verify business function was called with correct args
        mock_main_function.assert_called_once_with(
            param1="test",
            param2=100
        )

# Run all tests for a script
uv run pytest packages/pitlane-agent/tests/scripts/test_script_name.py -v

# Run specific test class
uv run pytest packages/pitlane-agent/tests/scripts/test_script_name.py::TestCLI -v

# Run specific test method
uv run pytest packages/pitlane-agent/tests/scripts/test_script_name.py::TestCLI::test_cli_success -v

# Run with coverage
uv run pytest packages/pitlane-agent/tests/scripts/test_script_name.py --cov=pitlane_agent.scripts.script_name

# Test help output
python -m pitlane_agent.scripts.your_script_name --help

# Test with sample inputs
python -m pitlane_agent.scripts.your_script_name --param1 test --param2 100

# Verify JSON output format
python -m pitlane_agent.scripts.your_script_name --param1 test | jq .

# Run all tests
uv run pytest packages/pitlane-agent/tests/scripts/test_your_script_name.py -v

# Check coverage
uv run pytest packages/pitlane-agent/tests/scripts/test_your_script_name.py \
  --cov=pitlane_agent.scripts.your_script_name \
  --cov-report=term-missing

---
name: code-review-helper
description: Assist with code review tasks. Use when user asks for code reviews, style checks, or best practices.
allowed-tools: Read, Glob, Grep
---

# Code Review Helper

This skill helps perform thorough code reviews following best practices.

## When to Use This Skill

Use when users ask to:
- Review code changes
- Check coding standards
- Suggest improvements
- Identify bugs or issues

## Step 1: Understand Scope

Determine what needs to be reviewed:
- Specific files: Use Read tool
- Pattern-based: Use Glob to find files
- Search for patterns: Use Grep

## Step 2: Analyze Code

Review for:
- Code style and formatting
- Potential bugs
- Performance issues
- Security vulnerabilities
- Best practices

## Step 3: Provide Feedback

Structure feedback as:
1. Summary of findings
2. Critical issues (must fix)
3. Suggestions (should consider)
4. Positive observations

---
name: data-analysis
description: Comprehensive data analysis tools. Use when user needs data processing, visualization, or statistical analysis.
allowed-tools: Skill
---

# Data Analysis

This skill provides access to specialized data analysis subskills.

## Available Subskills

| Subskill | Description | Documentation |
|----------|-------------|---------------|
| data-cleaning | Clean and prepare datasets | [data-cleaning.md](./data-cleaning.md) |
| data-viz | Create visualizations | [data-viz.md](./data-viz.md) |
| statistics | Statistical analysis | [statistics.md](./statistics.md) |

## How to Use

- Data preparation tasks → data-cleaning
- Chart/graph requests → data-viz
- Statistical questions → statistics

# Data Cleaning

Instructions for cleaning and preparing datasets.

## When to Use

Use when data needs:
- Missing value handling
- Outlier detection
- Format standardization
- Deduplication

## Steps...

try:
    result = main_function(...)
    click.echo(json.dumps(result, indent=2))
except ValueError as e:
    click.echo(json.dumps({"error": f"Validation error: {str(e)}"}), err=True)
    sys.exit(1)
except Exception as e:
    click.echo(json.dumps({"error": f"Unexpected error: {str(e)}"}), err=True)
    sys.exit(1)