Using Skills¶

Skills extend the F1 agent with specialized analysis capabilities. Each skill is automatically invoked based on your question.

How Skills Work¶

When you ask a question, the agent:

1. Analyzes Intent - Determines which skill is relevant
2. Invokes Skill - Passes your question to the skill
3. Skill Executes - Runs Python scripts via pitlane CLI
4. Returns Result - Provides analysis and visualizations

User Query
    ↓
Agent Reasoning
    ↓
Skill Invocation (f1-analyst, f1-drivers, or f1-schedule)
    ↓
CLI Execution (pitlane fetch/analyze commands)
    ↓
Data Processing & Visualization
    ↓
Response with Charts & Analysis

Available Skills¶

f1-analyst¶

Purpose: Data analysis and visualization using FastF1

Triggers: - Lap time questions: "Compare VER and HAM lap times" - Strategy questions: "Show me Ferrari's tyre strategy" - Telemetry questions: "Compare speed traces" - Performance questions: "Who was fastest in Q3?"

Capabilities: - Lap time distributions - Tyre strategy timelines - Telemetry comparisons - Statistical analysis

Example:

User: Compare Verstappen and Hamilton lap times in Monaco qualifying

Agent: [Invokes f1-analyst skill]

Skill Actions:
1. Fetch session info: pitlane fetch session-info --year 2024 --gp Monaco --session Q
2. Analyze lap times: pitlane analyze lap-times --drivers VER --drivers HAM
3. Generate chart: workspace/charts/lap_times.png
4. Return analysis with statistics

Result: "Verstappen was 0.234s faster on average (1:12.345 vs 1:12.579)"
       [lap_times.png displayed]

f1-drivers¶

Purpose: Driver information via Ergast API

Triggers: - Driver roster questions: "Who drove for Ferrari in 2019?" - Driver code questions: "What's Leclerc's driver code?" - Team lineup questions: "Show me Mercedes drivers"

Capabilities: - Season driver rosters - Driver codes and names - Team affiliations - Nationality and Wikipedia links

Example:

User: Who drove for Ferrari in 2024?

Agent: [Invokes f1-drivers skill]

Skill Actions:
1. Fetch drivers: pitlane fetch drivers --year 2024 --team Ferrari
2. Parse results
3. Format response

Result: "Ferrari's 2024 drivers: Charles Leclerc (LEC) and Carlos Sainz (SAI)"

f1-schedule¶

Purpose: Event calendar and session schedules

Triggers: - Calendar questions: "When is the next race?" - Schedule questions: "Show me the 2024 calendar" - Session timing questions: "What time is qualifying?"

Capabilities: - Season calendars - Race dates and locations - Session schedules - Sprint weekend identification

Example:

User: When is the Monaco Grand Prix?

Agent: [Invokes f1-schedule skill]

Skill Actions:
1. Fetch schedule: pitlane fetch schedule --year 2024
2. Find Monaco event
3. Extract dates and times

Result: "Monaco Grand Prix is on May 26, 2024 (Round 8)"

Skill Selection¶

The agent automatically selects the appropriate skill based on query keywords:

Sub-Skills¶

Complex skills like f1-analyst use sub-skills for organization:

f1-analyst/
├── SKILL.md (main routing)
└── references/
    ├── lap_times.md        # Lap time analysis
    ├── strategy.md         # Tyre strategy
    ├── telemetry.md        # Telemetry comparison
    └── standings.md        # Championship standings

The main skill reads the appropriate reference based on query type.

Workspace Integration¶

Skills use the session workspace for data persistence:

~/.pitlane/workspaces/<session-id>/
├── data/
│   ├── session_info.json   # Fetched by skills
│   ├── drivers.json
│   └── schedule.json
└── charts/
    ├── lap_times.png       # Generated by skills
    └── strategy.png

Benefits: - Session isolation (no data mixing) - Persistent data for debugging - Charts accessible via web interface

Tool Permissions¶

