CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

docs-writing-style

Export a docs style prompt or review a draft against the house rubric. Use when handing off voice to an agent or checking a docs draft. It does not place the page (that's `docs-contribution-router`).

Quality

74%

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 ./plugins/documentation/skills/docs-writing-style/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

75%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 body is well structured with a clear two-mode contract, concrete output formats, and real, well-signaled one-level-deep references. Its main weaknesses are redundancy between the inline quick-reference rules and the reference files, plus Scalekit-specific content that contradicts the skill's own site-agnostic claim.

Suggestions

Trim the "Key rules (quick reference)" section to the handful of always-FAIL rules and defer the full list to references/style-principles.md, which already covers most of it.

Move the Scalekit-specific Code rules (SDK language tabs, `scalekit` variable names) into the site-specific prompt block or a site reference, keeping SKILL.md genuinely site-agnostic as the Adapt section claims.

Add a verification step to review mode, such as re-reading the FAIL list against the draft before reporting, to give the workflow an explicit checkpoint.

DimensionReasoningScore

Conciseness

The ~40-line "Key rules (quick reference)" section duplicates material already in references/style-principles.md (sentence case, story first, then the work, imperative verbs all appear in both), and the Scalekit-specific Code rules (four SDK languages, `scalekit` variable names) duplicate the site prompt block the skill also loads. This is 'mostly efficient but includes some unnecessary explanation or could be tightened' — not anchor 2's pervasive padding, since the rest of the body is dense and earns its place.

3 / 5

Actionability

Guidance is copy-paste ready: an exact report format block (PASS/FAIL/WARN with arrow syntax), exact paste destinations (CLAUDE.md, .cursorrules, .github/copilot-instructions.md), concrete before/after examples ("Configure your auth provider" not "Configure Your Auth Provider"), and specific fallback paths. As an instruction-only skill, the absence of executable code is not penalized per the rubric's scoring notes, and the guidance fully covers the common cases.

5 / 5

Workflow Clarity

Both modes have clear numbered sequences, a mode-selection table up front, priority-ordered reporting (fails, warns, passes), a defined closing action, and a session-level feedback loop ("Did this solve what you were trying to do?" with an issue-filing fallback). It falls short of anchor 5 because there are no in-workflow validation checkpoints verifying the produced output (e.g., confirming the exported prompt block is complete) — though as a non-destructive, non-batch skill it incurs no cap.

4 / 5

Progressive Disclosure

All four referenced files (style-principles.md, scalekit-style-prompt-block.md, llms-judge-rubric.md, _template-style-prompt-block.md) exist, are one level deep, and are clearly signaled per mode with explicit load instructions. It is not anchor 5 because content that should live in those references is inlined in the body: the quick-reference rules duplicate style-principles.md and the Scalekit-specific code rules belong in the site prompt block rather than the site-agnostic SKILL.md.

4 / 5

Total

16

/

20

Passed

Description

62%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 answers both what and when in third person and explicitly fences off a sibling router skill, which is a strength. It is held back by thin trigger-term coverage and only partial specificity about what each mode actually produces.

Suggestions

Add natural trigger synonyms to the when-clause, e.g. "Use when handing off voice to a coding agent, checking a docs draft, or when the user mentions documentation style, tone, or a style guide."

Make each mode's output concrete in the what-clause: "Export a self-contained style prompt block for coding agents, or diagnose a docs draft against a PASS/FAIL/WARN rubric."

Name the typical artifacts users mention (CLAUDE.md, .cursorrules, copilot-instructions.md) so the description triggers on system-instruction setup requests.

DimensionReasoningScore

Specificity

"Export a docs style prompt or review a draft against the house rubric" names the domain and two concrete actions, matching the '1-2 concrete actions, but not comprehensive' anchor. It is above anchor 2 (which only names a domain with generic actions) but below anchor 4, which expects several specific actions with only minor gaps in coverage.

3 / 5

Completeness

Both questions are answered: what ("Export a docs style prompt or review a draft against the house rubric") and when ("Use when handing off voice to an agent or checking a docs draft"). The when-clause is explicit but not as concrete as anchor 5, which demands trigger phrases covering multiple entry points; it is clearly above anchor 3, where when is only weakly implied.

4 / 5

Trigger Term Quality

"Use when handing off voice to an agent or checking a docs draft" contains some natural keywords ("docs draft", "agent", "voice"), but misses common variations users would actually say such as "documentation style", "style guide", "tone", or "review my documentation". This fits anchor 3 ('some relevant keywords but missing common variations or synonyms') better than anchor 4's 'good keyword coverage, a few natural terms missing'.

3 / 5

Distinctiveness Conflict Risk

The niche (docs voice/style handoff and rubric review) is fairly distinct, and the explicit boundary "It does not place the page (that's `docs-contribution-router`)" disambiguates from the closest sibling skill. Minor overlap risk remains with generic writing/editing-review skills, so anchor 4 fits better than anchor 5.

4 / 5

Total

14

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

metadata_field

'metadata' should map string keys to string values

Warning

Total

15

/

16

Passed

Repository

saif-shines/devex-kit

Path

plugins/documentation/skills/docs-writing-style/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.