CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

markdown-authoring

Author high-quality Markdown documentation with deterministic structure, lint compliance, and CI integration. Use when writing README files, creating docs pages, fixing markdownlint failures, defining style rules, or wiring markdown checks into pre-commit and pipelines. Keywords: markdown, markdownlint, readme, docs, headings, lists, code fences, links, images, lint config, ci, documentation style.

Quality

86%

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

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 body is well structured with excellent progressive disclosure, a validated lint-fix workflow, and copy-paste-ready commands. Its main weakness is the Anti-Patterns section, which over-explains basic Markdown conventions Claude already knows in a padded format.

Suggestions

Trim the Anti-Patterns section: drop the WHY/Consequence scaffolding and keep only the rule plus the BAD/GOOD contrast for the genuinely repo-specific rules; delete or move the stray 'Consider adding a table of contents' paragraph, which restates knowledge Claude already has.

Make workflow step 2 concrete by naming the reference for each document type, e.g. 'README → docs-readme.md, API doc → docs-api.md, changelog → docs-changelog.md', so the mapping is executable without guessing.

Cut redundancy between the lint-loop prose in step 4 and the 'lint-fix loop' bullet beneath it — one statement of the loop is sufficient.

DimensionReasoningScore

Conciseness

Quick Commands and the workflow are lean, but the Anti-Patterns section re-explains basic Markdown knowledge Claude already has (typed code fences, sequential heading levels, consistent list markers), each padded with WHY/BAD/GOOD/Consequence blocks, plus a stray 'Consider adding a table of contents' paragraph — more than the minor trims allowed by the 4 anchor.

3 / 5

Actionability

Commands are concrete and copy-paste ready with expected results ('rumdl check .', 'bunx @biomejs/biome check .', './scripts/read-reference.sh syntax-headings'), but step 2 of the workflow ('Apply template and section order from references') does not specify which reference maps to which document type, leaving a minor gap to full executability.

4 / 5

Workflow Clarity

The Deterministic Workflow gives a clear 5-step sequence with an explicit validation feedback loop ('identify the specific rule, fix the source content... then re-lint. Do not proceed until lint is clean') — matching the 5 anchor's validate-fix-retry pattern with a hard gate.

5 / 5

Progressive Disclosure

The 139-line SKILL.md is a genuine overview: bulk detail (77–589 lines per file) is split into 16 real, one-level-deep reference files with clearly labeled links, organized by prefix (Syntax/Docs/Lint), plus a reader script — matching the 5 anchor's well-signaled, easy-to-navigate structure.

5 / 5

Total

17

/

20

Passed

Description

87%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 that explicitly states capabilities and trigger conditions with an effective keyword list. Its only weaknesses are slight fluff ('high-quality', 'deterministic structure') and a keyword list missing a few natural variations like the '.md' extension.

DimensionReasoningScore

Specificity

Lists several concrete actions ('writing README files, creating docs pages, fixing markdownlint failures, defining style rules, or wiring markdown checks into pre-commit and pipelines') with only minor coverage gaps, but 'high-quality' and 'deterministic structure' are mild fluff, keeping it below the comprehensive-and-clean 5 anchor.

4 / 5

Completeness

Clearly answers both 'what' ('Author high-quality Markdown documentation with... lint compliance, and CI integration') and 'when' with an explicit 'Use when writing README files, creating docs pages, fixing markdownlint failures...' clause containing concrete trigger phrases — a direct match to the 5 anchor.

5 / 5

Trigger Term Quality

The keyword list ('markdown, markdownlint, readme, docs, headings, lists, code fences, links, images, lint config, ci, documentation style') plus natural 'Use when' phrases gives good coverage, but common variations like the '.md' file extension and synonyms such as 'md' or 'linting' are missing, so it falls just short of the 5 anchor.

4 / 5

Distinctiveness Conflict Risk

The niche is clearly Markdown authoring with distinct triggers (markdownlint, readme, code fences, markdown checks in pre-commit); 'docs' and 'documentation style' are broad enough to touch generic documentation skills, but the specific triggers keep conflict risk minimal.

5 / 5

Total

18

/

20

Passed

Validation

100%

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

pantheon-org/tekhne

Path

skills/documentation/markdown-authoring/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.