CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

baoyu-format-markdown

Formats plain text or markdown files with frontmatter, titles, summaries, headings, bold, lists, and code blocks. Use when user asks to "format markdown", "beautify article", "add formatting", or improve article layout. Outputs to {filename}-formatted.md.

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 ./skills/baoyu-format-markdown/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

68%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, highly actionable workflow skill with concrete commands, verified script options, and a clearly sequenced 7-step process that appropriately offloads title formulas to a real one-level reference. Its main weaknesses are the missing safety/validation checkpoint around the destructive in-place typography path (capping workflow clarity) and localized verbosity in runtime-mechanics sections.

Suggestions

Add a backup step before the in-place "Typography only" path (Step 1 option 3) — e.g., copy the original file with a timestamped suffix, mirroring the Step 5 backup — so the destructive modification is reversible.

Add an explicit validation loop after Step 6: check the typography script's exit status/output, and on failure review the error and re-run before reporting completion, rather than reporting applied/skipped unconditionally.

Trim the "User Input Tools" section to a single line (e.g., "Prefer the runtime's built-in user-input tool; otherwise ask numbered plain-text questions") and drop the duplicated EXTEND.md mention in "Extension Support".

DimensionReasoningScore

Conciseness

The body is dense and table-driven (preferences tables, options table, do/don't lists) with almost no concept explanation Claude already knows, but sections like the ~10-line "User Input Tools" runtime mechanics and the duplicated EXTEND.md pointer are over-explanation that could be trimmed — efficient with minor instances of padding, anchor 4; not 3 because the padding is localized rather than pervasive.

4 / 5

Actionability

Guidance is mostly executable: a copy-paste bash backup snippet, a script invocation `${BUN_X} {baseDir}/scripts/main.ts {output-file-path} [options]` whose flags were verified against the actual scripts/main.ts CLI, exact EXTEND.md paths, and verbatim prompt/report templates. Minor gaps remain — commands require placeholder substitution and the usage examples line ("main.ts article.md (defaults)") omits the full invocation prefix — so anchor 4 rather than the fully copy-paste-ready anchor 5.

4 / 5

Workflow Clarity

Steps 1-7 are clearly sequenced with explicit decision branches at Step 1 ("Optimize → Step 2", "Keep original → skip to Step 5", "Typography only → skip to Step 6"), but the "Typography only" path runs the script on the original file in-place — a destructive modification with no backup step (the only backup covers the -formatted.md copy) and no verification of script success before reporting. Per the rubric, a destructive operation without validation/feedback loops caps this dimension at 3, taking precedence over the otherwise clear sequence.

3 / 5

Progressive Disclosure

The single external reference [references/title-formulas.md](references/title-formulas.md) is well-signaled, one level deep, and verified to exist; the three scripts are described in a table rather than inlined. However, the ~236-line body carries several large verbatim prompt/report templates (Step 1 menu, Step 2 analysis template, Step 7 report) that make it denser than an overview — good structure with minor organization gaps, anchor 4; not 5 because not all content is appropriately split out of the main file.

4 / 5

Total

15

/

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 that clearly and explicitly covers what the skill does, when to use it via natural quoted trigger phrases, and where output lands, all in third person. The main gaps are the omission of the default typography/spacing capability and a few missing natural synonyms, which keep specificity and trigger coverage at the good-but-not-comprehensive level.

DimensionReasoningScore

Specificity

"Formats plain text or markdown files with frontmatter, titles, summaries, headings, bold, lists, and code blocks" lists six-plus concrete actions, but the description omits the typography/spacing fixes the workflow applies by default (Step 6), a real capability gap that keeps it below the comprehensive anchor 5.

4 / 5

Completeness

The first sentence explicitly states what the skill does, the "Use when user asks to..." clause gives concrete trigger phrases for when to use it, and "Outputs to {filename}-formatted.md" adds the output destination — both what and when clearly and explicitly answered, matching anchor 5; not 4 because the when-clause is fully explicit rather than improvable.

5 / 5

Trigger Term Quality

Explicit triggers "format markdown", "beautify article", "add formatting", or "improve article layout" are phrases users would naturally say, but common synonyms such as "clean up", "polish", "prettify", or "typography/spacing" are missing — good coverage with a few gaps, matching anchor 4 rather than the comprehensive anchor 5.

4 / 5

Distinctiveness Conflict Risk

Markdown/article formatting is a fairly distinct niche with specific triggers, but phrases like "add formatting" or "improve article layout" could still overlap with general document-styling or prose-editing skills — mostly distinct with minor overlap risk, anchor 4; not 5 because conflict risk is not minimal.

4 / 5

Total

17

/

20

Passed

Validation

81%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 13 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

metadata_field

'metadata' should map string keys to string values

Warning

frontmatter_unknown_keys

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

Warning

Total

13

/

16

Passed

Repository

JimLiu/baoyu-skills

Path

skills/baoyu-format-markdown/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.