Build the application profile

This skill produces application-profile.json, the one file that configures every other stage. It declares what the institution wants generated and how: the target schema, the controlled vocabularies in priority order, the house description style, the fields that must be right for a record to pass, the review threshold the loop optimizes toward, and the model to use for each role.

The output conforms to ../../schemas/application-profile.schema.json, and the doc that describes the artifact in full is ../../docs/application-profiles.md. Read both before drafting.

Where this runs in the pipeline

Building the profile is setup. It is not one of the seven numbered stages; it runs before them and configures all of them. From it, the generation prompt's visible {{...}} placeholders are filled (stage 4), the authority-resolution stage gets its vocabulary endpoints (stage 5), and the review and loop stages get the required-field gate, the threshold, and the model choices they run on.

In the operating sequence it is Step 1 (Seed) of the improvement loop (../../docs/the-improvement-loop.md), where the orchestrator drafts the profile from the works plus the institution's context, and Phase 1 (Scoping and standards mapping) of the pilot engagement. Run it once at the start; the institution owns and edits the profile thereafter.

Inputs and outputs, by schema

Inputs (two evidence streams plus the interview, all reconciled into one artifact):

• A representative sample of the institution's works in the adjacent workspace (works/): the actual digital objects, their filenames, folder structure, and any source metadata at intake.
• The institution's existing finished records, the human-cataloged output that defines house style and reveals which fields the institution genuinely ships. These also seed the exemplar set the generation prompt uses for few-shot calibration (context/exemplar-records/).
• The institution interview, which confirms the inspection's proposed defaults and supplies the decisions only the institution can make: schema, vocabularies, model and data-governance, house style, and review policy.

Output:

• One application-profile.json in the institution's adjacent workspace, conforming to ../../schemas/application-profile.schema.json. It lives in the adjacent workspace and is never committed to this shared repo. It fills the visible {{...}} placeholders in ../../prompts/system/metadata-generation.v1.md and feeds the loop and review stages the values they run on.

Usage example

The distinctive interactive piece is calibrating house style from the institution's own records, which is sample-user-prompt #2 in the initiative's operator curriculum, reconciled here to the repo's canonical artifact names:

Here are five of our existing finished records (in ./context/exemplar-records/). Our cataloguers
write shorter, more neutral descriptions than the default, one or two sentences, present tense, no
interpretation of mood or intent. Set description_style in application-profile.json to match these
examples, point examples_path at that folder, then re-run item tel_0001 and show me the description
before and after so I can see the house voice take hold.

The same interview-and-inspect pattern produces the rest of the profile: read the works to propose a target schema and vocabularies, then confirm them with the cataloguer and capture the model and review-policy decisions.

Procedure

1. Inspect the works sample

Read a representative slice of works/. Note the dominant content type (still image, document, audio, video, map, mixed), the source metadata present at intake (filenames, folder paths, accession notes, partial legacy records), and the collection hierarchy the folder structure implies. The content type proposes the target schema: Dublin Core as the baseline, with VRA Core elements for visual works and PBCore elements for audiovisual. The hierarchy proposes the optional collection_hierarchy block, which the generation stage receives as evidence so works are described in their collection context rather than atomized; see ../../docs/collection-context.md.

2. Inspect the finished records

Read the institution's existing human-cataloged records. They answer two questions the works cannot. First, house style: the length, register, and tense the institution actually uses, and what it declines to assert (intent, mood, attribution without evidence). Second, which fields the institution genuinely ships on every record, which proposes required_fields. Copy a handful of the strongest records into context/exemplar-records/ as the few-shot set, and point description_style.examples_path there.

3. Interview the institution

Inspection proposes; the interview disposes. Confirm the proposed defaults with the cataloguer or metadata reviewer who holds decision authority, and capture the calls only they can make:

• Target schema. Confirm the schema the inspection proposed and any element sets layered on it.
• Controlled vocabularies, in priority order. Which authorities apply to which fields, and in what preference order. Capture community and local vocabularies here too, not only the national authorities: Homosaurus for LGBTQ+ subjects, a local format scheme for departmental record types, and so on. Record the scope_note that says when to prefer one over another.
• House style. Confirm the guidance distilled from the finished records, and any length cap.
• Required fields. Press for an honest, minimal list (see the gate note below).
• Review policy. The single number the institution sets as its per_record_pass_rate, and the policy behind it (for example, that below the line it reviews the whole dataset by hand).
• Model and data governance. The generation model, the orchestration model for the loop, and critically, any collection that must never leave the institution's infrastructure. Surface sensitive, donor-restricted, or rights-restricted material early; it drives local_only_collections.

