describe-collection

The operator entry point for a first-pass run. It owns pipeline stage 1 (intake and inventory) and drives stage 4 (generation) by dispatching the field-generator agent against the generation prompt. It walks a collection, captures what already describes each work and where it sits in the collection tree, runs generation per work, and writes one metadata record per work plus a run manifest.

It is the stage that produces the first-pass records the rest of the loop reviews and improves. It stops at first-pass output: every controlled value leaves this skill with authority_status of needs_verification, and the deterministic resolve-authorities stage (stage 5) confirms candidates against the real authorities later. This skill does not resolve authorities, does not review, and does not export.

Where it sits in the pipeline

For a simple image collection with no derivatives or transcription needed, this skill can follow intake directly. When works carry text or audiovisual material, run preprocess-derivatives and classify-and-route first so generation receives OCR text, transcripts, and the right schema and prompt set. This skill consumes those upstream outputs; it does not reproduce them.

The LLM is one stage of seven. Stage 4 here is the only generative step; intake (stage 1) is deterministic capture, and authority resolution (stage 5) is deterministic lookup downstream. Keeping generation boxed into one inspectable stage is what makes the output auditable. See ../../docs/architecture.md.

Sample-before-scale: the hard checkpoint

Default behavior: process at most a small sample, then stop and hand the operator a summary so they can sanity-check before any larger run. This checkpoint enforces the improvement loop's discipline. A generic prompt rarely clears an institution's per-record threshold on the first pass, and the loop exists to raise it on a sample before the volume run earns sampled review. Do not process a large batch before a sample has cleared review. See ../../docs/the-improvement-loop.md and the operating spine in ../../CLAUDE.md.

When a manifest or directory holds more than the sample size, generate the sample, write its records and the run manifest, present the summary table, and ask the operator before continuing.

Inputs

Composed from this shared repo plus the adjacent institution workspace, with local material winning (see ../../docs/adjacent-workspace.md).

From the adjacent workspace (named workspace locations, reachable at ../<institution>-metadata/ from the clone, not repo-relative paths):

• works/: the digital objects to describe, or a manifest enumerating them. For text-bearing or audiovisual works this includes the derivatives produced by preprocess-derivatives (OCR text, Whisper transcripts, technical metadata).
• application-profile.json: what to generate and how. This skill reads target_schema, controlled_vocabularies, description_style, required_fields, collection_hierarchy, and model. Its shape is fixed by ../../schemas/application-profile.schema.json.
• context/: collection scope, house style, exemplar finished records for few-shot calibration, and donor or provenance notes. The profile's description_style.examples_path points in here.
• overrides/: any local prompt, skill, or agent customization that shadows the shared asset at the same relative path.

From this repo (relative to skills/describe-collection/):

• The generation prompt: ../../prompts/system/metadata-generation.v1.md. Its {{...}} placeholders are filled from application-profile.json.
• The record contract: ../../schemas/metadata-record.schema.json.
• The run-manifest contract: ../../schemas/run-manifest.schema.json.
• The generation agent: field-generator (in ../../agents/).

What it does

Stage 1: intake and inventory

For each work, capture the collection context as fact, before generation, so the hierarchy enters the record from the institution's arrangement rather than from model inference. Write it into the record's collection_context object (the schema-backed home; there is no separate inventory schema):

• The position in the hierarchy: repository, collection, series, subseries, is_part_of (the identifier or title of the immediate parent), and accession, drawn from the directory structure, a DAMS export, a spreadsheet, or the profile's collection_hierarchy.
• source_metadata: every scrap of pre-existing description that travels with the work, captured by key as free-form evidence: filename, folder path, accession note, donor note, partial legacy record.

This captured context is the evidence stage 4 uses and the cataloguer checks later. Capturing it at intake is what keeps the model from manufacturing a hierarchy. See ../../docs/collection-context.md.

Stage 4: generation

For each work, dispatch the field-generator agent to run the generation prompt with the work, its derivatives, its collection_context, and the profile-derived configuration. The agent returns a first-pass record conforming to ../../schemas/metadata-record.schema.json, under the eight hard rules in ../../CLAUDE.md. This skill orchestrates and stamps the run; it does not reimplement generation logic, which lives in the prompt and the agent.

