run-documentation-examples

Extract Python examples from markdown docs and run them (including LLM examples). Use when validating documentation, after doc changes, or to verify all doc examples execute correctly.

1.51x

Quality

76%

Does it follow best practices?

Impact

100%

1.51x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.cursor/skills/run-documentation-examples/SKILL.md

Quality

Content

75%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 an efficient, actionable overview with executable commands, clear sections, and a genuine failure-recovery feedback loop for a batch operation. Scores are held at 4 across the board by minor issues: redundant invocation paths, a naming inconsistency, implicit validation, and an inlined rather than navigated bundle reference.

Suggestions

Reconcile the command naming inconsistency: pick one form (run_doc_examples vs run-doc-examples) and use it consistently in both the command block and the prose.

Collapse the three invocation variants (pytest, CLI, manual two-step) into a primary path plus a brief 'alternatives' note to tighten conciseness and clarify the canonical workflow.

Add an explicit verification checkpoint (e.g., 'confirm extracted_examples.py ran with 0 failures before considering docs validated') to make the validation step explicit and push workflow_clarity toward 5.

Dimension	Reasoning	Score
Conciseness	The body is lean and sectioned without over-explaining concepts Claude already knows, but presenting three alternative invocation paths (pytest, CLI, manual two-step) adds minor redundancy that keeps it just below the fully lean score-5 anchor.	4 / 5
Actionability	Commands are concrete and copy-paste ready ("pytest tests/test_doc_examples.py -v", the script path, manual two-step commands), but the inconsistent naming between "run_doc_examples" and "run-doc-examples" is a minor gap preventing a 5.	4 / 5
Workflow Clarity	The manual two-step workflow is clearly sequenced and the Failure Handling section provides a real retry-from-fail-index feedback loop, satisfying validation for this batch operation; it stays at 4 rather than 5 because validation is implicit (run == execute without error) and multiple parallel paths dilute the single canonical sequence.	4 / 5
Progressive Disclosure	Content is well-organized into clearly headed sections with a single one-level-deep bundle reference (scripts/run_documentation_examples.py, verified to exist), but the reference is inlined inside a workflow code block rather than surfaced in a dedicated navigation section, leaving it just below the score-5 anchor.	4 / 5
	Total	16 / 20 Passed

Description

78%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 strong: it explicitly covers both what the skill does and when to use it with concrete, natural trigger phrases. The main weakness is that it lists only two concrete actions, leaving specificity slightly short of comprehensive.

Suggestions

Add one or two more concrete actions (e.g., 'generate extracted_examples.py', 'resume from failed example') to lift specificity from a 3 toward a 4-5.

Include common synonyms or file extensions in the trigger clause (e.g., 'doc examples', 'code blocks in markdown', '.md examples') to push trigger-term coverage toward 5.

Dimension	Reasoning	Score
Specificity	"Extract Python examples from markdown docs and run them (including LLM examples)" names the domain plus two concrete actions (extract, run) but is not comprehensive, matching the score-3 anchor rather than the multi-action score-4 anchor.	3 / 5
Completeness	It clearly states what ("Extract Python examples from markdown docs and run them") and when ("Use when validating documentation, after doc changes, or to verify all doc examples execute correctly") with concrete trigger phrases, matching the score-5 anchor.	5 / 5
Trigger Term Quality	Phrases like "validating documentation", "after doc changes", and "to verify all doc examples execute correctly" give good natural-keyword coverage a user would plausibly say, falling just short of the comprehensive synonym coverage of score 5.	4 / 5
Distinctiveness Conflict Risk	The documentation-example execution niche and its triggers are mostly distinct with minimal conflict risk, though it could overlap slightly with general pytest/CI testing skills, keeping it just below score 5.	4 / 5
	Total	16 / 20 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
referenced_paths_exist	Referenced path issues: 1 missing	Warning

	Total	15 / 16 Passed

Repository: sandialabs/talkpipe
Path: .cursor/skills/run-documentation-examples/SKILL.md
Commit: 14049ad

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