pdf-markdown-validator

Validate PDF to Markdown conversion quality using multi-dimensional metrics. Assess table accuracy, style preservation (bold/italic/headings), robustness, and performance with standardized F1-scoring methodology.

Quality

66%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Medium

Suggest reviewing before use

Fix and improve this skill with Tessl

tessl review fix ./.github/skills/pdf-markdown-validator/SKILL.md

Quality

Content

63%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 content is highly actionable with concrete executable commands and a clear validation workflow, but it is over-long for a single file and would benefit from splitting reference material into separate bundle files and trimming redundant sections.

Suggestions

Move the Ground-Truth Annotation Format, Metric Definitions & Examples, and Troubleshooting sections into separate reference files (e.g. references/annotation-format.md, references/metrics.md) and link to them one level deep.

Trim or remove the Summary and Best Practices sections, which restate content already covered in Core concepts and the Workflow.

Resolve the 'pdf_validator' Python module references — either add the module to the bundle or replace those examples with the actual CLI script invocations that exist.

Dimension	Reasoning	Score
Conciseness	The 725-line body is mostly efficient for a complex skill but includes padded/redundant sections — the Summary, Best Practices, and Capabilities blocks restate material already covered in Core concepts and the Workflow — that could be tightened.	3 / 5
Actionability	Provides concrete, copy-paste-ready bash, Python, and YAML commands referencing real bundle scripts (validate.py, analyze_failures.py, compare_runs.py), with a minor gap: the Python API examples import 'pdf_validator' / 'BaseMetric', which are not present in the bundle.	4 / 5
Workflow Clarity	The 'Workflow: Running a Full Validation' gives a clear 5-step sequence with a validate→fix→re-run feedback loop (Step 5) and an explicit CI gate (--ci-mode --fail-below 75); validation is present for this batch operation, so no cap applies, though the main workflow's checkpoint phrasing could be more explicit.	4 / 5
Progressive Disclosure	The scripts bundle is referenced inline appropriately, but the SKILL.md is a 725-line monolith with large blocks (annotation format, metric examples, troubleshooting, best practices) inlined that would be better split into one-level-deep reference files; the only external references point to repo paths rather than bundle files.	3 / 5
	Total	14 / 20 Passed

Description

70%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 specific and distinctive, clearly conveying what the skill does with concrete metric dimensions. Its main weakness is the absence of an explicit 'when to use' trigger clause, which limits completeness.

Suggestions

Append an explicit trigger clause, e.g. 'Use when validating or benchmarking PDF→Markdown conversion quality, comparing converters, or enforcing quality gates in CI/CD.'

Add natural trigger terms and file extensions users would say, such as '.pdf', '.md', 'convert PDF to Markdown', and 'benchmark'.

Mention core capabilities from the body (comparing conversion approaches, generating reports) so the description fully reflects the skill's scope.

Dimension	Reasoning	Score
Specificity	Names the domain and several concrete actions ('Validate PDF to Markdown conversion quality', 'Assess table accuracy, style preservation (bold/italic/headings), robustness, and performance', 'F1-scoring methodology'), but omits core capabilities surfaced in the body such as comparing approaches and generating reports.	4 / 5
Completeness	The 'what' is clear and concrete, but there is no 'Use when...' clause or equivalent explicit trigger guidance for when Claude should invoke the skill, which caps completeness at 3 per the rubric guideline.	3 / 5
Trigger Term Quality	Includes natural terms a user would say ('PDF to Markdown conversion', 'table accuracy', 'style preservation', 'F1-scoring'), but misses common variations and file extensions like '.pdf', '.md', or 'convert PDFs'.	4 / 5
Distinctiveness Conflict Risk	The niche is sharply defined — standardized F1-scored validation of PDF→Markdown conversions — making it clearly distinguishable from other skills with minimal conflict risk.	5 / 5
	Total	16 / 20 Passed

Validation

81%

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 — 13 / 16 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (725 lines); consider splitting into references/ and linking	Warning
metadata_version	'metadata.version' is missing	Warning
metadata_field	'metadata' should map string keys to string values	Warning

	Total	13 / 16 Passed

Repository: raphaelmansuy/edgequake
Path: .github/skills/pdf-markdown-validator/SKILL.md
Commit: 4904960

Reviewed: about 20 hours 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.