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

82%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

76%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 content is highly actionable and well-structured with appropriate external references, but the workflow lacks explicit validation/verification checkpoints and leaves the in-place typography path without a backup, which caps workflow clarity. Tightening the report template and adding an output-validation step would raise the score.

Suggestions

Add an explicit validation checkpoint after Step 4/Step 6 (e.g., re-read the formatted file to confirm markdown is well-formed and no content was lost) before reporting completion.

Protect the 'Typography only' in-place path by backing up the original file before Step 6 modifies it, mirroring the backup logic already present in Step 5.

Consider moving the full completion-report template (Step 7) and the detailed EXTEND.md option tables into a reference file to tighten the main SKILL.md body.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient — actionable tables for script options, formatting toolkit, and EXTEND.md settings rather than padded prose — and avoids over-explaining basic concepts Claude already knows, but the completion-report template and the trailing Notes section contain content that could be trimmed, sitting just below the lean score-5 anchor.	4 / 5
Actionability	Provides fully executable guidance: concrete bash invocations with a complete script-options table, real file paths, substitution rules for {baseDir}/${BUN_X}, and copy-paste-ready examples covering the common cases (default, --quotes, --no-spacing), matching the score-5 anchor.	5 / 5
Workflow Clarity	The 7-step workflow is clearly sequenced with an explicit Analyze→Format structure and a backup step for the formatted output, but the 'Typography only' path modifies the original file in-place with no backup or output validation, and there is no verification step on the formatted result — validation gaps that cap this at 3 per the destructive/batch-operations rule.	3 / 5
Progressive Disclosure	Good structure with one-level-deep, well-signaled references: title-generation detail is correctly externalized to references/title-formulas.md (a real file) and scripts are documented in a table pointing to real files in scripts/. It stops at 4 because a fair amount of inline material (the full completion-report template, detailed EXTEND.md option tables) could be further externalized.	4 / 5
	Total	16 / 20 Passed

Description

88%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 concisely states concrete capabilities, provides explicit natural-language triggers, names the output file, and covers both what and when. The only gap is trigger-term breadth — adding file extensions and a couple more synonyms would push it to the top anchor.

Suggestions

Add file extensions and a few more natural synonyms to the trigger clause (e.g., 'format .md files', 'tidy markdown', 'clean up article formatting').

Tighten the 'improve article layout' trigger to a more formatting-specific phrase to reduce overlap with general editing skills.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete formatting actions — 'frontmatter, titles, summaries, headings, bold, lists, and code blocks' — giving comprehensive coverage of what the skill applies, matching the score-5 anchor for multiple specific concrete actions.	5 / 5
Completeness	Explicitly answers both 'what' (formats plain text/markdown with the listed elements) and 'when' (concrete 'Use when...' trigger phrases), plus the output destination, matching the score-5 anchor for clearly answering both what and when.	5 / 5
Trigger Term Quality	Includes natural phrases users would say — 'format markdown', 'beautify article', 'add formatting', 'improve article layout' — with good synonym coverage, but misses file extensions like .md and a few common variants, fitting just below the comprehensive score-5 anchor.	4 / 5
Distinctiveness Conflict Risk	The markdown-formatting niche with triggers like 'format markdown' and 'beautify article' is mostly distinct, but phrases such as 'improve article layout' carry minor overlap risk with general writing/editing skills, so it sits at 4 rather than 5.	4 / 5
	Total	18 / 20 Passed

Validation

81%

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

Validation for skill structure

Criteria	Description	Result
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
Commit: 1567581

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