What is puzzle-fetcher?

The Puzzle Fetcher is a specialized Claude skill designed to automate the retrieval and processing of Advent of Code (AoC) challenges. By integrating with the aoc-cli tool, it seamlessly downloads puzzle descriptions and inputs, then applies advanced parsing logic to extract requirements, example test cases, and expected outputs. This skill transforms unstructured Markdown into machine-readable JSON, allowing developers to focus on problem-solving and Test-Driven Development (TDD) without the overhead of manual setup.

When should I use puzzle-fetcher?

puzzle-fetcher is useful in the following scenarios: • Automated Setup: Instantly fetch daily Advent of Code puzzles and inputs directly into your development environment. • TDD Integration: Extract example inputs and expected results from puzzle descriptions to automatically populate test suites. • Requirement Analysis: Parse complex Markdown descriptions to distinguish between Part 1 and Part 2 requirements and identify logic changes. • Data Structuring: Convert raw puzzle data into a standardized JSON format for consumption by other AI agents or automated solvers.

name	Puzzle Fetcher
description	Download and parse Advent of Code puzzles using aoc-cli. Extracts examples, expected outputs, and problem requirements from puzzle descriptions. Use when needing to fetch AoC puzzles, parse puzzle examples, or when user mentions downloading or reading AoC puzzle data.

Puzzle Fetcher

Purpose

This skill handles downloading puzzle descriptions and input files from adventofcode.com using the aoc-cli tool, then parsing them to extract examples, expected outputs, and problem requirements.

Primary Responsibilities

Download puzzle description (Markdown format)
Download puzzle input
Parse puzzle description to extract:
- Problem statement and requirements
- Example inputs
- Expected outputs for examples
- Part 1 vs Part 2 differentiations
Structure data for consumption by TDD solver

Using aoc-cli

Download Puzzle and Input

# Download for specific day
aoc download --day {day} --year 2025 \
  --puzzle-file puzzles/day{day:02}/puzzle.md \
  --input-file puzzles/day{day:02}/input.txt

# Example for Day 1:
aoc download --day 1 --year 2025 \
  --puzzle-file puzzles/day01/puzzle.md \
  --input-file puzzles/day01/input.txt

Handle Different Scenarios

# If puzzle not yet unlocked
# aoc-cli will return error: "Puzzle X of 2025 is still locked"

# If already downloaded and --overwrite not specified
# aoc-cli will skip download and inform file exists

# Force re-download
aoc download --day 1 --year 2025 --overwrite

Parsing Puzzle Description

The puzzle.md file is in Markdown format. Parse it to extract:

1. Problem Title

## --- Day 1: Calorie Counting ---

Extract: "Calorie Counting"

2. Example Inputs/Outputs

Look for patterns like:

For example:

1000 2000 3000

4000


This list represents...

Example extraction logic:

Find code blocks (triple backticks) that appear before explanatory text
These are usually example inputs
Look for phrases like "the answer is", "the total is", "should be" to find expected outputs
Common patterns:
- "the result is 42" → Extract 42
- "a total of 24000 calories" → Extract 24000
- "How many...? Your puzzle answer was 123" → Extract 123

3. Part 1 vs Part 2

Part 2 typically appears after:

## --- Part Two ---

Important:

Part 2 often modifies Part 1 requirements
May introduce new examples
May reuse Part 1 examples with different expected outputs

Output Format

Structure the parsed data as JSON for downstream consumption:

{
  "day": 1,
  "year": 2025,
  "title": "Calorie Counting",
  "part1": {
    "description": "Find the elf carrying the most calories...",
    "examples": [
      {
        "input": "1000\n2000\n3000\n\n4000\n\n5000\n6000\n\n7000\n8000\n9000\n\n10000",
        "expected_output": "24000",
        "explanation": "The fourth elf has the most calories"
      }
    ]
  },
  "part2": {
    "description": "Find the top three elves carrying the most calories...",
    "examples": [
      {
        "input": "1000\n2000\n3000\n\n4000\n\n5000\n6000\n\n7000\n8000\n9000\n\n10000",
        "expected_output": "45000",
        "explanation": "Top three totals: 24000 + 11000 + 10000"
      }
    ]
  },
  "input_file_path": "puzzles/day01/input.txt",
  "puzzle_file_path": "puzzles/day01/puzzle.md"
}

Save this to: puzzles/day{day:02}/parsed.json

Example Extraction Strategies

Strategy 1: Code Block Detection

For example:

```

The answer is 123


→ Input: content of code block
→ Output: 123

### Strategy 2: Inline Examples
```markdown
If the input is `abc`, the output would be `42`.

→ Input: "abc" → Output: 42

Strategy 3: Multi-Step Examples

Given this input:

line1 line2


First, do X which gives Y.
Then, do Z which results in **final answer 42**.

→ Input: "line1\nline2" → Output: 42

Edge Cases to Handle

Multiple Examples

Some puzzles provide multiple examples:

For example:

Example 1:
Input: `abc`
Output: `1`

Example 2:
Input: `def`
Output: `2`

Create separate example objects for each.

Examples Without Explicit Output

Some examples show the process but don't state the answer:

For example, given this input...
[process description]

In this case:

Flag that expected output needs manual extraction
Include process description in explanation field
May need to compute expected output from process

Part 2 Reusing Part 1 Examples

Part 2 often says "using the same example from Part 1":

Reference Part 1's example input
Extract Part 2's expected output
Link them together

Validation

Before returning parsed data, validate:

✅ Puzzle file exists and is readable ✅ Input file exists and is readable ✅ At least one example extracted for Part 1 ✅ Title extracted successfully ✅ Part 1 description exists ✅ If Part 2 section exists, Part 2 data extracted

Error Handling

Puzzle Not Available Yet

Error: Puzzle 5 of 2025 is still locked
Action: Return error status, orchestrator will handle retry

Network Failure

Error: Failed to connect to adventofcode.com
Action: Retry up to 3 times with exponential backoff

Parsing Failure

Error: Could not extract examples from puzzle description
Action: Save raw puzzle.md, flag for manual review
Log: Warning about parsing failure
Still proceed with solution attempt using manual test creation

File Organization

After fetching:

puzzles/
  day01/
    puzzle.md        # Raw puzzle description from aoc-cli
    input.txt        # Real puzzle input
    parsed.json      # Structured parsed data
  day02/
    ...

Testing This Skill

Create test cases with:

Mock puzzle.md files with various formats
Verify correct extraction of examples
Test edge cases (no examples, multiple examples, etc.)
Validate JSON output structure

Integration Points

Called By

aoc-orchestrator skill (main workflow)

Calls

aoc-cli command-line tool via Bash

Outputs Used By

tdd-solver skill (consumes parsed.json)

Performance Considerations

Cache puzzle descriptions once downloaded
Don't re-download if file exists (unless forced)
Parsing should complete in < 1 second
Network download typically < 5 seconds

Command Interface

When invoked directly:

# Fetch today's puzzle
./scripts/fetch-puzzle.sh

# Fetch specific day
./scripts/fetch-puzzle.sh 5

# Force re-download
./scripts/fetch-puzzle.sh 1 --force

# Dry run (download but don't parse)
./scripts/fetch-puzzle.sh 1 --dry-run

puzzle-fetcher

When & Why to Use This Skill

Use Cases