1. Introduction

Bibliographies, indexes, and tables of contents are among the densest primary sources in humanities research. A single bibliography maps what was published, by whom, when, and where — encoding canon formation, translation networks, editorial decisions, and disciplinary boundaries in a form that is, in principle, computationally tractable. In practice, most such sources exist only as scanned pages in physical volumes: undigitized, unrecognized by standard OCR pipelines, and effectively unanalyzable at scale.

The extraction problem is not new. Digital humanities projects have long sought to convert such sources into structured datasets. Data extraction is consistently rated as the most time and effort-consuming step in digital projects (Muñoz & Viglianti, 2015). The barrier is not conceptual but operational: the entry cost is high. Humanities researchers rarely have programming backgrounds. Some projects secure external funding for technical specialists. Many do not begin.

AI assistance is becoming increasingly common in this workflow, but the dominant interaction pattern is improvised. A researcher opens a new Claude conversation, explains their source from scratch, corrects the same misunderstandings, and produces output that cannot be reliably replicated in the next session. Each conversation starts from zero.

ArkSkill addresses this by inverting the interaction structure. Instead of the researcher explaining the source to Claude, ArkSkill elicits a structured description of the source from the researcher and compiles it into a SKILL.md file — a permanent instruction document that Claude reads at the start of any session, behaving from that point as a collaborator who already understands the archive.

This paper describes the design and implementation of ArkSkill. Section 2 situates the work. Section 3 describes the skill file format. Section 4 describes the generator architecture. Section 5 addresses the YAML sanitization problem. Section 6 describes the interface design. Section 7 discusses limitations and future work.

2. Related Work

2.1 Prompt Engineering and Persistent Instruction

A substantial literature addresses the problem of making AI behavior consistent and reusable. System prompts (Anthropic, 2024), prompt templates (Reynolds & McDonell, 2021), and constitutional AI methods (Bai et al., 2022) all address the alignment of model behavior with user intent. ArkSkill operates at a different level: rather than engineering a general-purpose prompt, it generates a source-specific instruction document that encodes domain knowledge rather than general behavioral preferences.

The closest analogues are few-shot example templates (Brown et al., 2020) and retrieval-augmented generation (Lewis et al., 2020), both of which inject structured context into model inference. ArkSkill's skill files function similarly but are authored once and reused across many sessions and many pages of the same source.

2.2 Digital Humanities Data Extraction

OCR post-correction, named entity recognition, and structured extraction from historical documents are active areas (Piotrowski, 2012; Ehrmann et al., 2021). Tools like Transkribus (Kahle et al., 2017) address layout analysis and transcription; OpenRefine (Verborgh & De Wilde, 2013) addresses downstream cleaning and reconciliation. ArkSkill occupies the gap between transcription and analysis: the step where transcribed text must be parsed into structured fields. Unlike these separate tools, ArkSkill integrates both OCR via Claude and no-code data extraction into a single workflow, eliminating the need to switch between tools. It also automatically flags ambiguous fields and generates the additional fields required for downstream clustering and analysis. In addition, for sources in non-Latin script languages (ex: Russian, Ukrainian) it creates fields with transliteration according to the Library of Congress system.

2.3 Low-Code Tools for Humanities Research

The "no-code" and "low-code" movement in digital humanities (Dombrowski, 2020) motivates tools that lower technical barriers without eliminating methodological rigor. ArkSkill follows this tradition: the eight-question form requires no technical knowledge, but the generated skill file encodes genuine expert knowledge about the extraction problem.

3. The Skill File Format

A SKILL.md file is a Markdown document with YAML frontmatter. It has two components: a structured metadata header and a natural-language instruction body. Claude reads the entire file as context before processing any source pages.

3.1 Frontmatter

The frontmatter encodes the source parameters in a machine-readable form:

---
name: Soviet Literature
source_type: literary journal table of contents
language: English
sample_entry: |
  GEORGI BEREZKO - A Night in the Life of
  a Commander
  BORIS POLEVOY - The Story of a Real Man
  (continued) .
entry_meaning: one article or published work
expected_fields: year, issue, author, title, genre, pages, rubric
periodical: true
combine_with_other_sources: yes
---

