doc-example-formatting

Format code examples in markdown documentation for TalkPipe. Use when writing or editing doc examples. Covers unindented fences, standalone vs fragment intent, and skip-extract. Complements run-documentation-examples which runs the examples.

1.16x

Quality

73%

Does it follow best practices?

Impact

93%

1.16x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Fix and improve this skill with Tessl

tessl review fix ./.cursor/skills/doc-example-formatting/SKILL.md

Quality

Content

72%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This is a solid, well-structured skill that provides actionable formatting guidance with concrete examples. Its main weakness is a slight lack of workflow sequencing—the validation step could be better integrated into an explicit edit-validate-fix loop. Minor verbosity in a few spots (the 'Why' explanation, some redundancy between sections) keeps conciseness from top marks.

Suggestions

Tighten the validation section into an explicit feedback loop: format → run pytest → fix failures → re-run, rather than listing the command as an afterthought.

Remove the 'Why' explanation for unindented fences—the preference is sufficient without justification—and consolidate the 'Good vs Bad' section with the earlier formatting examples to reduce redundancy.

Dimension	Reasoning	Score
Conciseness	Mostly efficient but includes some unnecessary explanation. The 'Why' for unindented fences and the 'When to Use' section add modest value. The 'Good vs Bad' section partially duplicates the earlier formatting section. Some tightening possible but not egregiously verbose.	2 / 3
Actionability	Provides concrete, copy-paste-ready examples of correct formatting, skip-extract usage, and validation commands. The good vs bad comparisons give specific patterns to follow and avoid. The pytest command is directly executable.	3 / 3
Workflow Clarity	The skill covers a relatively simple task (formatting code blocks) so a complex workflow isn't strictly needed. However, the validation step at the end is somewhat disconnected from the editing steps—there's no explicit sequence like 'format → validate → fix → re-validate' feedback loop, which would be valuable since bad formatting can break extraction.	2 / 3
Progressive Disclosure	The skill provides a clear overview and immediately references the full guidelines document (docs/architecture/documentation-formatting.md) for deeper detail. Sections are well-organized with clear headers. For a skill of this scope, the structure is appropriate with one-level-deep references.	3 / 3
	Total	10 / 12 Passed

Description

75%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This is a reasonably well-crafted description for a niche, project-specific skill. Its strengths are clear completeness (both what and when are addressed) and strong distinctiveness, including explicit disambiguation from a related skill. Its main weakness is that the specific capabilities could be more concretely enumerated as discrete actions rather than topic areas.

Suggestions

Expand the specific actions beyond 'format code examples' — e.g., 'Adds proper fence formatting, sets standalone vs fragment intent markers, applies skip-extract annotations to code blocks'

Consider adding a few more natural trigger terms users might say, such as 'code block formatting', 'documentation code snippets', or 'markdown fences'

Dimension	Reasoning	Score
Specificity	Names the domain (formatting code examples in markdown documentation) and mentions some specific concepts like 'unindented fences', 'standalone vs fragment intent', and 'skip-extract', but doesn't list multiple concrete actions beyond 'format code examples'. The specific terms are more like coverage areas than discrete actions.	2 / 3
Completeness	Clearly answers both 'what' (format code examples in markdown documentation for TalkPipe, covering unindented fences, standalone vs fragment intent, and skip-extract) and 'when' ('Use when writing or editing doc examples'). Also includes a helpful disambiguation note about the complementary skill 'run-documentation-examples'.	3 / 3
Trigger Term Quality	Includes some relevant keywords like 'code examples', 'markdown documentation', 'TalkPipe', 'doc examples', 'unindented fences', and 'skip-extract'. However, these are fairly domain-specific/technical terms and may miss common user phrasings. Terms like 'format', 'documentation', and 'code examples' are reasonable triggers.	2 / 3
Distinctiveness Conflict Risk	Clearly scoped to a specific niche: formatting code examples in TalkPipe markdown documentation. The explicit mention of complementary skill 'run-documentation-examples' and the distinction between formatting vs running examples helps prevent conflicts. The domain-specific terms like 'skip-extract' and 'unindented fences' further narrow the scope.	3 / 3
	Total	10 / 12 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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: sandialabs/talkpipe
Commit: 0cf1686

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