CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

md-document

Converts long-form markdown (specs, RFCs, reports, plans, explainers) into a single-file, lightly-interactive HTML document with sticky TOC, scrollspy, search filter, code-copy buttons, and design-system-driven brand tokens. Triggers when the markdown-html-orchestrator classifies an input as DOCUMENT, or when invoked directly via /cs-md-document. Reads the design-system config via config_loader.py and inlines the user's 12 derived CSS custom properties; refuses to render if onboarding hasn't run. Single-file output — Google Fonts + Prism.js CDN are the only externals; no framework runtime, no build step. Use after orchestrator routing or after design-system onboarding is confirmed.

63

Quality

79%

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

Fix and improve this skill with Tessl

tessl review fix ./.gemini/skills/md-document/SKILL.md

The canonical home for this skill is md-document in alirezarezvani/claude-skills

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 well-structured, executable skill body: an unambiguous three-command pipeline, explicit refusal gates, clear scope boundaries, and sharp differentiation from sibling converters. The main weaknesses are dangling references — both the citations pointer and all script paths point to files absent from the bundle — and the absence of an executable command for the onboarding check and a post-render verification step.

Suggestions

Ship the referenced files or fix the pointers: 'See references/ for full citations' and the 'markdown-html/skills/md-document/scripts/*.py' paths resolve to nothing in this bundle — either include those files or reference scripts relative to the skill (e.g., 'scripts/markdown_parser.py').

Add an executable command for the onboarding gate, e.g. 'python3 scripts/config_loader.py --check' or equivalent, so the refusal rule in hard rule 2 is directly actionable.

Add a post-render validation step to the pipeline, such as verifying document.html exists and contains the injected interactivity marker, with a fix-and-retry loop if a step fails.

DimensionReasoningScore

Conciseness

The body is dense and information-rich — symptom/action table, exact pipeline commands, explicit scope boundaries, and smoke-tested behavior claims — with no explanations of concepts Claude already knows. Minor trimmable material: the 'Canon:' attributions in the forcing-question library and the References section partially duplicate in-body citations. This fits 'efficient; minor instances that could be trimmed' (4) rather than the every-token-earns-its-place level 5.

4 / 5

Actionability

The three-step pipeline is given as full, copy-paste-ready bash commands with flags, plus an all-in-one alternative, and the output artifact naming is specified. Two minor gaps keep it below level 5: hard rule 2 gates rendering on 'config_loader.setup_completed() must return True' but provides no executable command to check it, and design_style variants are described without showing how to select one.

4 / 5

Workflow Clarity

The pipeline is clearly sequenced (numbered steps, one command each) and includes pre-flight validation gates — the <100-line refusal and the onboarding check. It is not a destructive/batch operation, so no cap applies. It falls short of level 5 because there is no explicit post-render validation step (e.g., verifying document.html was produced or spot-checking anchors/TOC) and no error-recovery loop if a step fails.

4 / 5

Progressive Disclosure

Sections are well organized and one level deep, but scored against the actual bundle structure: 'See references/ for full citations' and every pipeline command path ('markdown-html/skills/md-document/scripts/*.py') point to files that do not exist in this bundle — there are no references/, scripts/, or assets/ directories. Navigation fails at the reference step, fitting the 'references present but not reliably usable / could be better organized' level 3 rather than level 4's 'references mostly clear'.

3 / 5

Total

15

/

20

Passed

Description

80%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 strong description: concrete, specific, and honest about constraints (single-file output, CDN-only externals, refusal gates), written in third person with an explicit trigger clause. Its main weakness is that the 'when' guidance is oriented toward internal orchestrator routing and a slash command rather than natural user phrasing, and it lacks common synonyms/file extensions like '.md' or 'docs'.

Suggestions

Add a natural user-language trigger clause, e.g. 'Use when the user asks to convert a spec, RFC, report, plan, or other long-form markdown document (.md) to HTML'.

Include common synonyms and the file extension ('.md', 'docs', 'documentation') among the trigger terms to round out keyword coverage.

DimensionReasoningScore

Specificity

The description lists multiple concrete actions with comprehensive coverage: 'Converts long-form markdown (specs, RFCs, reports, plans, explainers) into a single-file, lightly-interactive HTML document with sticky TOC, scrollspy, search filter, code-copy buttons' plus 'inlines the user's 12 derived CSS custom properties'. It uses third-person voice throughout, so no voice penalty applies. This matches the level-5 anchor; level 4 ('several specific actions; minor gaps') understates the coverage of input types and output features.

5 / 5

Completeness

Both 'what' and 'when' are explicitly present: 'Triggers when the markdown-html-orchestrator classifies an input as DOCUMENT, or when invoked directly via /cs:md-document' plus 'Use after orchestrator routing or after design-system onboarding is confirmed'. However, the 'when' is framed around internal orchestrator routing and a slash command rather than concrete user-language trigger phrases (e.g., 'when the user asks to convert a spec or report to HTML'), so it fits the level-4 anchor where the 'when' could be more specific.

4 / 5

Trigger Term Quality

Good natural keyword coverage — 'specs, RFCs, reports, plans, explainers', 'markdown', 'HTML', 'convert' — phrased as a user would say them. It falls short of the level-5 anchor, which requires synonyms and file extensions: no '.md', 'documentation', or 'docs' appear.

4 / 5

Distinctiveness Conflict Risk

The niche is clear (long-form markdown documents to single-file HTML), but sibling converters in the same family (md-review, md-slides) accept the same markdown input, and the description alone does not disambiguate them — routing relies on the orchestrator. This is 'mostly distinct; minor overlap risk with closely related skills' (4) rather than the minimal-conflict level-5 anchor.

4 / 5

Total

17

/

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

frontmatter_unknown_keys

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

Warning

relative_links

Relative link issues: 2 missing

Warning

Total

14

/

16

Passed

Repository

alirezarezvani/claude-skills

Path

.gemini/skills/md-document/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.