Skills have restricted tool access for security:

See Architecture: Tool Permissions for details.

Example Conversations¶

Lap Time Analysis¶

User: Compare Verstappen, Hamilton, and Leclerc lap times in Monaco 2024 qualifying

Agent: I'll analyze the qualifying lap times for those three drivers.

[Invokes f1-analyst skill → lap_times.md]

pitlane fetch session-info --workspace-id abc123 --year 2024 --gp Monaco --session Q
pitlane analyze lap-times --workspace-id abc123 --year 2024 --gp Monaco --session Q \
  --drivers VER --drivers HAM --drivers LEC

[Generates lap_times.png]

Here's the comparison:

1. Max Verstappen (VER): 1:12.123 (mean: 1:12.345)
2. Charles Leclerc (LEC): 1:12.234 (mean: 1:12.456)
3. Lewis Hamilton (HAM): 1:12.345 (mean: 1:12.567)

Verstappen was fastest, with Leclerc 0.111s behind and Hamilton 0.222s behind.

[Chart displayed showing lap time distributions]

Strategy Analysis¶

User: What tyre strategy did Red Bull use in Silverstone 2024?

Agent: I'll check Red Bull's tyre strategy for the Silverstone race.

[Invokes f1-analyst skill → strategy.md]

pitlane fetch session-info --workspace-id abc123 --year 2024 --gp Silverstone --session R
pitlane analyze tyre-strategy --workspace-id abc123 --year 2024 --gp Silverstone --session R

[Generates strategy.png]

Red Bull's strategy:
- Verstappen (VER): MEDIUM (Laps 1-20) → HARD (Laps 21-52)
- Perez (PER): SOFT (Laps 1-15) → MEDIUM (Laps 16-52)

Verstappen used a one-stop strategy with a later pit stop, while Perez started on softs
and made an earlier pit stop to mediums.

[Chart displayed showing strategy timeline]

Driver Information¶

User: Who drove for McLaren in 2023?

Agent: I'll look up McLaren's driver lineup for the 2023 season.

[Invokes f1-drivers skill]

pitlane fetch drivers --workspace-id abc123 --year 2023 --team McLaren

McLaren's 2023 drivers:
- Lando Norris (NOR) - British
- Oscar Piastri (PIA) - Australian

Best Practices¶

Be Specific¶

Good: "Compare Verstappen and Hamilton lap times in Monaco 2024 qualifying" Bad: "Show me lap times" (missing: who, where, when, which session)

Use Official Names¶

Good: "Monaco Grand Prix", "Silverstone", "British Grand Prix" Bad: "Monaco race", "UK GP" (may not match FastF1 event names)

Check Season Year¶

Good: "2024 calendar" Bad: "current season" (agent needs explicit year)

Note: The agent has temporal context, so "last race" and "next race" work.

Troubleshooting¶

Skill Not Triggered¶

Symptom: Agent doesn't invoke a skill

Causes: - Query too vague - Missing required information (year, GP, session) - Ambiguous intent

Solution: Be more specific about what you want

Data Not Found¶

Symptom: Error: "Session not found" or "No data available"

Causes: - Incorrect GP name (use official name from FastF1) - Session not yet available (too recent) - Typo in driver code

Solution: - Check GP name: pitlane fetch schedule --year 2024 - Wait 1+ hour after session for data availability - Use 3-letter driver codes: VER, HAM, LEC, etc.

Chart Not Generated¶

Symptom: No visualization in response

Causes: - Analysis failed (check workspace/data for errors) - Insufficient data (e.g., only 1 lap) - Tool permission denied

Solution: - Check workspace: pitlane workspace info --workspace-id <id> - Enable tracing: PITLANE_TRACING_ENABLED=1

Related Documentation¶

• Analysis Types - Available analysis workflows
• CLI Reference - Underlying CLI commands
• Architecture: Skills - Skill system internals
• Developer Guide: Adding Skills - Creating custom skills