CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

markdown-html-orchestrator

Use when a user wants to convert any markdown file in their Claude project into a single-file, lightly-interactive HTML — long-form documents (specs, plans, RFCs, reports, explainers), code reviews with diffs and severity-tagged annotations, or slide decks. Triggers on "convert this markdown to HTML", "make this an HTML file", "turn this into an interactive document", "render this report as HTML", "PR writeup as HTML", "slides from this markdown". Forks context to route to one of three converter sub-skills (md-document, md-review, md-slides) based on a deterministic doctype classifier, after the user has run the design-system onboarding once. Refuses if input is under 100 lines (per Shihipar — markdown still wins below the threshold) or design-system isn't onboarded. Distinct from Anthropic's official Playground plugin (which is interactive prompt-tuning controls with sliders/knobs/prompt-copy-back) and from marketing/landing/ (which is a landing-page generator).

69

Quality

87%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

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.

A strong, disciplined orchestrator body: deterministic routing with a concrete signal table, runnable script invocations, explicit refusal gates, and an anti-pattern checklist. The two real weaknesses are that the bundled `references/*.md` files are never surfaced from the body (a navigation dead-end) and that the workflow stops at handoff without any output-verification step.

Suggestions

Link the three bundled reference files (e.g., under References: routing patterns → references/orchestrator_routing_patterns.md, density canon → references/information_density_canon.md, single-file rules → references/single_file_html_discipline.md) so they are discoverable from SKILL.md, and move the forcing-question library's detail there if it grows.

Add a Step 6 verification checkpoint (confirm the output HTML exists, is single-file, and renders) with an error-recovery branch, closing the workflow's only validation gap.

Trim assumed-knowledge padding — the Shihipar essay recap, per-question 'Canon:' citations, and the 'Distinct from' section that duplicates the description — and rewrite script paths relative to the bundle (scripts/doctype_classifier.py) so the commands are copy-paste runnable from this skill's location.

DimensionReasoningScore

Conciseness

Mostly lean: dense signal tables, tight workflow steps, and terse anti-pattern bullets ("Single file or nothing — that's the whole point") — most tokens earn their place. But there is trimmable material Claude doesn't need: the opening essay recap ("Thariq Shihipar's argument ... markdown collapses past 100 lines"), "Canon:" citations to Tufte/Matt Pocock/research-ops sprinkled through the forcing-question library, and a Distinct-from section that restates the frontmatter description. Matches 'efficient; minor instances of over-explanation that could be trimmed' rather than 5, and clearly above 3 since the padding is incidental, not structural.

4 / 5

Actionability

Executable commands with flags are given for every script stage: the classifier→router pipeline invocation, `onboard.py`, and `output_path_resolver.py --input <path>.md --doctype <document|review|slides>` with collision flags (`--on-collision timestamp`), plus a concrete signal table with regex-level content signals. Minor gaps keep it at 4 rather than 5: Step 5's handoff is directional ("forward the original markdown + the design-system config into the named sub-skill's renderer") with no concrete invocation, and script paths are written against a repo layout (`markdown-html/skills/...`) rather than this bundle's `scripts/`. Clearly above 3 — the guidance is real and runnable, not pseudocode.

4 / 5

Workflow Clarity

Steps 1–5 are clearly sequenced with checkpoints at the front (three hard pre-flight refusal gates) and mid-flight ("Inspect the verdict", branch on ROUTE_SILENTLY / ASK_USER / REFUSE, collision handling defaults). The operation is non-destructive by design (suffix-on-collision, overwrite opt-in), so the destructive-cap doesn't apply. Not 5 because there is no post-render verification or error-recovery loop (nothing says what to do if the renderer fails or the HTML is broken), which the anchor-5 example includes; comfortably above 3 since validation is explicit at intake, not implicit.

4 / 5

Progressive Disclosure

The body is well-sectioned and points to the bundle's three scripts, but scored against the actual bundle structure: the three files in `references/` (information_density_canon.md, orchestrator_routing_patterns.md, single_file_html_discipline.md) are never linked or mentioned anywhere in the body — the "References" section cites external essays and other repos instead — so those files are undiscoverable from SKILL.md. Content that could live in those files (the forcing-question library, the density rationale) is also inlined. This fits 'references present but not clearly signaled; content that should be separate is inline' better than the anchor-4 'minor organization gaps', since three whole bundle files being orphaned is not minor.

3 / 5

Total

15

/

20

Passed

Description

100%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.

A model description: concrete capabilities, six natural trigger phrases, explicit refusal boundaries, and explicit disambiguation from adjacent tools. The only cost is length — the parenthetical Playground/landing explanations push verbosity, but no dimension is diluted by it. Third-person voice is used throughout.

DimensionReasoningScore

Specificity

Lists multiple concrete actions with comprehensive coverage: "convert any markdown file ... into a single-file, lightly-interactive HTML — long-form documents (specs, plans, RFCs, reports, explainers), code reviews with diffs and severity-tagged annotations, or slide decks", plus concrete routing behavior ("route to one of three converter sub-skills (md-document, md-review, md-slides) based on a deterministic doctype classifier") and refusal conditions. Not score 4 because coverage has no real gaps — the three doc families, the routing mechanism, and the preconditions are all named; not below 5 because no anchor phrase is vague or abstract.

5 / 5

Completeness

Both halves are explicit and concrete: 'what' is stated in the first sentence (convert markdown into single-file lightly-interactive HTML) and elaborated with the sub-skill routing; 'when' is given twice — "Use when a user wants to convert any markdown file..." and "Triggers on [six quoted phrases]". This matches the anchor 'clearly and explicitly answers both what AND when with concrete trigger phrases'. Not 4 because the 'when' is not merely present but enumerated with verbatim user phrasings.

5 / 5

Trigger Term Quality

Explicit natural trigger phrases span the space a user would actually say: "convert this markdown to HTML", "make this an HTML file", "turn this into an interactive document", "render this report as HTML", "PR writeup as HTML", "slides from this markdown". These are synonyms-level variations across all three doc types, matching the comprehensive-synonyms anchor. Not 4, because the phrase set is broader than 'a few natural terms missing' — the main missing variation (file extensions like .md/.html) is marginal for this domain.

5 / 5

Distinctiveness Conflict Risk

The niche is narrow (existing markdown ≥ 100 lines → single-file HTML) and it actively disambiguates the two nearest neighbors: "Distinct from Anthropic's official Playground plugin (which is interactive prompt-tuning controls with sliders/knobs/prompt-copy-back) and from marketing/landing/ (which is a landing-page generator)". Not 4: the overlap risks are not just minor but explicitly addressed, leaving minimal wrong-skill trigger risk.

5 / 5

Total

20

/

20

Passed

Validation

87%

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

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_field

'metadata' should map string keys to string values

Warning

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

14

/

16

Passed

Repository

alirezarezvani/claude-skills

Path

markdown-html/skills/markdown-html-orchestrator/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.