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
- Verifies the manifest: every file of the pack must have its recorded size and sha256 (an altered
docir.jsonis rejected), and no listed path may leave the pack. - Validates
candidates.json: at most 5 MB, well-formed JSON without duplicate keys orNaN, conformity tocandidates.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 infinalize-errors.jsoninside the pack, and the exit code is 2, so the agent can fix the file and retry. - Converts with
candidates_from_response(T06) and runsfinalizeof T08: normalization, word-level verification of the citations (T07), rules (T09) and heuristic confidence.extraction.mode = 'agent',extraction.agent.namefrom--agent,usage.billing = 'agent'. AI rules need a model, so they stayinconclusivewithmodel_unavailableand are listed inwarnings(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.