mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-20 16:16:25 +03:00
f37dc73829
* 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>
98 lines
5.2 KiB
Markdown
98 lines
5.2 KiB
Markdown
# Sources, provenance, and verification
|
||
|
||
## Upstream project
|
||
|
||
| Resource | URL / identifier |
|
||
| --- | --- |
|
||
| Repository | https://github.com/firecrawl/anydoc |
|
||
| npm package | `@firecrawl/anydoc` — https://www.npmjs.com/package/@firecrawl/anydoc |
|
||
| PyPI package | `firecrawl-anydoc` (imports as `anydoc`) — https://pypi.org/project/firecrawl-anydoc/ |
|
||
| crates.io crate | `anydoc` (same release train) |
|
||
| Browser demo (WASM) | https://firecrawl.github.io/anydoc/ |
|
||
| License | MIT |
|
||
|
||
## Access and verification dates
|
||
|
||
- Research and empirical verification performed **2026-08-05** and **2026-08-06**
|
||
on macOS (arm64) with Node v22.22.3, network access, and the pinned CLI
|
||
`npx -y @firecrawl/anydoc@0.1.6`.
|
||
- The pinned release **0.1.6** was published to npm at
|
||
**2026-08-05T18:29:40Z**; PyPI wheels for the same version were uploaded
|
||
**2026-08-05T18:29Z**. First release was 0.1.1 (2026-08-04).
|
||
|
||
## Fixture provenance
|
||
|
||
The committed fixtures under `fixtures/` come from two sources, both documented
|
||
here per the repository's attribution policy:
|
||
|
||
1. **The MIT-licensed upstream test suite.** Most fixtures were downloaded from
|
||
`https://github.com/firecrawl/anydoc/tree/main/tests/fixtures` (raw files
|
||
via `https://raw.githubusercontent.com/firecrawl/anydoc/main/tests/fixtures/...`).
|
||
They retain the upstream naming and structure:
|
||
- CSV: `fixture-handmade-quoted.csv`, `fixture-handmade-semicolon.csv`,
|
||
`fixture-handmade-utf16.csv`, `fixture-sheet.csv`
|
||
- DOCX: `fixture-handmade-numbering.docx`, `fixture-handmade-outline.docx`,
|
||
`fixture-handmade-rich.docx`, `fixture-handmade-tables.docx`
|
||
- Word legacy: `text.doc`; OpenDocument: `text.odt`, `sheet.ods`, `pres.odp`
|
||
- RTF: `text.rtf`; EPUB: `book.epub`
|
||
- PowerPoint: `pres.ppt`, `pres.pptx`; Excel: `sheet.xls`, `sheet.xlsx`,
|
||
`handmade-merged.xlsx`
|
||
- PDF: `fixture-text.pdf`
|
||
- Error cases from the upstream `*--errors.*` corpus:
|
||
`empty--errors.docx`, `encrypted--errors.odt`
|
||
2. **Generated samples** (created during research for cases the upstream suite
|
||
does not cover; deterministic, reproducible):
|
||
- `scanned-image-only.pdf` — a PDF with a single grayscale image and no
|
||
text layer, generated with Pillow, to exercise the no-OCR error path.
|
||
- `unsupported.xyz` — a small text file with an unsupported extension, to
|
||
exercise the unrecognized-content error path.
|
||
|
||
All fixtures are tiny (largest: `pres.ppt` at ~454 KB) and each is well under
|
||
the 5 MB repository limit. All committed copies are byte-identical to the
|
||
staged originals used during research (verified by sha256).
|
||
|
||
MIT license notice: the upstream anydoc project is MIT-licensed (Copyright
|
||
Firecrawl); the fixture files above are used under that license. The generated
|
||
samples carry no upstream copyright.
|
||
|
||
## Verification procedure
|
||
|
||
Every factual claim in this skill was confirmed against the **real pinned CLI**
|
||
(v0.1.6), not inferred from documentation:
|
||
|
||
1. **Environment warm-up**: `node --version` (v22.22.3 ≥ 20), then
|
||
`npx -y @firecrawl/anydoc@0.1.6 --version` → prints `0.1.6`; `--help` →
|
||
the verbatim help block reproduced in
|
||
[cli-reference.md](cli-reference.md).
|
||
2. **Positive conversions**: the pinned CLI was run on every committed fixture
|
||
with stdout and stderr captured separately and the exit code recorded. All
|
||
20 positive fixtures converted with exit 0 and empty stderr; the captured
|
||
markdown was compared against the output expectations documented in
|
||
[formats.md](formats.md) (headings, table rows, slide structure, footnote
|
||
definitions, CSV header promotion, UTF-16/delimiter handling, merged-cell
|
||
covered spans).
|
||
3. **Error paths**: each error fixture and each usage error was run with
|
||
stderr captured verbatim and the exit code recorded (1 for conversion/IO
|
||
failures, 2 for usage errors). The exact messages appear in
|
||
[errors.md](errors.md) character-for-character, including
|
||
`anydoc: unsupported input: PDF has no extractable text (Scanned, 1 pages): OCR is required`.
|
||
4. **Special behaviors**: `-o` overwrite and EISDIR, stdin via `-` with and
|
||
without `--format csv`, `--format=x` inline syntax, `--` end-of-options,
|
||
extension aliases (`--format xls`, `--format docm`), EPIPE (`| head` exits
|
||
0 with empty stderr), the stdin-is-a-terminal usage error (via a
|
||
pseudo-TTY), and resource limits (run on the upstream `zipbomb`/`imagebomb`
|
||
fixtures and on a generated 250 MB-entry archive — all exit 1 with the
|
||
documented `max_entry_bytes` prefix).
|
||
5. **First-run/offline**: a fresh empty npm cache was used to verify the
|
||
first-run download path (`env npm_config_cache=$(mktemp -d) npx -y
|
||
@firecrawl/anydoc@0.1.6 --version` → `0.1.6`, exit 0).
|
||
6. **Startup timing**: repeated warm invocations were timed
|
||
(`/usr/bin/time -p npx -y @firecrawl/anydoc@0.1.6 ...`) — ~0.32–0.35 s each,
|
||
consistent with the documented ~0.33–0.55 s warm-cache startup range.
|
||
|
||
Repository checks applied after authoring: frontmatter and structure
|
||
(`ruby scripts/validate-skills.rb`), skill quality (`ruby
|
||
scripts/validate-skill-quality.rb --base origin/main`), reference caps and link
|
||
resolution, eval-manifest validation (`scripts/validate-evals.py`), and no
|
||
machine-specific paths or credentials in any committed file.
|