writing-guidelines

Review docs/prose for Writing Guidelines compliance. Use when asked to "review my docs", "check writing style", "audit prose", "review docs voice and tone", or "check this page against the writing handbook".

Quality

71%

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

Fix and improve this skill with Tessl

tessl review fix ./skills/writing-guidelines/SKILL.md

Quality

Content

65%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 skill body is well-structured with excellent progressive disclosure, pointing cleanly to a real pinned reference. Its main weaknesses are redundant step lists across two sections and the absence of any validation/verification checkpoint for what is a batch review operation.

Suggestions

Merge the near-duplicate 'How It Works' and 'Usage' step lists into a single workflow to remove redundancy.

Add an explicit verification checkpoint (e.g. 'Confirm every requested file was read before reporting') to address the batch-operation validation gap.

Specify how findings are grouped or deduplicated across files so the output step is fully actionable.

Dimension	Reasoning	Score
Conciseness	The body is free of concept over-explanation, but 'How It Works' and 'Usage' present near-identical five-step lists (load guidelines, optionally fetch upstream, read files, apply rules, output findings) that should be merged. This redundant restating keeps it at 'could be tightened' rather than the minor-trim level of 4.	3 / 5
Actionability	Guidance is concrete and executable: a specific pinned file path, a concrete upstream URL, and a defined output format ('terse file:line'). Per the instruction-only scoring note, absence of code is not penalized; the minor gap is that the substantive rule set is delegated to the reference.	4 / 5
Workflow Clarity	Steps are clearly numbered and sequenced with a conditional for missing files, which would normally rate 4-5 for a simple skill. However the skill is a batch operation (reviewing multiple files) with no validation or verification checkpoint, so the batch-operation cap of 3 applies and takes precedence over the simple-skill exception.	3 / 5
Progressive Disclosure	The body is a concise overview that defers the bulk rule set to a single, clearly signaled, one-level-deep reference (references/guidelines.md, verified to exist) via markdown links, with the upstream live source also clearly separated. Content is appropriately split and easy to navigate.	5 / 5
	Total	15 / 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 clearly answers both what the skill does and when to invoke it, with natural, varied trigger phrases. Its main weakness is specificity, listing only one generic action ('Review') rather than concrete capabilities.

Suggestions

Enumerate concrete actions beyond 'Review' (e.g. 'check voice and tone, verify formatting, validate content structure') to lift specificity.

Add a couple of common natural synonyms such as 'proofread my docs' or 'writing review' to round out trigger coverage.

Tighten the generic 'review my docs' trigger with a style/guidelines qualifier to reduce overlap with general doc-review skills.

Dimension	Reasoning	Score
Specificity	Names the domain ('docs/prose') and one concrete action ('Review ... for Writing Guidelines compliance'), but offers only a single generic action rather than a list of specific capabilities. It is not a 2 because a concrete action and domain are present, and not a 4 because no additional distinct actions are enumerated.	3 / 5
Completeness	Explicitly states what the skill does ('Review docs/prose for Writing Guidelines compliance') and when to use it via concrete trigger phrases in a 'Use when...' clause, satisfying both halves of the anchor.	5 / 5
Trigger Term Quality	Includes several natural phrases users would actually say ('review my docs', 'check writing style', 'audit prose', 'review docs voice and tone') plus a non-English variant. Good coverage but a few natural synonyms (e.g. 'proofread', 'writing review') are absent, so it stops short of 5.	4 / 5
Distinctiveness Conflict Risk	The 'Writing Guidelines compliance' niche and style-oriented triggers ('audit prose', 'review docs voice and tone') are fairly distinct, but the generic trigger 'review my docs' carries minor overlap risk with broader documentation-review skills, keeping it just below 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
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: nexu-io/open-design
Path: skills/writing-guidelines/SKILL.md
Commit: f580271

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.