The sample_entry field is the most important. A raw, uncleaned entry from the actual source — dot-leaders, OCR artifacts, inconsistent spacing and all — gives Claude a direct example of what it will encounter. This is more informative than any prose description. The YAML block scalar format (|) is required here; free-form multiline text with colons, dashes, and special characters breaks standard YAML scalar parsing (see Section 5).

3.2 Instruction Body

The instruction body specifies extraction behavior in natural language, organized into sections:

• Source: A one-paragraph description of the source and entry structure, generated from the frontmatter fields.
• Output fields: User-defined fields, inferred fields, and system fields (needs_review, issue_id, source_id).
• Extraction rules: Handling of names, titles, page numbers, multivalued fields, ambiguous content, end-of-page truncation, and section headings.
• Output format: CSV specification (UTF-8, quoted values, needs_review first).
• Data notes: Guidance on identifier propagation, author normalization, and QA philosophy.

The instruction body does not vary by source type. It encodes a fixed set of extraction principles that apply across all historical structured sources. The frontmatter parameters specialize these principles for the specific case.

The instruction body also functions as a hallucination guardrail. Standard prompting leaves the model to infer what "good output" looks like, which in practice means all fields populated and no uncertainty flagged. Without explicit rules governing absence and ambiguity, models tend to fill missing values with plausible-looking reconstructions rather than admitting they are absent or uncertain — a well-documented LLM pattern. The consequences are twofold: either the dataset becomes extremely difficult to proofread, since identifying suspicious entries requires tracing back every record individually; or, worse, it becomes silently unreliable, as confidently hallucinated values propagate into statistics and downstream analysis without any visible signal that something is wrong. The skill file closes this gap by making every failure mode a named case with a prescribed response: unreadable characters become [?], absent fields become [absent], and uncertain entries become REVIEW flags. The model is never left to decide between guessing and flagging — the decision is made in advance, in the skill file, by someone who understands the source. This does not eliminate hallucination but it significantly reduces its surface area: the model's generative freedom is constrained to the fields that exist, the values that are present, and the flagging conventions that are specified.

3.3 System Fields

Three system fields are generated automatically, conditional on source parameters:

needs_review — Always present. Set to "REVIEW" when any field contains [?], a mandatory field is absent, or OCR damage makes the entry unreliable. This is the primary QA signal: a missed flag is harder to recover from than a false alarm.

issue_id — Generated only when periodical: true. Format: {name}_{issue_number}, falling back to {name}_{year}_{month} or {name}_00{x} when issue metadata is unclear. Populated on every row once established.

source_id — Generated when combine_with_other_sources is yes or maybe. Format: {name}_{year} when year is known, {name}_{edition_number} otherwise. Enables cross-source reconciliation in downstream cleaning. The threshold for generation is deliberately low: a researcher who is "maybe" combining sources should have the column — it is easy to remove and impossible to reconstruct retroactively.

4. Generator Architecture

ArkSkill is a single-page React application built with Vite and TypeScript, deployed on Vercel. Skill generation requires no backend. The SKILL.md file is produced entirely client-side through structured string interpolation.

4.1 Template Interpolation

The template is a string constant containing placeholder tokens ({name}, {source_type}, etc.). The generateSkill function replaces each token with the corresponding sanitized user input:

const generateSkill = () => {
  const clean = (s: string) => s.trim().replace(/\s+/g, " ");

  const indentedSample = (sampleEntry || "[no sample provided]")
    .trim()
    .split("\n")
    .map(line => "  " + line.trim())
    .filter((_, i, arr) => !(i === 0 && arr[i].trim() === ""))
    .join("\n");

  const filled = template
    .replaceAll("{name}", clean(sourceTitle) || "[untitled]")
    .replaceAll("{source_type}", clean(sourceType) || "[unknown]")
    .replaceAll("{language}", clean(language) || "[unknown]")
    .replaceAll("{sample_entry_indented}", indentedSample)
    .replaceAll("{sample_entry}", (sampleEntry || "[no sample provided]").trim())
    .replaceAll("{entry_meaning}", clean(entryMeaning) || "[unknown]")
    .replaceAll("{expected_fields}", clean(outputFields).replace(/,\s*$/, "") || "[unknown]")
    .replaceAll("{periodical}", isPeriodical === "yes" ? "true" : "false")
    .replaceAll("{combine}", combineSources ?? "maybe");

  setGeneratedSkill(filled);
};

