Skip to content

Add plugin document-skills - #12

Closed
Hylouis233 wants to merge 34 commits into
hetaoBackend:mainfrom
Hylouis233:plugin/document-skills
Closed

Add plugin document-skills#12
Hylouis233 wants to merge 34 commits into
hetaoBackend:mainfrom
Hylouis233:plugin/document-skills

Conversation

@Hylouis233

Copy link
Copy Markdown
Contributor

What changes

New Plugin Hylouis233/document-skills - a Skill-only portable Agent Plugin bundling four original
workbench Skills: docx, pdf, pptx, xlsx.

All guidance in this Plugin was written originally for this contribution. It contains no content
from Anthropic's document skills or any other proprietary skill pack - the docx/pdf/pptx/xlsx
names describe the formats, and the patterns are built around standard open-source Python
libraries (python-docx, python-pptx, openpyxl, pypdf, ReportLab, PyMuPDF) and public format
knowledge.

User value

Users ask agents for document deliverables and get silent corruption: hand-edited ZIP XML that
no viewer opens, pasted values where spreadsheet formulas belong, screenshot-style PDFs with no
extractable text, decks whose text overflows every slide. The four Skills route each task to the
right tool, enforce the container contracts, and - critically - require re-opening and verifying
the artifact before handing it back.

Example prompt:

Use the document-skills plugin: open sales-2024.xlsx, add a sheet "Summary" with per-region
totals computed by formula, a bar chart of the top 5 products, and currency formatting.

Expected result: the agent loads the workbook with openpyxl, inspects sheets and headers, writes
real SUMIF/COUNTIF formulas, adds a native BarChart, applies number formats, and reports
the changed ranges plus the verification it ran.

Use the document-skills plugin: create a PDF one-pager "Q3 launch checklist" that fits exactly
one A4 page.

Expected result: generated with ReportLab flowables, measured, and verified with pypdf to be
exactly 1 page with extractable text.

Skill inventory (4 Skills, 13 reference files, 1333 lines):

  • docx - create (python-docx outline + styles + TOC field), edit (two-tier: structural edits
    vs. safe OOXML surgery), read (pandoc / python-docx), review (symptom-driven repair table),
    mandatory postcheck with optional soffice PDF smoke test.
  • pdf - one-tool-per-job routing: ReportLab for creation, PyMuPDF for extraction/inspection,
    pypdf for split/merge/rotate/watermark/encrypt/forms; text-first rule; page-geometry and
    overflow checks in postcheck.
  • pptx - seven workhorse slide patterns, narrow in-place editing with asserted shape matching,
    real chart parts over chart pictures, text-fit rules, slide-count and render verification.
  • xlsx - formulas-are-formulas contract, data_only caveats, typed values with explicit
    number formats, native charts bound to ranges, structural-edit formula audit, CSV/TSV route
    with a messy-data cleanup contract.

Plugin submission checklist

  • Plugin lives at plugins/<github-owner>/<plugin-name>.
  • plugin.json name matches the Plugin directory.
  • README.md includes a real example prompt and expected result.
  • LICENSE and plugin.json declare an open-source license (Apache-2.0).
  • Required executables, accounts, paid services, and supported platforms are disclosed
    (Python 3.9+ and the six libraries; optional LibreOffice/pandoc; Windows/macOS/Linux).
  • Network destinations and data handled by the plugin are disclosed (none - fully local).
  • No credentials, private endpoints, hidden telemetry, installers, symlinks, or native
    binaries are included.
  • Every scaffold TODO has been replaced.
  • Repository validation and portable contract tests pass (see evidence).

Network and data behavior

No network access, no credentials, no bundled executables. The Skills instruct the agent to use
the user's own installed Python libraries and operate only on files the user points at; temporary
artifacts go to the system temp directory. soffice/pandoc render checks are optional and
degrade gracefully when absent.

Evidence

npm run validate
OK   example hello-mcode
OK   example hello-mcode-mcp
OK   plugin Hylouis233/document-skills
Validated 1 hosted Plugin and all examples.

node --test
# tests 12
# pass 11
# fail 1

The one failing test (contributor can scaffold a hosted Skill plugin with one command,
test/hosted-plugins.test.mjs) is a pre-existing failure on unmodified main: the test asserts
a POSIX path separator while path.relative returns plugins\alice\hello-world on Windows.
Verified on a pristine shallow clone of this repository's main - same single failure, all
other 11 tests pass. No repository file outside plugins/Hylouis233/document-skills is touched
by this PR.

Manual evidence - the documented patterns were executed end to end on Windows (Python 3.13,
python-docx 1.2.0, python-pptx 1.0.2, openpyxl 3.1.5, pypdf 6.9.2, reportlab 4.4.10,
pymupdf 1.27.2, LibreOffice present):

XLSX ok | sheets: ['Sales'] | dims: A1:E5 | formulas: 4 [('E2','=C2*D2') ...] + native BarChart
DOCX ok | paragraphs: 3 | tables: 1 | table rows: 2 | PAGE field footer
PPTX ok | slides: 3 | title/table/chart slides rendered
PDF  ok | pages: 1 | mediabox: 595.3 x 841.9 | title text extractable
soffice report.docx -> exit 0 | pdf made: True
soffice deck.pptx    -> exit 0 | pdf made: True   (deck.pdf pages: 3 = slide count)

Every Python snippet embedded in the Skills was also parsed with ast.parse - zero syntax
errors. Staged files verified UTF-8 without BOM, LF line endings.

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants