feedback-ls - SKILL.md Agent Skill

name: feedback-ls description: > Guide for sending document pages to Label Studio for human feedback on transcriptions. Use when: feedback, label studio, annotation, review transcription, quality check, send to label studio, import to label studio, human review, correct transcription, segmentation feedback, transcription feedback, ALTO to label studio, review pages, flag pages for review, quality assurance, QA, annotation task, annotate images, label images, send images for annotation.

Label Studio Feedback Workflow

Send document pages to Label Studio for human annotation and feedback.

Tool

label_import_to_label_studio — Import pages to a Label Studio project. Two modes:
- With ALTO: pre-annotated tasks with polygons and transcriptions
- Images only: blank tasks for annotation from scratch

When to Use

User asks to send pages for human review or annotation
User wants to flag transcription or segmentation issues
User wants to create Label Studio tasks from browse results
User wants to send images for annotation from scratch
User asks for quality assurance on specific pages

Two Modes

Mode 1: Pre-annotated (with ALTO XML)

Use when pages already have AI transcriptions. The tool fetches ALTO XML, extracts text line polygons and transcriptions, and creates VectorLabels pre-annotations.

{
  "image_urls": [
    "https://lbiiif.riksarkivet.se/arkis!30002056_00004/full/max/0/default.jpg"
  ],
  "alto_urls": [
    "https://sok.riksarkivet.se/dokument/alto/SE_RA_30002056_00004"
  ],
  "feedback": [["Transcription"]]
}

Mode 2: Images only (no ALTO)

Use when there are no existing transcriptions — the user wants to annotate from scratch. Just pass image URLs, omit alto_urls.

{
  "image_urls": [
    "https://lbiiif.riksarkivet.se/arkis!30002056_00004/full/max/0/default.jpg",
    "https://lbiiif.riksarkivet.se/arkis!30002056_00005/full/max/0/default.jpg"
  ]
}

Choosing the Right Source for Pre-annotations

When the user wants to send pages with pre-annotations, choose the source based on what's available:

Situation	Source	How
Pages from `browse_document` results	ALTO XML from Riksarkivet	Pass `alto_urls` from browse output
User has images without transcriptions	No pre-annotations	Omit `alto_urls` (image-only mode)
User has images and wants AI transcription first	HTR transcription	Use `htr_transcribe` first to generate ALTO XML, then pass the ALTO export URLs as `alto_urls`
User wants to label/annotate themselves	No pre-annotations	Omit `alto_urls` — blank tasks for manual annotation

Tip: If the user has untranscribed images and wants pre-annotations, suggest running htr_transcribe (see /htr-transcription skill) first to generate ALTO XML, then feed those results into this tool.

Workflow

1. Get page URLs

From browse results: Call browse_browse_document first (or use results already in the conversation). Each page includes:

ALTO XML URL: https://sok.riksarkivet.se/dokument/alto/...
Image URL: https://lbiiif.riksarkivet.se/arkis!.../full/max/0/default.jpg

From any image source: Any publicly accessible image URL works for image-only mode.

2. Determine feedback choices (optional, ALTO mode only)

Value	Meaning
`Transcription`	Text recognition needs correction
`Segmentation`	Line/region boundaries need correction

Each page gets its own list of feedback values. Use an empty list [] for pages that need general review without a specific feedback flag.

3. Optionally assign to a user

Pass assign_to with a Label Studio user's email to auto-assign the imported tasks for annotation. If omitted, tasks are created unassigned.

{
  "image_urls": ["..."],
  "alto_urls": ["..."],
  "assign_to": "reviewer@example.com"
}

4. Call the tool

Label Studio URL, token, and project ID are configured via environment variables (LS_URL, LS_TOKEN, LS_PROJECT_ID) — no need to pass them unless overriding.

5. Confirm to the user

The tool returns:

Number of tasks imported and the mode (pre-annotated or image-only)
Who the tasks were assigned to (if assign_to was provided)
Direct links to each task in Label Studio for labeling

Share the task links with the user so they can go directly to Label Studio.

Dry Run — Preview Before Import

Set dry_run=true to see the converted Label Studio JSON without importing.

{
  "image_urls": ["..."],
  "alto_urls": ["..."],
  "dry_run": true
}

Pairing Rules

When using alto_urls, all lists are paired by index — alto_urls[i], image_urls[i], and feedback[i] refer to the same page.

Rule	Detail
`image_urls` is always required	One image URL per page
`alto_urls` is optional	Omit for image-only tasks
`alto_urls` and `image_urls` must match length	One ALTO XML per image
`feedback` must match length if provided	One feedback list per page
`feedback` requires `alto_urls`	Feedback choices attach to ALTO text regions

Extracting URLs from Browse Results

The browse_browse_document tool returns per-page links in this format:

🔗 Links:
  📝 ALTO XML: https://sok.riksarkivet.se/dokument/alto/SE_RA_30002056_00004
  🖼️  Image: https://lbiiif.riksarkivet.se/arkis!30002056_00004/full/max/0/default.jpg

Collect the Image URLs (always needed) and ALTO XML URLs (only if you want pre-annotations).

Batch Strategy

Small sets (1-10 pages): Send all pages in a single call.
Larger sets: Batch into groups of 10-20 pages per call to avoid timeouts. The tool has a 120-second timeout.

Common Mistakes

Mistake	Fix
Mismatched list lengths	`alto_urls` and `image_urls` must be the same length
Passing feedback without alto_urls	Feedback requires ALTO (choices attach to text regions)
Passing feedback as flat list	Each entry must be a list of strings, e.g. `[["Transcription"], []]` not `["Transcription", ""]`
Wrong ALTO URL format	Use the full URL from browse results, not just the page ID
Passing Label Studio credentials	Credentials are loaded from env vars — only pass if overriding

Environment Variables

Variable	Description
`LS_URL`	Label Studio instance URL
`LS_TOKEN`	Label Studio Personal Access Token (JWT PAT)
`LS_PROJECT_ID`	Target project ID

These are configured in packages/label-mcp/.env and loaded automatically.