blog-writer

Plan, write, and review VS Code blog posts. ALWAYS use this skill when the user asks to "write a blog post", "draft a blog", "add a blog post for", "review this blog post", or provides a feature/issue/PR to announce on the VS Code blog. For new posts, it proposes an outline and asks clarifying questions first, and does not edit any files until you approve the plan.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

77%Weight 40%Scale 1-3

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

The body is well-structured and highly actionable with a clear two-phase workflow and an explicit approval gate. Its main weaknesses are mild redundancy of style rules already delegated to an external guide and references to files that are not present in the skill bundle.

Suggestions

Stop restating the style rules (active voice, "we", contractions, the "Happy coding! 💙" closing) in Guardrails, Phase 2, and Review Mode — reference the blog-writing style guide once and trust it, to tighten conciseness.

Either ship the referenced style-guide files inside the bundle (e.g. references/blog-writing.md) and point to them there, or remove the broken ../../instructions/*.instructions.md references so the skill is self-contained and the progressive-disclosure links resolve.

Move the full frontmatter field list and source-repo mapping table into a one-level-deep reference file so the main SKILL.md stays a lean overview.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient and does not explain concepts Claude already knows, but it restates style rules the skill explicitly delegates to the external style guide ("active voice", "we", contractions, the "Happy coding! 💙" closing) across Guardrails, Phase 2, and Review Mode — content that could be tightened by trusting the referenced guide.	2 / 3
Actionability	Gives concrete, specific guidance — exact folder paths (blogs/<year>/<month>/<day>/), the full required frontmatter field list, the byline format, and a source-repo mapping table — which is highly actionable for an instruction-only skill.	3 / 3
Workflow Clarity	Two phases are clearly sequenced with an explicit approval checkpoint ("Stop and wait for approval… Do not proceed to Phase 2 until the user explicitly approves"), plus a numbered Phase 1 and a checklist-style Review Mode, matching the level-3 anchor.	3 / 3
Progressive Disclosure	Sections are well-organized, but the body references style-guide files (../../instructions/blog-writing.instructions.md, ../../instructions/docs-writing.instructions.md) that are not part of the bundle and do not exist on disk, and it inlines detail (full frontmatter list, style rules) that a present reference file would hold — matching the level-2 anchor for structure with missing/unclear references and inline content.	2 / 3
	Total	10 / 12 Passed

Description

100%Weight 40%Scale 1-3

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: it states concrete capabilities, packs in natural trigger phrases, and clearly answers both what and when with an explicit "Use when…"-style clause. Third-person voice is maintained throughout.

Dimension	Reasoning	Score
Specificity	Names multiple concrete actions — "Plan, write, and review VS Code blog posts", "proposes an outline and asks clarifying questions first", "does not edit any files until you approve the plan" — matching the level-3 anchor for multiple specific concrete actions.	3 / 3
Completeness	Explicitly answers both what (plan, write, review VS Code blog posts) and when via an "ALWAYS use this skill when…" clause with concrete triggers, matching the level-3 anchor.	3 / 3
Trigger Term Quality	Includes natural phrases a user would actually say — "write a blog post", "draft a blog", "add a blog post for", "review this blog post", plus "announce this on the blog" — giving good coverage of common variations.	3 / 3
Distinctiveness Conflict Risk	Scoped narrowly to VS Code blog posts with distinct triggers and an explicit carve-out for reference docs/release notes/API docs, making it unlikely to fire for the wrong skill.	3 / 3
	Total	12 / 12 Passed

Validation

87%

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

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 1 missing, 4 suspicious	Warning

	Total	14 / 16 Passed

Repository: microsoft/vscode-docs
Path: .github/skills/blog-writer/SKILL.md
Commit: 66977a9

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