The clean function collapses internal whitespace and trims leading/trailing whitespace from all single-line fields. The sample_entry field receives special treatment (see Section 5).

4.2 Client-Side Download

The generated skill file is offered as a browser download via a Blob URL:

const downloadSkill = () => {
  if (!generatedSkill) return;
  const blob = new Blob([generatedSkill], { type: "text/markdown" });
  const url = URL.createObjectURL(blob);
  const a = document.createElement("a");
  a.href = url;
  a.download = `${sourceTitle || "skill"}.md`;
  a.click();
  URL.revokeObjectURL(url);
};

No data is transmitted to any server. The skill file is generated and downloaded entirely in the browser. This is not a limitation but a deliberate design choice: research data about specific archival sources should not pass through third-party infrastructure. The tool is also trivially forkable and self-hostable by any institution with different privacy requirements.

4.3 Routing and Deployment

The application uses React Router for client-side routing between the landing page (/) and the skill builder (/build_skill). Vercel's build detection handles the Vite configuration automatically. The repository is connected to Vercel for continuous deployment on push.

5. The YAML Sanitization Problem

The most non-trivial engineering problem in ArkSkill is YAML frontmatter correctness under adversarial user input.

YAML is a strict format. A colon followed by a space in a scalar value is interpreted as a key-value separator. A leading dash is a list item marker. A # begins a comment. Multiline strings require explicit block scalar syntax. A user pasting a raw bibliography entry — which may contain all of these characters — will reliably break naive YAML construction.

5.1 The Block Scalar Solution

The sample_entry field uses the YAML literal block scalar format (|), which treats all indented content following the marker as a literal string regardless of its contents:

sample_entry: |
  GEORGI BEREZKO - A Night in the Life of
  a Commander
  BORIS POLEVOY - The Story of a Real Man
  (continued) .

The indentation is mandatory and must be consistent. The generateSkill function applies uniform 2-space indentation to every line of the sample entry after trimming:

const indentedSample = (sampleEntry || "[no sample provided]")
  .trim()
  .split("\n")
  .map(line => "  " + line.trim())
  .filter((_, i, arr) => !(i === 0 && arr[i].trim() === ""))
  .join("\n");

The .trim() call on each line removes inconsistent leading whitespace before the 2-space indent is applied. The .filter() removes empty first lines, which would shift the block scalar's content and invalidate the indentation reference.

5.2 Single-Line Field Sanitization

Single-line fields receive the clean function, which collapses internal whitespace sequences to single spaces and trims leading/trailing whitespace. This handles copy-paste artifacts from PDF viewers, which often introduce extra spaces between words. The expected_fields field additionally strips trailing commas, which users frequently add after the last field name.

5.3 What Sanitization Does Not Handle

The sanitization pipeline handles whitespace, trailing commas, and multiline content. It does not handle: (a) YAML anchors and aliases in user input, (b) null bytes, (c) content exceeding the YAML specification's line length recommendations. These are edge cases unlikely to appear in humanist source descriptions, but they represent known failure modes for future hardening.

6. Interface Design

