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.

1.00x

Quality

81%

Does it follow best practices?

Impact

97%

1.00x

Average score across 7 eval scenarios

Securityby

Passed

No findings from the security scan

Quality

Content

78%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 skill body: an overview with executable quick commands, explicit lint feedback loops, and an exemplary one-level-deep reference layout backed by a real bundle. Weakest spots are repo-specific or nonexistent script paths in the commands, a vague final workflow step, and a few sections of trimming candidates.

Suggestions

Replace repo-specific and unverifiable commands ('sh skills/agentic-harness/skill-quality-auditor/scripts/evaluate.sh ...', 'bun run check-style ...') with portable equivalents, or document the exact preconditions for those paths.

Give workflow step 5 a concrete validation command (e.g. the actual pre-commit or CI check invocation) instead of the vague 'Validate CI/pre-commit integration for regression prevention'.

Trim the abstract 'Principles' section and move the 'Consider adding a table of contents...' paragraph out of the Anti-Patterns block into a style reference file to reduce token cost.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes Claude's competence (no explanation of what Markdown or linting is), but the abstract 'Principles' list, the 'Consider' paragraph awkwardly placed inside Anti-Patterns, and the self-referential 'Evaluate this skill quality' command are tokens that could be trimmed, matching anchor 4 rather than a fully lean 5.	4 / 5
Actionability	Quick Commands are copy-paste ready with expected results ('bunx markdownlint-cli2 "*/.md"') and anti-patterns include concrete BAD/GOOD pairs, but several commands reference repo-specific paths ('sh skills/agentic-harness/...', 'skills/documentation/...') and 'bun run check-style' invokes a script that does not exist in the bundle — minor gaps placing this at anchor 4.	4 / 5
Workflow Clarity	The Deterministic Workflow has a clear sequence with an explicit lint-fix feedback loop ('lint fails → identify rule → fix source or add justified exception → re-lint → proceed only when clean') and a 'Do not proceed until lint is clean' checkpoint, but step 5 ('Validate CI/pre-commit integration for regression prevention') lacks any concrete check or command — a minor validation gap that fits anchor 4 better than 5.	4 / 5
Progressive Disclosure	Verified against the actual bundle: all 16 reference links ('references/syntax-headings.md' through 'references/lint-api.md') point to real files exactly one level deep, grouped into clear syntax/docs/lint categories, supplemented by a working './scripts/read-reference.sh' navigation script, with no bulk detail inlined in SKILL.md — a clear match for anchor 5.	5 / 5
	Total	17 / 20 Passed

Description

83%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 with an explicit 'Use when...' clause covering concrete triggers and a solid keyword list. Its main gaps are a couple of abstract buzzword phrases and the absence of common synonyms/file extensions (e.g. '.md') in the trigger terms.

Dimension	Reasoning	Score
Specificity	The description lists several concrete actions ('fixing markdownlint failures, defining style rules, or wiring markdown checks into pre-commit and pipelines') alongside the domain, but phrases like 'deterministic structure' and 'high-quality' add mild abstraction, so it sits at anchor 4 rather than a fully comprehensive 5.	4 / 5
Completeness	It explicitly answers both 'what' ('Author high-quality Markdown documentation with deterministic structure, lint compliance, and CI integration') and 'when' with concrete trigger phrases ('Use when writing README files, creating docs pages, fixing markdownlint failures...'), matching the anchor-5 example pattern exactly.	5 / 5
Trigger Term Quality	The keyword list ('markdown, markdownlint, readme, docs, headings, lists, code fences, links, images, lint config, ci') gives good coverage of natural user terms, but misses common synonyms and file extensions like '.md' or 'MD rules', which the anchor-5 example requires.	4 / 5
Distinctiveness Conflict Risk	Markdown lint/CI authoring is a clear niche with distinct triggers (markdownlint, code fences, readme), but the broad terms 'docs' and 'documentation style' create minor overlap risk with general writing or documentation skills, placing it at anchor 4 rather than 5.	4 / 5
	Total	17 / 20 Passed

Validation

100%

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

Validation for skill structure

No warnings or errors.

Repository: pantheon-org/tekhne
Path: skills/documentation/markdown-authoring/SKILL.md
Commit: a1083f4

Reviewed: 2 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.