CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

technical-writing

Layered technical-writing standard: Diátaxis structure, Google developer style sentences, STE instruction rules, Global English syntax. Use for /technical-writing or when writing or reviewing docs, RFCs, readmes, PR descriptions, or commit messages.

Quality

81%

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

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 tight, disciplined style standard that shows rather than tells: nearly every rule ships with a before/after phrase pair and a real-symbol worked example. Its weaknesses are process-shaped, not content-shaped — no explicit application order beyond mode-first and no verification pass for the review workflow it explicitly claims.

Suggestions

Add an explicit application sequence for reviewing (e.g., mode check → structure → sentence-level layers → rhythm), plus a final verification pass such as re-reading the doc once against the three meta-rules before returning it.

Add one short worked example per Diátaxis mode (a tutorial paragraph and a reference paragraph), mirroring the existing reference-style example, so the mode rules are demonstrated rather than only stated.

Deduplicate rules that appear in multiple layers — passive voice and one-word-per-action each appear in two sections — and cross-reference the other section instead, tightening the token budget.

DimensionReasoningScore

Conciseness

The body is dense and prescriptive, with nearly every rule carrying an inline before/after pair ("'In order to' is 'to'"), but rules repeat across sections — passive voice appears in both the Google section and the STE section, and one-word-per-action appears in both STE ("Pick one word per action and stick to it") and Global English ("Call each thing by one name, everywhere"). This matches anchor 4 (efficient with minor instances that could be trimmed) rather than 5, since the duplication means not every token earns its place.

4 / 5

Actionability

Guidance is highly concrete: paired replacements throughout ("Use", not "utilize"; "a column rename fails the build"), a two-question mode-selection procedure, and a worked example with real symbols (`budget.mjs`, `budget.json`, `--write`). It falls just short of anchor 5 because examples do not cover all common cases — only one worked example is given, with no sample tutorial/how-to restructuring.

4 / 5

Workflow Clarity

Only "Pick the mode first (Diátaxis)" establishes an application order; the sequence for the remaining layers is implicit and no verification checkpoint exists for the reviewing side of the skill (e.g., a final pass checking the doc against each layer). This matches anchor 3 (steps listed but checkpoints missing or implicit) rather than 4, which requires most checkpoints present.

3 / 5

Progressive Disclosure

No bundle files exist, so all content lives in one well-sectioned ~100-line SKILL.md with clear headers ("Pick the mode first (Diátaxis)", "Worked example") and easy in-file navigation. This matches anchor 4 (good structure, minor organization gaps) — the per-mode paragraphs could split into reference files and the "Vary the rhythm" section sits oddly before mode-picking — and the under-50-line simple-skill exception to reach 5 does not apply at this length.

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 explicitly answers both what the skill does and when to use it, in third person, with concrete named frameworks and natural trigger phrases spanning the slash command, doc types, and commit artifacts. Its only weaknesses are minor: a few missing natural synonyms and slight overlap risk with dedicated commit-message/PR skills.

DimensionReasoningScore

Specificity

The description lists four concrete components ("Diátaxis structure, Google developer style sentences, STE instruction rules, Global English syntax") and concrete artifacts ("docs, RFCs, readmes, PR descriptions, or commit messages"), matching anchor 4 (several specific items, minor gaps). It is below anchor 5 because the actions themselves (apply, restructure, edit) are implicit behind "Layered technical-writing standard".

4 / 5

Completeness

Both halves are explicit: the "what" ("Layered technical-writing standard: Diátaxis structure, Google developer style sentences, STE instruction rules, Global English syntax") and the "when" ("Use for /technical-writing or when writing or reviewing docs, RFCs, readmes, PR descriptions, or commit messages") with concrete trigger phrases. This matches anchor 5 exactly, and the required 'Use when...' clause is present so no cap applies.

5 / 5

Trigger Term Quality

"docs, RFCs, readmes, PR descriptions, commit messages" plus the "/technical-writing" slash command are all natural phrasings a user would say, matching anchor 4 (good coverage, a few natural terms missing). Anti-drift check against anchor 5: common synonyms such as "documentation", "user guide", or "changelog" are absent, so it does not reach comprehensive synonym coverage.

4 / 5

Distinctiveness Conflict Risk

The four named frameworks establish a clear niche distinct from generic doc-generation skills, but "PR descriptions, or commit messages" overlaps with dedicated commit-message and PR-writing skills, matching anchor 4 (mostly distinct, minor overlap risk with closely related skills). It does not reach anchor 5 because of that overlap, and it is clearly above anchor 3 given the framework-specific triggers.

4 / 5

Total

17

/

20

Passed

Validation

100%

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

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

geut/factory-skills

Path

.agents/skills/technical-writing/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.