4. Draft the profile and validate

Assemble the answers into application-profile.json in the adjacent workspace. Validate it against ../../schemas/application-profile.schema.json before handing it on; the schema is closed, so cover behavior it does not have through the local overrides/ directory referenced by overrides_path rather than by inventing profile keys. A complete worked profile is in ../../docs/application-profiles.md.

The fields, and what to get right

target_schema

Names the descriptive standard, for example Dublin Core, Dublin Core + VRA Core for visual works, or PBCore for audiovisual. It fills {{TARGET_SCHEMA}} and is written into every record. The export stage adapts the final write to the institution's platform regardless of the schema, so choose the schema that fits the material rather than the destination repository.

controlled_vocabularies

An array, and array order is the priority order: the generator proposes terms preferring earlier vocabularies. Each entry binds a vocabulary to the fields it governs through applies_to, so a subject vocabulary is not reached for on a material field. Include the endpoint, which has a second consumer: the deterministic authority-resolution stage uses it to turn needs_verification candidates into confirmed URIs. The documented default order is LCSH and FAST for subjects, Getty AAT for genre_form and medium_technique, Getty TGN for spatial, LCNAF and VIAF for creator and depicted_entities, LCGFT for genre and form, and Homosaurus where relevant. Endpoints for the national and community authorities are in the initiative's metadata-standards reference; if you are unsure of an exact endpoint, set it to null and flag it for verification rather than inventing one. Community and local vocabularies belong here alongside the national authorities, which is part of how the toolkit answers the cultural-bias risk; see ../../docs/responsible-description.md.

description_style

The optional house-style block, tuned to local practice. guidance fills {{DESCRIPTION_STYLE}}; the documented default is factual, concise, present tense, describing what is visibly present without interpreting intent. examples_path fills {{HOUSE_STYLE_EXAMPLES}} and points at the exemplar finished records for few-shot calibration. The optional max_length_words caps description length. Pointing examples_path at the institution's own approved records is the most direct way to make generated descriptions read in the house voice.

required_fields

The fields that must be accepted with no edit for a record to pass the per-record gate. Keep this list honest and minimal, because the cost of each required field is multiplicative. If a record has ten required fields and each is independently correct 95 percent of the time, the whole record needs no edit only about 60 percent of the time (0.95 to the tenth power); clearing a 90 percent per-record bar across ten fields demands each field be right about 99 percent of the time. Adding a required field multiplies one more probability below 1 into that product, so it is never free. Make a field required because the institution genuinely will not ship a record without it. A required array field (subjects, genre_form, depicted_entities) is held to the harder standard: it passes only when every generated value is accepted and the cataloguer added no missing value. The math and the gate definitions are worked out in ../../docs/the-improvement-loop.md.

review_threshold

per_record_pass_rate is the single number the institution sets: the share of generated records that need no human modification. Oregon State's roughly 90 percent (0.90) is one example rather than a default to hardcode; elicit the institution's own number and record the policy behind it in rationale. This is the institution's own review-policy gate and the loop's optimization target. It is not a contractual accuracy guarantee from Notch8; the pilot promises the method and the transparency.

model

Selects which model plays each role, because model is a parameter. generation is the cost-effective model that does the volume and fills {{MODEL_ID}}. orchestration is the frontier model the loop uses to refine prompts on the small sample. local_only_collections lists collections that must use a local model with nothing sent to an external API, which sets provenance.local_only to true as the auditable proof that no content left the institution's infrastructure. This is the path for sensitive and rights-restricted material; see ../../docs/models-and-cost.md.

After this skill

With the profile in place, run a first-pass batch on a bounded sample with describe-collection, and stop to sanity-check the first 25 records before processing more. The profile is the institution's to edit from here: a change that would help an institution describing entirely different works can contribute upstream, while a change that encodes this collection's scope, house style, local vocabulary, or donor context stays in the adjacent overrides/.