deckprobe skill

DeckProbe

ffprobe for documents. One shell command answers a specific question about a PDF, Office, or iWork file; the answer comes back as JSON on stdout and the exit status carries the verdict.

Reach for it when a task needs facts about a document — how many slides, is it encrypted, does it have macros, is it corrupt, is this really a .pptx — rather than the text inside it. It is safe on untrusted input: nothing is rendered, no macro runs, no external reference is followed.

1. Make sure it runs

npx skills add installs this document only, not the binary. Check first:

deckprobe --version

• Prints a version → use deckprobe as written throughout this document.
• Command not found, but node exists → the command is npx -y @deckflow/deckprobe. Prefix every example below with it. First run downloads the package; later runs are cached.
• Neither → ask the user to install one of:
  • curl --proto '=https' --tlsv1.2 -LsSf https://github.com/deckflow/deckprobe/releases/latest/download/deckprobe-installer.sh | sh
  • npm install -g @deckflow/deckprobe
  • cargo install --git https://github.com/deckflow/deckprobe --locked deckprobe

If you cannot get it running, say so and stop. Do not fall back to unzipping the package, grepping XML, or parsing PDF bytes by hand — avoiding exactly that is the point of this tool.

2. The shape of every call

deckprobe [-t TARGETS] [-l LEVEL] [-c CONFIDENCE] [--view values] [--pretty] FILE

Start here when you do not yet know what you need:

deckprobe -t @summary --view values --pretty report.pdf

--view values returns a compact target -> value map. Drop it when you also need each value's confidence, the path that produced it, and the measured cost.

Check the exit status before parsing stdout. A non-zero status still writes valid JSON, but it is an error envelope, not a report.

3. Choosing targets

-t accepts short names (slide_count), canonical names (powerpoint.slide_count), and selector presets. It is repeatable and comma-separated: -t @header,title,page_count.

Selector	Expands to
@header	Container identity only — format, size, extension match, encryption flag
@default	The driver's defaults for the active level. Used when -t is omitted
@summary	Identity, common metadata, and primary structure
@security	Encryption, macros, signatures, external references, active content
@structure	Format-owned counts, names, and dimensions
@assets	Images, media, previews, fonts, embedded objects
@quality	Integrity, repair, extension match, conformance
@format	Every format-specific target at the active level
@all	Everything available at the active level

@summary deliberately omits a statistic the current driver can only get from a full-file read. PDF page count is the notable case — ask for page_count or @structure explicitly.

Never guess a target name. The tool documents itself:

deckprobe targets --format pptx --pretty   # ids, aliases, min level, value type, cost class
deckprobe formats --pretty                 # drivers, profiles, support boundaries
deckprobe schema --pretty                  # the authoritative report JSON Schema

references/targets.md has the full catalogue per format if you would rather read than run.

4. Probe level and confidence

-l / --level picks the budget and which paths are eligible. Accepts h/m/d too.

Level	Use it for
header	Identity and container properties. ~500 ms budget
metadata	Default. Bounded metadata and common structural counts. ~500 ms
deep	Higher-cost paths. ~5 s — only when a target's min_level says deep

-c / --confidence filters eligible paths: low < medium < high (default) < exact. Lower it when a target comes back unresolved and an approximate answer is acceptable; raise it with -C target=exact for a single target that must be authoritative.

5. Reading the report

{
  "schema_version": 2,
  "status": "ok",              // "ok" | "partial" | "error"
  "input":  { "display_name": "deck.pptx", "source_kind": "local_file" },
  "driver": { "id": "powerpoint", "profile": "pptx" },
  "results": {
    "powerpoint.slide_count": {
      "status": "resolved",     // see the eight values below
      "value": 31,
      "confidence": "high",     // none | low | medium | high | exact
      "path": "powerpoint.app_statistics",
      "source": "docProps/app.xml saved statistic"
    }
  },
  "execution": { "unresolved_targets": [], "actual_cost": { } },
  "diagnostics": []
}

A result's status is one of resolved, estimated, planned, unknown, unsupported, invalid, budget_exceeded, failed. Only resolved and estimated carry a value. unknown is the common one: the path ran and the document simply does not record that fact.

• The report's own status is ok or partial. partial is not a failure — at least one requested target could not be resolved at the requested confidence, and the rest are still valid. Check execution.unresolved_targets.
• Add --strict when an unresolved target must fail the command. The full report is still written, and the exit status becomes 5.
• results is keyed by the canonical target name even when you asked with a short alias.

6. Exit status — and what to do about it

Status	Meaning	Your next move
0	Success	Parse stdout. Unresolved targets are allowed unless --strict
1	Invalid request or unsupported target	You named a target this format has no path for. Run deckprobe targets --format <fmt>
2	CLI syntax error, or the file is missing/unreadable	Fix the flags or the path
3	Unsupported or unrecognized format	Check the extension against deckprobe formats
4	Malformed input or budget exceeded	Genuinely damaged file, or raise -b/-x/-e/-T. See references/limits.md
5	--strict and a target was unresolved	The report is on stdout; decide whether the missing target matters
6	Internal failure	A bug. Report it

7. Many files at once

printf '%s\n' '{"path":"a.pdf"}' '{"path":"b.pptx"}' | deckprobe --jsonl -t @summary

One compact JSON per non-empty input line. A per-record error does not stop the run; the process exits with the highest per-record status. Each record is a JSON string path, {"path":"..."}, or {"name":"report.pdf","data_base64":"..."}. Add an id to an object record when the caller needs stable attribution; JSONL error envelopes echo that id and the original path under input.

For bytes on stdin, -n supplies the logical filename that selects the format:

curl -sL "$url" | deckprobe -n download.pdf -t @security -

8. What DeckProbe will not do

It has no renderer, no OCR, no text extraction, and no macro interpreter. It never opens a network connection and never resolves an external reference. Legacy XML iWork packages are rejected by design — only modern IWA is supported. .xlsb is identity-only. PDF XMP is not merged into the metadata targets.

Routing is by filename extension, then verified against the container. Renaming a .pptx to .docx returns MALFORMED_INPUT, and -f/--input-format is an assertion, not an override — it cannot force an unrelated parser onto a file.

Never parse stderr. Every result, including every error, is one JSON value on stdout.

References

Read these only when you need them:

• references/targets.md — the full target catalogue per format, with aliases and minimum levels. Read before naming a target you have not verified.
• references/recipes.md — task → command lookup for the common questions.
• references/output.md — the complete report shape, error codes, and cost accounting, for when you are consuming the JSON programmatically.
• references/limits.md — budgets, the -b/-x/-e/-T overrides, -O format options, and how to diagnose an exit 4.