Skip to content

Agent mode: extractit task, extractit finalize and the skills

In agent mode the coding agent of the user (Claude Code, Codex, Gemini CLI) does the LLM part with its own subscription and extractit does the rest: parsing, citation verification, normalization, rules and confidence. extractit task and extractit finalize never call a model or an API and never start another agent; the candidates come from outside the process and are treated as untrusted data.

extractit task invoice.pdf --schema invoice.schema.json --rules rules.json -o pack/   # 1. work pack
# 2. the agent reads pack/TASK.md and writes pack/candidates.json
extractit finalize pack/ pack/candidates.json --validate-only                         # 3. check
extractit finalize pack/ pack/candidates.json -o result.json --agent claude-code      # 4. finalize
extractit task-images pack/ --pages 2,3                                               # when in doubt

The work pack

manifest.json            sha256 and size of every other file, chunks, granularity
TASK.md  FIELDS.md       instructions (English) and the field guide
document/chunk-NNN.md    the anchored text, by whole pages (--chunk-tokens, default 12 000)
candidates.schema.json   the output schema of T06: what the agent must write
candidates.example.json  a valid file with every field not_found
schema.json  rules.json  the extraction schema (with field ids) and the rules
docir.json  anchored.json  the parsed document and the AnchoredMarkdown, for extractit finalize
source.pdf  pages/       the PDF; page images on demand

The chunks concatenate to the text of anchored.json, which is what the renderer of T04 produces (--granularity line|block). schemas/task-pack-1.0.json is the contract of manifest.json.

candidates.json

One object shaped like candidates.schema.json; each field is {value, raw_text, anchors, quote, status} with status extracted, not_found or abstained (see TASK.md).

extractit finalize

  1. Verifies the manifest: every file of the pack must have its recorded size and sha256 (an altered docir.json is rejected), and no listed path may leave the pack.
  2. Validates candidates.json: at most 5 MB, well-formed JSON without duplicate keys or NaN, conformity to candidates.schema.json (unknown fields, wrong types, missing fields) and every cited anchor must exist in the document. All problems are listed with their JSON path in finalize-errors.json inside the pack, and the exit code is 2, so the agent can fix the file and retry.
  3. Converts with candidates_from_response (T06) and runs finalize of T08: normalization, word-level verification of the citations (T07), rules (T09) and heuristic confidence. extraction.mode = 'agent', extraction.agent.name from --agent, usage.billing = 'agent'. AI rules need a model, so they stay inconclusive with model_unavailable and are listed in warnings (ai_rule_unavailable).

Exit codes: 0 done, 1 execution error, 2 invalid candidates or altered pack, 3 review pending with --fail-on-review. --validate-only stops after step 2. Nothing in the candidates is ever used as a path or run as a command.

Skills

skills/ holds the skill of each agent, generated from one template (skills/_template/) by scripts/build_skills.py, and scripts/check_skills.py validates them: frontmatter with name and description, executable scripts, only extractit task, extractit task-images and extractit finalize, no keys, no claude -p, no network calls. extractit skills install --agent claude|codex|gemini [--scope user|project] [--dry-run] copies the skill to the folder each agent documents (checked 2026-11-10):

Agent User scope Project scope Context file
Claude Code ~/.claude/skills/extractit/ .claude/skills/extractit/ none
Codex ~/.agents/skills/extractit/ .agents/skills/extractit/ block in $CODEX_HOME/AGENTS.md (~/.codex) or ./AGENTS.md
Gemini CLI ~/.gemini/skills/extractit/ .gemini/skills/extractit/ block in ~/.gemini/GEMINI.md or ./GEMINI.md

The skill follows the steps: extractit task, read the pack, write candidates.json, validate, finalize; if requires_review is true or a field is unverified or contradicted, look at the pages with extractit task-images and correct (at most 2 rounds); report to the user. It tells the agent to use the CLI instead of re-implementing parsing, normalization, citation checks, rules or confidence.

Measuring agent mode

extractit eval --mode agent --candidates DIR reads DIR/<id>.candidates.json for every item, runs the same finalize and measures with the same metrics (items without candidates count as errors). extractit eval --emit-packs DIR writes a pack per document so an agent can fill them offline.

Limits

The quality depends on the agent and its model; the cost counts against the subscription of the user and cannot be measured (billing = 'agent', cost n/a), but the quality can, with extractit eval --mode agent. The tool uses no API and launches no agent. Gemini CLI: personal accounts lost access on 2026-06-18, so its skill is generated and validated but has not been run.