mirror of https://github.com/magnus919/agent-skills.git synced 2026-09-11 19:47:12 +03:00

Files

T

f37dc73829 feat(skill): add anydoc — office documents to GitHub-Flavored Markdown (#295 )

* feat(skill): add anydoc core content and references

Add the anydoc skill content tree: SKILL.md (progressive-disclosure index
with frontmatter per ALLOWED_FIELDS), human-facing README, the five reference
files (formats, cli-reference, errors, workflows, sources), 24 committed
fixtures (valid + error cases), and a fixture-grounded eval manifest with 8
cases. Every documented behavior, exit code, and error message was verified
against the real pinned CLI (npx -y @firecrawl/anydoc@0.1.6); verbatim --help
and error transcripts are reproduced character-for-character.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

* feat(skill): add anydoc wrapper script and unit tests

Implements scripts/anydoc, a stdlib-only Python wrapper around the pinned
@firecrawl/anydoc@0.1.6 CLI: convert/batch/info subcommands, global
--json/--dry-run, input and output pre-validation, friendly hints for the
no-OCR/encrypted/malformed/unsupported error classes, Node >= 20 and npx
availability checks, deterministic batch output naming with documented
duplicate/collision behavior, and exit codes 0/1/2. Adds offline unittest
suite (46 tests, real-CLI tests skip when npx is unavailable) and keeps the
wrapper contract documented in cli-reference.md and errors.md.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

* feat(skill): ratchet anydoc evals to 14 grounded cases

Verify the pre-authored 8-case manifest and extend it with six
high-signal cases (PDF lower-fidelity pipeline, legacy .ppt table
flattening, ODP same-serializer, RTF, EPUB, CSV header promotion),
each grounded in real pinned-CLI runs against the committed fixtures.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

* feat(skill): integrate anydoc into repo catalog and artifacts

Add the sorted anydoc catalog entry to README.md (between agent-skills
and api-design-and-evolution), regenerate the tracked catalog artifacts
(.claude-plugin/marketplace.json, .codex-plugin/plugin.json,
.agents/plugins/marketplace.json, llms.txt) with the ruby generators,
and add a routing note to documents/SKILL.md pointing office-document
to-markdown conversion at the anydoc skill.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

* fix(skill): polish anydoc wrapper timeout, JSON shape, and docs

- run_cli raises CliTimeoutError on the 120s timeout; convert/batch with
  --json now emit one parseable JSON error envelope (error_class "timeout")
  on stdout before exiting, so --json always yields exactly one JSON doc
- batch JSON failure entries (pre-validation and CLI) now carry error_class
  ("io" for missing/dir inputs, mapped classes for CLI failures), so all
  batch failure entries share the same shape
- build_cli_command places -o/-f before the -- separator for dash-leading
  filenames, so `convert -f csv -- -weird` converts instead of misparsing
  ("unexpected second input"); absolute-path inputs unchanged
- workflows.md vault-ingestion recipe globs notes/* instead of docs/* and
  warns to run from a temp/vault dir, never touching repo-root docs/
- unit tests: +6 (timeout envelope x4, batch error_class shape,
  dash-leading filename); suite grows 46 -> 52

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

---------

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

2026-08-06 20:11:19 -04:00

10 KiB

Raw Blame History

name, description, license, compatibility, metadata, allowed-tools

name

description

license

compatibility

metadata

allowed-tools

anydoc

Convert Word (.doc/.docx/.docm), PowerPoint (.ppt/.pps/.pot/.pptx/.pptm/.ppsx/.ppsm), Excel (.xls/.xlsx/.xlsm/.xlsb), OpenDocument (.odt/.ods/.odp), RTF, EPUB, CSV, and PDF documents to clean GitHub-Flavored Markdown locally with the Any Doc CLI (npx -y @firecrawl/anydoc@0.1.6): headings, GFM tables, slide structure, and footnotes in one pass. Use when a task needs the contents of an office document, spreadsheet, presentation, ebook, or PDF you cannot read directly. Do not use for generating, editing, or validating documents (use documents), for ebook packaging (use epub), or for OCR of scanned or image-only PDFs (anydoc does not OCR; route to OCR tooling).

MIT

Node.js >= 20 and npx. The pinned CLI is @firecrawl/anydoc@0.1.6; the native binary ships via npm optionalDependencies (no install step, no postinstall, no compilation). Conversion runs entirely on your machine — no services, no API keys, no uploads. The first npx run downloads the package once (network required); later runs use the npm cache.

skills	tags	source
anydoc, markdown, conversion, docx, xlsx, pptx, pdf, odt, ods, odp, rtf, epub, csv, office, documents, firecrawl	conversion, markdown, office, documents	https://github.com/firecrawl/anydoc

Bash Read

Any Doc — office documents to GitHub-Flavored Markdown

The anydoc skill converts office documents, spreadsheets, presentations, ebooks, CSV, and text-based PDFs into GitHub-Flavored Markdown using the pinned Any Doc CLI (@firecrawl/anydoc v0.1.6). One shared document model and one GFM serializer produce the same logical output across formats, and conversion runs locally in milliseconds — no service, no API key, no file upload.

Overview

Load this skill when a task needs the contents of a document the agent cannot read directly: a Word report to summarize, a spreadsheet to turn into a table, a slide deck to extract, a CSV to analyze, or an ebook or PDF to quote from.

The skill ships a small Python helper (scripts/anydoc) that wraps the pinned CLI and adds input pre-validation, friendly error hints, batch conversion, and --dry-run/--json output. Every recipe in references/workflows.md also shows the raw npx invocation, so the skill works with or without the helper.

When to use

Convert a document to markdown — Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV, or text-based PDF.
Extract structure — headings, GFM tables, slide titles, speaker notes (as blockquotes), and footnotes.
Feed documents to an LLM — one-pass conversion to clean markdown for summarization, extraction, or retrieval ingestion.
Batch a folder — convert a directory of mixed office files for a vault or knowledge base.
Read a document from stdin — pipe bytes into anydoc -.

Format coverage (summary)

anydoc covers 8 format families / 21 extensions through 12 canonical parsers. The canonical formats are doc, docx, odt, pdf, ppt, pptx, rtf, epub, xlsx, ods, odp, csv; extension aliases map through them (.docm→docx, .xls→xlsx, .pptm→pptx, and so on).

Family	Extensions	Expected GFM output
Word	`.doc` `.docx` `.docm`	`#`–`######` headings, GFM tables, `[^n]` footnotes
PowerPoint	`.ppt` `.pps` `.pot` `.pptx` `.pptm` `.ppsx` `.ppsm`	slide titles as plain paragraphs, bullet lists, speaker notes as `>` blockquotes, GFM tables (PPTX/ODP; legacy `.ppt` flattens tables to text lines)
Excel	`.xls` `.xlsx` `.xlsm` `.xlsb`	`## <sheet name>` heading + one GFM table per worksheet; number formats dropped (raw cell values)
OpenDocument	`.odt` `.ods` `.odp`	same document/slide shapes as DOCX/PPTX; ODS keeps formatted display values
Rich Text Format	`.rtf`	same document shape as DOCX/ODT
EPUB	`.epub`	`#` chapter headings, GFM tables, internal anchor links
CSV	`.csv`	one GFM table; label-like first row promoted to header; delimiter sniffing; UTF-16 with BOM
PDF	`.pdf`	headings + inline emphasis, but a lower-fidelity pipeline: tables flatten to text, footnotes and links degrade. Scanned or image-only PDFs fail — anydoc does not OCR

See references/formats.md for the full per-format expectations and fidelity caveats, and references/errors.md for the exact failure messages (including the no-OCR error).

Command Map

Commands are shown relative to the repository root. <file> is any document path (for example anydoc/fixtures/fixture-handmade-outline.docx); - reads the document from stdin.

Need	Command
Convert one file (markdown to stdout)	`anydoc/scripts/anydoc convert <file>`
Convert one file to a markdown file	`anydoc/scripts/anydoc convert <file> -o out.md`
Convert many files to a directory	`anydoc/scripts/anydoc batch <file1> <file2> ... --out-dir out/`
Show the tool and pinned CLI version	`anydoc/scripts/anydoc info`
Raw pinned CLI, one document	`npx -y @firecrawl/anydoc@0.1.6 <file> [-o out.md]`
Raw pinned CLI, read stdin	`cat data.csv \| npx -y @firecrawl/anydoc@0.1.6 - --format csv`

Notes:

scripts/anydoc is an executable Python 3 script (shebang #!/usr/bin/env python3); python3 anydoc/scripts/anydoc ... is equivalent when the executable bit is unavailable.
The raw npx -y @firecrawl/anydoc@0.1.6 rows are the ground truth for conversion behavior; the wrapper delegates to exactly that command.
Always pin @0.1.6 for reproducible conversions. -y answers npx's "Ok to proceed?" prompt non-interactively — the CLI itself never prompts.
Both forms share the same contract: one document per invocation, exit code 0 success / 1 conversion or IO failure / 2 usage error, diagnostics as exactly one anydoc: <message> line on stderr, and no prompts.

Reference Routing

Load these on demand — one per topic:

references/formats.md — the 8 families / 21 extensions / 12 parsers, what GFM each format produces, and the fidelity caveats (xlsx/xls number-format drop vs ODS preserved display values, legacy .ppt table flattening, PDF lower-fidelity pipeline, merged-cell covered spans, ODP same-serializer).
references/cli-reference.md — verbatim --help, every flag (-o, -f, -h, -V, --format=x, --), stdin via -, stdout/stderr conventions including EPIPE, version pinning, Node >= 20, and first-run/offline network behavior.
references/errors.md — exit codes 0/1/2, the verbatim error-message vocabulary (io, unsupported, malformed, encrypted, EISDIR, resource-limit, usage errors), the no-OCR caveat, and troubleshooting recipes.
references/workflows.md — single conversion, batch loops, vault ingestion, stdin/stdout piping, output verification, large-file/resource-limit behavior, and startup cost.
references/sources.md — upstream URLs, access dates, fixture provenance, and how every documented claim was verified against the real CLI.

When not to use

Generating, editing, or validating documents — anydoc only converts existing documents to markdown; it never creates, edits, or checks documents. Use the documents skill for generation, inspection, and validation of PDF/Word/Excel/PowerPoint artifacts.
Ebook packaging or EPUB authoring — use the epub skill. anydoc reads EPUBs to markdown but never writes or validates EPUB containers.
Scanned or image-only PDFs (OCR) — anydoc does not perform OCR. Such PDFs fail as unsupported with the OCR message; route the file to OCR tooling or the hosted Firecrawl Parse API instead of retrying locally. Do not claim local OCR support.
HTML and other web content — HTML is not a supported input format; use a web-scraping skill instead.
Binary media (images, video, audio) — embedded images render as alt text only; anydoc cannot transcribe media content.
Layout or rendering work — output is GitHub-Flavored Markdown only; there is no pagination, font, or template control.
Password-protected files — encrypted documents fail with anydoc: document is encrypted; there is no password or decryption option.

Verification

Confirm a conversion before reporting it as done:

Check the exit code. 0 means the CLI produced markdown. 1 means the document could not be read or converted — read the single anydoc: <message> stderr line and match it against references/errors.md. 2 means the command itself was a usage error (bad flag, missing input, invalid --format).
Check the output shape. The markdown must contain the structural markers your format actually produces:
- Word / ODT / RTF / text-based PDF: #/## headings. For PDF, do not expect GFM tables or [^1]: footnote definitions — that pipeline flattens them.
- Spreadsheets (xlsx/xls/ods) and CSV: |-delimited GFM tables. xlsx/xls show raw cell values (0.155, 1234.5); ODS shows formatted display values (15.5%, $1,234.50).
- Presentations (pptx/odp): slide titles as plain paragraphs, > blockquote speaker notes, GFM tables. Legacy .ppt flattens tables to bare text lines.
- EPUB: # chapter headings and internal anchor links.
Write large outputs to a file with -o. -o out.md keeps stdout silent and gives a reviewable file instead of streaming the whole document into context.
Verify tables survived. If the source had tables and the output has no | rows, consult the format caveats — PDF and legacy .ppt flatten tables by design, not by error.

Stop when the conversion exits 0 and the structural markers match the source format. Do not re-run or retry on a documented failure mode (encrypted, malformed, scanned/image-only, unsupported) without changing the input; report the documented message and route as references/errors.md instructs.

10 KiB Raw Blame History Unescape Escape