The interface follows a deliberate editorial aesthetic. IBM Plex Mono is used throughout — a monospaced font that signals technical precision while remaining readable. The background is a warm off-white (#f5f2ec), borders are black, and a signature gold (#EDBF6F) is used for emphasis on key terms and calls to action. The isometric grid background is a visual metaphor for the structured, tabular nature of the data ArkSkill helps extract.

6.1 The Eight-Question Form

The form elicits the parameters needed to specialize the skill template:

Questions 2, 4, 5, 6, and 8 have inline hint panels, accessible via an i button, that provide guidance specific to each question without cluttering the primary interface. The hints address the most common errors observed in informal user testing: overly generic source type descriptions, cleaned-up sample entries, and underspecified output fields.

6.2 Contextual Guidance

Question 4 (sample entry) has an additional inline hint triggered by clicking the word "entry": Don't clean it up — paste it raw, errors and all. Paste 2–3 if entries vary. This addresses a consistent user error: researchers instinctively clean OCR artifacts before pasting, which removes exactly the information that makes the sample entry useful.

Question 8 (combine sources) carries an asymmetric recommendation in its hint: researchers who are "even slightly considering" combining sources should answer Maybe or Yes. The source_id column is cheap to generate and expensive to reconstruct retroactively. This reflects a genuine data management principle that is easy to overlook at the extraction stage.

6.3 Post-Generation Flow

After generating the skill file, users are presented with two download buttons (SKILL.md and a plain-language installation guide, GUIDE.txt) and two informational panels introducing the needs_review column and OpenRefine. The OpenRefine introduction links to a beginner's guide written by the ArkSkill team, covering clustering, Wikidata reconciliation, and basic cleaning operations for the kinds of datasets ArkSkill produces.

7. Limitations

Template coverage. The skill template encodes extraction principles for a specific class of source: historical bibliographies, indexes, and tables of contents in Western European scripts. Sources with fundamentally different structure — inventories, account books, parish registers, musical incipits — may require template variations not covered by the current generator. The eight-question form cannot anticipate every field variation or OCR failure mode.

No feedback loop. ArkSkill generates a skill file but has no mechanism for ingesting the results of extraction back into the template. A researcher who discovers that Claude mishandles a particular field type must edit the skill file manually. A future version could support iterative skill refinement based on flagged rows.

Single model dependency. The skill files are authored for Claude's instruction-following behavior. Behavior may vary across Claude versions, and the template has not been tested against other models.

No evaluation dataset. We do not report extraction accuracy metrics because we do not have a labeled ground-truth dataset of historical bibliography entries. Constructing such a dataset is a substantial undertaking and is future work. The current paper describes the system design; empirical evaluation is left for subsequent publication.

Client-side only. Skill generation is entirely client-side, which is a feature for privacy but a limitation for institutional deployment scenarios that require server-side logging, access control, or template versioning.

8. Conclusion

ArkSkill addresses a specific and underserved gap in humanities digital research: the interface between researchers who possess domain knowledge about historical structured sources and AI systems capable of extraction at scale. The contribution is a parameterized instruction template that makes implicit expertise explicit and persistent — compiled once, reused across many sessions, and portable across collaborators and institutions.

The system was built and deployed in a single buildathon cycle, placing second at the Claude Buildathon (April 2026). It is free, open, and deployed at arkskill.vercel.app.

The broader principle generalizes beyond humanities data extraction. Any domain where AI-assisted work requires consistent, source-specific behavior — medical record parsing, legal document analysis, archival finding aid generation — faces the same interface problem: domain knowledge is tacit, interaction is improvised, and results are inconsistent. Skill files are one answer to that problem.

Acknowledgments

The project was built during the Claude Buildathon, April 2026.

References

Anthropic. (2024). Claude's character. Anthropic documentation.

Bai, Y., Jones, A., Ndousse, K., Askell, A., Chen, A., DasSarma, N., ... & Kaplan, J. (2022). Training a helpful and harmless assistant with reinforcement learning from human feedback. arXiv preprint arXiv:2204.05862.

Brown, T., Mann, B., Ryder, N., Subbiah, M., Kaplan, J. D., Dhariwal, P., ... & Amodei, D. (2020). Language models are few-shot learners. NeurIPS, 33.

Dombrowski, Q. (2020). What's a digital humanist to do in the age of COVID-19? Debates in the Digital Humanities.

Ehrmann, M., Hamdi, A., Ponti, E. M., Romanello, M., & Pires, T. (2021). Named entity recognition and classification on historical documents: A survey. ACM Computing Surveys, 56(2).

Kahle, P., Colutto, S., Hackl, G., & Mühlberger, G. (2017). Transkribus — A service platform for transcription, recognition and retrieval of historical documents. IAPR Workshop on Document Analysis Systems.

Lewis, P., Perez, E., Piktus, A., Petroni, F., Karpukhin, V., Goyal, N., ... & Kiela, D. (2020). Retrieval-augmented generation for knowledge-intensive NLP tasks. NeurIPS, 33.

Muñoz, T., & Viglianti, R. (2015). Texts and documents: New challenges for TEI interchange and the role of blind review. Journal of the Text Encoding Initiative, 8.

Piotrowski, M. (2012). Natural language processing for historical texts. Synthesis Lectures on Human Language Technologies.

Reynolds, L., & McDonell, K. (2021). Prompt programming for large language models: Beyond the few-shot paradigm. ACM CHI Extended Abstracts.

Verborgh, R., & De Wilde, M. (2013). Using OpenRefine. Packt Publishing.