Per-value handling this skill is responsible for:

• value_id on every value, assigned at generation and stable across re-runs. Scalar fields use the field name (title, description, creator, date, type, spatial, medium_technique, language). Array-field values use the field name plus a stable suffix: subjects.01, genre_form.01, depicted_entities.01. Review verdicts reference value_id, never an array position, so a verdict stays attached to the same value when array order changes between rounds. Do not emit positional keys.
• Authority candidates stay at needs_verification. The agent proposes a best-candidate label and sets authority_status; this skill leaves authority_uri null and resolves nothing. The LLM proposes, the deterministic stage 5 disposes, the human confirms.
• Provenance stamped on every record: generated_by (the resolved generation model id), model_role generation, prompt_version (for example system/metadata-generation@1.0.0), skill describe-collection@1.0.0, agent field-generator, generated_date, run_id (linking to the run manifest), local_only where the collection requires a local model, and human_reviewed false.
• disclosure_note carried through with the model, prompt version, and date, its reviewer portion left for human approval downstream.

Model is a parameter

Read the generation model from application-profile.json (model.generation); do not hardcode a model id. Generation runs on the cost-effective model that does the volume, while a frontier model orchestrates the loop elsewhere. For collections the profile lists under model.local_only_collections, run a local model so nothing leaves the institution, and set local_only true in provenance and in the run manifest. See ../../docs/models-and-cost.md.

Outputs

Written to the adjacent workspace runs/ (these are run artifacts; export-ready records are written to output/ later by export-for-repository after review):

1. One metadata record per work, conforming to ../../schemas/metadata-record.schema.json, with collection_context populated from intake, every value carrying value_id, confidence, and basis, controlled values carrying an authority_candidate at needs_verification, and provenance and disclosure_note stamped.
2. One run manifest, conforming to ../../schemas/run-manifest.schema.json. Write the start fields now: run_id, started_at, dataset (sample_id, item_count, item_ids, source, and held_out when this is a held-out confirmation run), models (generation, local_only), prompt_versions, and skill_versions. Leave outcome empty; compute-pass-rate fills it after review.
3. An operator summary table for the sanity check: one row per work with item id, title, overall confidence, and the count of low-confidence fields, so the operator can read the sample at a glance before approving a larger run.

The records feed resolve-authorities (stage 5) and then review-triage (stage 6). The cataloguer's verdicts come back as review-feedback (../../schemas/review-feedback.schema.json), keyed by value_id, and compute-pass-rate reads them against the run manifest.

Usage example

This is sample-user-prompt #1 from the initiative's operator curriculum, localized to repo conventions. Paths name the adjacent workspace; the system prompt and config are the repo's canonical locations.

Read the collection at ../acme-metadata/works/civil-war-telegrams/. For each work, capture its
collection context (series, parent, filename, any accession or donor notes) into collection_context,
then run the generation stage with the field-generator agent using
prompts/system/metadata-generation.v1.md and the institution config in
../acme-metadata/application-profile.json. Write one record per work to ../acme-metadata/runs/, write
the run manifest, then give me a summary table: item, title, overall confidence, and number of
low-confidence fields. Stop and ask me before processing more than 25 works so I can sanity-check the
first batch.

What the operator practices here is batch orchestration over a manifest, structured JSON output, and the sample-before-scale checkpoint. The 25-work stop is the loop's gate: it keeps a large run from happening before a sample has cleared review.

Boundaries

• Do not resolve authorities or invent URIs. Candidates leave at needs_verification for stage 5.
• Do not review or accept records. Generation sets human_reviewed false; review is stage 6.
• Do not export. Records land in runs/; export to the repository format is stage 7.
• Do not strip collection context. It is captured at intake and preserved on every record.
• Do not name unidentified people, and route sensitive, culturally restricted, or reparative-description cases to review_flags rather than resolving them. See ../../docs/responsible-description.md.
• Do not process a large batch before a sample has cleared review.