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

8.9 KiB

Raw Blame History

name, description, license, compatibility, metadata

name

description

license

compatibility

metadata

documents

Generate, inspect, validate, and fix PDF, Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) documents: turn structured content into render-ready artifacts, verify structural and output quality before delivery, and repair broken files. Use when a task involves creating, editing, converting, or validating office documents and PDFs. Do not use for ebook packaging (use epub), for images, video, or other media production, for API or code documentation, or for data pipelines (use data-engineering).

MIT

Python 3.8+ for scripts; validation uses only the standard library. Optional renderers for the render check: poppler-utils (pdftoppm) for PDF and LibreOffice for Office formats; both degrade gracefully when absent. Portable across all AgentSkills-compatible harnesses.

skills	tags
documents, pdf, docx, xlsx, pptx, word, excel, powerpoint, office, report, generation	documents, pdf, docx, xlsx, pptx, word, excel, powerpoint, office, generation, validation

Documents — PDF, Word, Excel & PowerPoint Skill

One skill for the four most common document formats. All four share a single agent workflow — structured content in, render-ready, validated artifact out — so they live in ONE family skill with per-format references, following the epub precedent. Load the shared workflow below, then pull the per-format reference for the format you are actually touching.

Format	Extension	Reference (load on demand)
PDF	`.pdf`	references/pdf.md
Word	`.docx`	references/word.md
Excel	`.xlsx`	references/excel.md
PowerPoint	`.pptx`	references/powerpoint.md
All formats	—	references/output-quality.md

Generation templates for each format live in templates/, and the validation script with per-format fixtures lives in scripts/.

When to use

Load this skill when the task involves any of the four formats:

Generate: build a report, memo, spreadsheet, or deck from structured content (markdown, JSON, data tables, outlines).
Edit: modify an existing document's content, layout, or metadata in place.
Extract: pull text, tables, or structure out of an existing file.
Convert: move content between formats or from a data source into a document.
Validate: check that a produced artifact is structurally sound and will render correctly before it is delivered.

When not to use

Ebooks and EPUB — use the epub skill; it owns the EPUB container, reading order, and package validation.
Images, video, and other media — this skill covers document formats only; route media production to the appropriate media skills.
Code and API documentation sites — use the technical-documentation and documentation-site conventions, not office documents.
Data pipelines — moving or transforming raw data belongs to data-engineering; Excel here is a deliverable format, not a data store.
Office documents to Markdown — converting an existing office document (docx, xlsx, pptx, pdf, odt, rtf, epub, csv) to GitHub-Flavored Markdown belongs to the anydoc skill; this skill owns generation, editing, and validation, not document-to-markdown extraction.

The Shared Workflow

Every document task follows the same six steps, regardless of format. Deep format-specific detail is deferred to the per-format reference — read it at the step where it matters.

1. Scope

Pin down what the document is for before touching a file:

Audience and purpose — who reads it and what decision it supports.
Format — PDF (fixed layout, print, archival), Word (editable prose, review), Excel (data, calculations), PowerPoint (presentation).
Boundaries — page/slide count, size limits, brand or style constraints.
Source of truth — the structured content the document is generated from (markdown, JSON, CSV, outline), so the artifact is reproducible.

2. Content model

Represent the document's content as structured data before rendering:

A title, sections/headings, body text, and metadata for prose documents.
A table model (headers, rows, column types) for spreadsheets.
A slide outline (title + bullets per slide, speaker notes) for decks.
Keep content and layout separate: content in the model, layout in the template. This is what makes regeneration cheap.

3. Template

Choose the generation template for the target format from templates/:

templates/pdf-template.md — fixed-layout document skeleton (print-ready HTML/CSS or LaTeX source).
templates/word-template.md — Word processing document structure (styles, headings, tables).
templates/excel-template.md — workbook structure (sheets, cells, shared strings, formulas).
templates/powerpoint-template.md — slide deck structure (slides, layouts, notes).

Fill the [fill: ...] markers in the template with content from the content model. Templates are the contract between content and layout — changing the template is how you change appearance without touching content.

4. Render

Produce the artifact file:

PDF — render the template to PDF (print CSS in a browser or engine, or a LaTeX toolchain). See references/pdf.md for tooling.
Word / Excel / PowerPoint — write the OOXML package directly (stdlib zipfile + XML for small artifacts) or with the conventional library for the format (python-docx, openpyxl, python-pptx). See the per-format reference for the exact package layout to produce.

5. Validate

Never deliver unvalidated output. Run the validation script:

python3 scripts/validate-documents.py --render-check --json report.pdf brief.docx data.xlsx deck.pptx

The script performs structural sanity (container signatures, required parts, XML well-formedness) and, when a renderer is installed, a render check (actually renders the file). When no renderer is present it reports unavailable instead of failing — validation never hard-requires a renderer. See references/output-quality.md for the full output-quality checklist, and the fixture files in fixtures/ (one per format) to smoke-test the script itself:

python3 scripts/validate-documents.py --json fixtures/sample.pdf fixtures/sample.docx fixtures/sample.xlsx fixtures/sample.pptx

6. Deliver

Hand off the artifact with its provenance:

The source content model (so it can be regenerated).
The template version used.
The validation result (structure passed; render checked or unavailable).
Any known deviations (fonts substituted, images downscaled, layout drift).

Exit conditions

The task is complete when the artifact exists, passes structural validation (and the render check when a renderer is available), and the content matches the agreed scope. Stop after delivering the validated artifact with its provenance; do not keep iterating on layout without a new scope instruction.

Scripts

All scripts live in scripts/ relative to this skill's directory and follow cli-builder conventions: --json for machine output, non-interactive, errors to stderr. Run with --help for full flag details.

validate-documents.py — Structural Sanity + Render Check

python3 scripts/validate-documents.py report.pdf            # human report
python3 scripts/validate-documents.py --json report.pdf    # machine report
python3 scripts/validate-documents.py --render-check --json report.pdf data.xlsx deck.pptx

Behavior:

Structural sanity per format: PDF header/EOF/page objects; OOXML ZIP container, [Content_Types].xml, required parts, XML well-formedness. Legacy .doc/.xls/.ppt files are recognized via OLE2 magic bytes.
Render check (--render-check): renders PDF via pdftoppm/mutool/gs and Office formats via LibreOffice. Reports unavailable — exit 0 — when no renderer is installed (graceful degradation, never a crash).
Exit codes: 0 all pass (or render check unavailable); 1 a file fails structure or rendering; 2 usage/I/O error.
JSON output: top-level status (ok / fail / unavailable / error) with per-file checks and render results.

epub — ebook container skill; the sibling family-skill precedent for this format family.
data-engineering — data pipelines and transformation; Excel is a deliverable format here, not a data store.
cli-builder — the CLI conventions the validation script follows (--json, non-interactive, exit codes).

8.9 KiB Raw Blame History