document-converter

Use for reading, analyzing, summarizing, and converting complex documents into Markdown artifacts or other supported document formats.

Quality

66%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./backend/super-magic/agents/skills/document-converter/SKILL.md

Quality

Content

71%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is highly actionable with comprehensive, executable code examples and clearly sequenced workflows backed by per-file verification for batch operations. Its main weaknesses are repetition that bloats the token budget and a monolithic single-file structure with no progressive disclosure to bundle reference files.

Suggestions

Factor the repeated `document_output_dir` helper into a single defined-once snippet (or a scripts/ helper) and reference it from each example to remove ~24 lines of duplication.

De-duplicate the output_dir naming rule — state it once in Code Mode Use and reference it from Batch Conversion Rules and the export tool entry instead of restating it.

Move the full Tools API reference and/or the catalog of code examples into references/ files (e.g. TOOLS.md, EXAMPLES.md) with one-level-deep links from SKILL.md to improve progressive disclosure.

Dimension	Reasoning	Score
Conciseness	The body is operational with no basic-concept padding, but the `document_output_dir` helper is repeated verbatim across three examples and the output_dir naming rule is restated three times, so it is 'mostly efficient but could be tightened.'	3 / 5
Actionability	Copy-paste-ready `run_sdk_snippet` examples with real `tool.call` invocations, concrete parameters, and `result.ok` checks cover all common cases (sample+plan, extract range, image understanding, export, batch export, summarize, convert, convert-then-export), matching 'fully executable; copy-paste ready; covers the common cases.'	5 / 5
Workflow Clarity	Clear numbered sequences (Default Approach 1–8, Summary 1–7) with checkpoints, and batch ops include verification (record ok/error per file, count success from actual results) so the batch cap does not trigger; however examples `raise SystemExit` on failure rather than offering a validate→fix→retry loop, leaving 'minor validation gaps.'	4 / 5
Progressive Disclosure	No bundle files exist and the ~490-line body inlines a full Tools API reference (~120 lines) plus eight code examples that could be split into separate reference files; it is well-sectioned but 'content that should be separate is inline', and the under-50-line simple-skill exception does not apply.	3 / 5
	Total	15 / 20 Passed

Description

62%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is concise and frames a clear niche (document → Markdown/format conversion) with a usable 'Use for' trigger, but it relies on generic action verbs and omits the concrete file-type triggers (PDF, .docx, etc.) that best drive activation. Rewording in third person and adding explicit user-say trigger phrases would lift completeness and trigger-term quality.

Suggestions

Rewrite in third person and lead with capabilities, e.g. 'Reads, analyzes, summarizes, and converts complex documents into Markdown artifacts or other supported formats. Use when the user asks to read, summarize, analyze, or convert PDF, Word, PowerPoint, or spreadsheet files.'

Add concrete trigger terms and extensions users actually say — PDF, .pdf, Word/.docx, PowerPoint/.pptx, Excel/.xlsx, spreadsheet, slide deck — to improve trigger-term quality and distinctiveness.

Make the 'when' explicit with a 'Use when the user mentions…' clause naming common phrasings ('summarize this PDF', 'convert this docx to Markdown').

Dimension	Reasoning	Score
Specificity	The description lists four actions ('reading, analyzing, summarizing, and converting') plus output formats (base 4, 'several specific actions; minor gaps'), but the imperative 'Use for…' voice is second-person rather than third person, so the rubric's voice penalty reduces specificity by 1.	3 / 5
Completeness	'Use for reading, analyzing, summarizing, and converting complex documents…' supplies both the what (actions/outputs) and a when ('Use for'), but the when lacks concrete user-mention trigger phrases, so it is 'both what and when; when could be more explicit or specific' rather than a 5.	4 / 5
Trigger Term Quality	Natural verbs (read, analyze, summarize, convert) and 'Markdown'/'documents' are present, but the concrete file-type trigger terms users actually say (PDF, .docx, .pptx, spreadsheet, Word) are missing, leaving only 'some relevant keywords but missing common variations or synonyms.'	3 / 5
Distinctiveness Conflict Risk	The Markdown-artifact / document-format conversion niche is fairly distinct, but 'complex documents' is broad enough to create minor overlap risk with closely related document skills, fitting 'mostly distinct; minor overlap risk.'	4 / 5
	Total	14 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: dtyq/magic
Path: backend/super-magic/agents/skills/document-converter/SKILL.md
Commit: f9973c5

Reviewed: 2 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.