CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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

77%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Medium

Suggest reviewing before use

Fix and improve this skill with Tessl

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

Quality

Content

77%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 and the validation workflow is clearly sequenced with explicit feedback loops, with all commands verified against the actual bundle scripts. Its weaknesses are verbosity (duplicated quick-start content, re-explanations of Markdown and F1 basics) and a monolithic structure that inlines reference material instead of splitting it into bundled files.

Suggestions

Move the ground-truth annotation format spec, CLI command reference, and troubleshooting sections into reference files under references/ (e.g. references/gold-format.md, references/cli.md) and link to them from a leaner SKILL.md.

Remove duplication: collapse the Quick start and the five-step Workflow into one pipeline presentation, and delete the Summary section that restates "When to use".

Trim explanations of concepts Claude already knows — basic Markdown syntax (bold/italic/heading forms, pipe alignment) and the precision/recall/F1 harmonic-mean definitions — keeping only the project-specific thresholds and formulas.

DimensionReasoningScore

Conciseness

Most of the ~720-line body is project-specific knowledge Claude cannot know (metric weights, formulas, file paths, CLI flags), so much of it earns its place — but there are several trimmable sections: the Quick start and the Workflow section duplicate the same validate.py invocations, the Summary restates "When to use", and the gold-format section explains Markdown syntax basics ("Bold: **text**", "Pipes align properly") and precision/recall/F1 definitions Claude already knows. Not 2 because the padding is peripheral rather than the bulk of the document.

3 / 5

Actionability

The body is fully executable throughout: copy-paste-ready cargo and python3 commands with exact flags (verified against the bundled scripts/validate.py --pdf-dir/--gold-dir/--ci-mode and analyze_failures.py --group-by), a complete GitHub Actions YAML, a worked Python extension API, and concrete worked scoring examples for every metric. It matches the anchor for copy-paste ready commands covering the common cases.

5 / 5

Workflow Clarity

"Workflow: Running a Full Validation" gives five explicitly sequenced steps with commands, embeds validation checkpoints (step 3 runs the validator, --ci-mode/--fail-below 75 gates CI), and closes with an iterative feedback loop (identify low-scoring dimension → fix → re-run validation → record baseline), plus a troubleshooting section for error recovery. Not 4 because both the validation checkpoints and the fix-and-retry loop are explicit rather than implied.

5 / 5

Progressive Disclosure

Section structure is clear and the referenced scripts (scripts/validate.py, analyze_failures.py, compare_runs.py) all exist in the bundle and are invoked by path, but ~300+ lines of content that clearly belongs in separate reference files — the ground-truth annotation format spec, the full CLI reference, troubleshooting, and best practices — are inlined in a single 720-line SKILL.md with no references/ directory. This matches the anchor for content that should be separate being inline despite present structure; not 2 because headers make it navigable and real script references exist, and two bundled scripts (batch_drift.py, diff_analysis.py) are never surfaced for discovery.

3 / 5

Total

16

/

20

Passed

Description

71%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, third-person, and distinctive, naming all four metric dimensions and the F1-scoring methodology. Its main weakness is the absence of any explicit "Use when..." trigger guidance, which caps completeness and leaves natural trigger terms underdeveloped.

Suggestions

Append an explicit trigger clause, e.g. "Use when validating PDF-to-Markdown conversion output, benchmarking PDF extraction quality, or enforcing conversion quality gates in CI."

Add natural trigger variations users would actually say, such as ".pdf", "PDFs", "Markdown extraction", and "conversion quality", to broaden keyword coverage.

Clarify the "when" by distinguishing this validation skill from PDF extraction itself (e.g. "Use after converting PDFs to Markdown to score the output against ground truth").

DimensionReasoningScore

Specificity

"Validate PDF to Markdown conversion quality" and "Assess table accuracy, style preservation (bold/italic/headings), robustness, and performance" list multiple concrete actions that comprehensively cover the skill's four metric dimensions, matching the anchor for multiple specific concrete actions. Not 4 because coverage of the skill's capabilities is complete rather than having minor gaps.

5 / 5

Completeness

The description clearly answers "what" (validate conversion quality across four named metric dimensions) but there is no "Use when..." clause or equivalent explicit trigger guidance — the "when" is only weakly implied by the domain itself. Per the judging guideline, a missing explicit trigger clause caps completeness at 3, and it does not fall to 2 because the "what" is concrete and detailed.

3 / 5

Trigger Term Quality

"PDF to Markdown conversion", "table accuracy", "style preservation", "robustness", and "performance" are natural phrases a user would say, giving good keyword coverage. Not 5 because common variations and file extensions are missing (".pdf", "PDFs", "extraction", "pandoc"); not 3 because the terms present are specific and natural rather than generic.

4 / 5

Distinctiveness Conflict Risk

"Validate PDF to Markdown conversion quality using multi-dimensional metrics... F1-scoring methodology" carves out a clear validation/quality-metrics niche distinct from generic PDF extraction skills. Not 5 because bare trigger words like "PDF" and "Markdown" still overlap somewhat with PDF-extraction or Markdown-writing skills; not 3 because the F1-scoring validation framing is unmistakably specific.

4 / 5

Total

16

/

20

Passed

Validation

81%

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

CriteriaDescriptionResult

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

Reviewed

Table of Contents

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.