Scrape Skill

Thin wrapper that routes PDF annotation extraction to the scrape-agent, which extracts highlights, comments, notes, and other annotations from PDF files.

Context Pointers

Reference (do not load eagerly):

• Path: .claude/context/formats/subagent-return.md
• Purpose: Return validation
• Load at: Subagent execution only

Note: This skill is a thin wrapper. Context is loaded by the delegated agent, not this skill.

Trigger Conditions

This skill activates when:

Direct Invocation

• User explicitly runs /scrape command
• User requests annotation extraction in conversation

Implicit Invocation (during task implementation)

When an implementing agent encounters any of these patterns:

Plan step language patterns:

• "Extract annotations from [file].pdf"
• "Extract highlights from [file].pdf"
• "Extract comments from [file]"
• "Scrape notes from [file].pdf"
• "Collect annotations in [file]"
• "Export PDF comments to markdown"
• "Gather highlights and notes from [file]"

File extension detection:

• Source file has extension: .pdf
• Target mentions: "annotations", "highlights", "comments", "notes"

Task description keywords:

• "annotation extraction"
• "PDF scraping"
• "extract highlights"
• "collect comments"
• "gather notes from PDF"

When NOT to Trigger

Do not invoke for:

• Non-PDF files (.docx, .html, .txt, etc.)
• General document conversion (use skill-filetypes)
• Reading PDF text content without annotation context (use skill-filetypes)
• Operations on spreadsheets or presentations (use skill-spreadsheet, skill-presentation)

Execution

1. Input Validation

Validate required inputs:

• pdf_path - Must be provided, must exist, must be a .pdf file
• output_path - Optional, defaults to {basename}_annotations.md in same directory
• annotation_types - Optional array, defaults to all types
• output_format - Optional, defaults to "markdown"

# Validate source exists
if [ ! -f "$pdf_path" ]; then
  return error "PDF file not found: $pdf_path"
fi

# Validate source is a PDF
if [[ "${pdf_path##*.}" != "pdf" ]]; then
  return error "Source must be a .pdf file: $pdf_path"
fi

# Determine output path if not provided
if [ -z "$output_path" ]; then
  source_dir=$(dirname "$pdf_path")
  source_base=$(basename "$pdf_path" .pdf)
  output_path="${source_dir}/${source_base}_annotations.md"
fi

2. Context Preparation

Prepare delegation context:

{
  "pdf_path": "/absolute/path/to/document.pdf",
  "output_path": "/absolute/path/to/document_annotations.md",
  "annotation_types": ["highlights", "comments", "notes", "bookmarks"],
  "output_format": "markdown",
  "metadata": {
    "session_id": "sess_{timestamp}_{random}",
    "delegation_depth": 1,
    "delegation_path": ["orchestrator", "scrape", "skill-scrape"]
  }
}

3. Invoke Agent

CRITICAL: You MUST use the Agent tool to spawn the scrape agent.

Required Tool Invocation:

Tool: Agent (NOT Skill, NOT Plan)
Parameters:
  - subagent_type: "scrape-agent"
  - prompt: [Include pdf_path, output_path, annotation_types, output_format, metadata]
  - description: "Extract annotations from {pdf_path} to {output_path}"

DO NOT use Skill(scrape-agent) - this will FAIL. Agents live in .claude/agents/ or extension agent directories, not .claude/skills/. The Skill tool can only invoke skills from .claude/skills/.

The agent will:

• Open the PDF and enumerate all annotation objects
• Filter by requested annotation types
• Format annotations according to output_format
• Write structured output to output_path
• Return standardized JSON result

4. Return Validation

Validate return matches subagent-return.md schema:

• Status is one of: scraped, partial, failed
• Summary is non-empty and <100 tokens
• Artifacts array present with output file path
• Metadata contains session_id, agent_type, delegation info

5. Return Propagation

Return validated result to caller without modification.

Return Format

See .claude/context/formats/subagent-return.md for full specification.

Expected successful return:

{
  "status": "scraped",
  "summary": "Extracted 42 annotations from document.pdf: 28 highlights, 10 comments, 4 notes",
  "artifacts": [
    {
      "type": "implementation",
      "path": "/absolute/path/to/document_annotations.md",
      "summary": "Extracted annotations in markdown format"
    }
  ],
  "metadata": {
    "session_id": "sess_...",
    "agent_type": "scrape-agent",
    "delegation_depth": 2,
    "delegation_path": ["orchestrator", "scrape", "skill-scrape", "scrape-agent"],
    "annotation_count": 42,
    "annotation_breakdown": {
      "highlights": 28,
      "comments": 10,
      "notes": 4
    }
  },
  "next_steps": "Review extracted annotations"
}

Error Handling

Input Validation Errors

Return immediately with failed status if PDF not found or not a .pdf file.

Unsupported Format

Return failed status with clear message about supported annotation types.

Agent Errors

Pass through the agent's error return verbatim.

Tool Not Available

Return failed status with installation instructions for PDF annotation tools (e.g., pdfannots, PyMuPDF).

MUST NOT

• Run the postflight step (git commit, status update) — that is the command's responsibility
• Modify the return from scrape-agent before propagating
• Load context files eagerly — only reference them when needed
• Use the Skill tool to invoke scrape-agent (use Agent tool instead)