CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

technical-writer

Audit, rewrite, and validate developer, administrator, and operator documentation—including API/OpenAPI references—against live repository evidence. Use when these documents need proof-backed correction, reader-focused review, generated-document ownership, public-access checks, or legacy docs-expert routing; route product end-user documentation to the separate User Documentation skill.

Quality

80%

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 ./Skills/agent-ops/technical-writer/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.

A dense, well-structured instruction body: clear lane separation, a numbered workflow, and unusually strong validation tooling with real commands. It loses points on closed-loop error recovery (recovery actions per failure class are unspecified), a few abstract workflow steps without worked examples, and ornate phrasing that costs clarity without saving tokens.

Suggestions

For each validation failure class (stale source, environment/tooling blocker, hosted blocker, blocked unknown), state the concrete next action so the feedback loop closes the way the stop rules already do.

Replace metaphorical phrasing like 'bounded truth constellation' and 'documentation supply chain' with plain equivalent terms (e.g., 'the set of surfaces that own or constrain the claims').

Add one short worked example of a claim -> evidence, owner, status, citation record so step 4's prescribed output is concrete rather than only structural.

DimensionReasoningScore

Conciseness

Extremely terse, telegraphic prose with zero explanation of concepts Claude already knows; almost every line is instruction. Not a 5 because of minor non-earning tokens: ornate metaphors ("Inspect the bounded truth constellation", "Resolve the documentation supply chain") and a noise HTML comment ("Discovery-smoke compatibility marker") that plainer phrasing would replace.

4 / 5

Actionability

The Validation section gives four concrete, executable commands (e.g., "./bin/ask skills audit <skill-path> --level strict --json --robot") and the workflow prescribes a concrete record structure ("claim -> evidence, owner, audience visibility, volatility, status, citation"). Not a 5 because several workflow steps remain abstract direction ("Preserve and classify checkout state", "Search the active glossary") with no worked example of the outputs they prescribe.

4 / 5

Workflow Clarity

A clearly numbered 12-step sequence with a dedicated Validation section specifying exact commands, a failure-classification taxonomy, and explicit stop rules ("Stop on introduced defects and required owning-contract failures"). Not a 5 because recovery actions are only defined for a subset of failure classes — it says to classify stale source, tooling blockers, etc., but not what to do next for each, so the feedback loop is not fully closed.

4 / 5

Progressive Disclosure

The body is a compact overview with a References section that one-line-annotates each file, and inline pointers load reference files exactly when needed (discovery-interview.md for underspecified requests, documentation-quality.md for rubric decisions); all referenced paths exist in the bundle. Not a 5 because knowledge-capsule-routing.md is a second-level index into knowledge-capsules/*.md (a 2-level hop from SKILL.md) and several bundle files are never signposted from the body.

4 / 5

Total

16

/

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.

A third-person description that clearly states what the skill does, when to use it, and where its boundary lies, with an explicit deconfliction rule for the sibling User Documentation skill. Its main gaps are trigger-phrase concreteness in the when-clause and missing common artifact keywords.

Suggestions

Add concrete artifact keywords users naturally say (README, runbook, API reference, docs review) to the description or its trigger coverage.

Rewrite the when-clause around concrete user moments (e.g., 'Use when the user asks to audit or rewrite a README, runbook, or API reference, or mentions docs-expert routing') instead of abstract need-conditions like 'generated-document ownership'.

DimensionReasoningScore

Specificity

Names the domain ("developer, administrator, and operator documentation—including API/OpenAPI references") and several concrete actions ("Audit, rewrite, and validate") grounded by a concrete evidentiary basis ("against live repository evidence"). Not a 5 because the action list stops at three verbs plus routing, without comprehensive coverage of deliverables.

4 / 5

Completeness

Both halves are present: a clear "what" ("Audit, rewrite, and validate... documentation... against live repository evidence") and an explicit "Use when these documents need..." clause. Not a 5 because the when-clause lists need-conditions ("proof-backed correction", "generated-document ownership") rather than concrete user-moment trigger phrases naming artifacts or scenarios.

4 / 5

Trigger Term Quality

Good natural-keyword coverage: "documentation", "audit", "rewrite", "API/OpenAPI references", and the explicit trigger phrase "docs-expert routing". Not a 5 because common user-facing terms like "README", "runbook", "technical writing", or "docs review" are absent.

4 / 5

Distinctiveness Conflict Risk

Clear niche (repo-evidence-backed technical documentation) with an explicit boundary statement ("route product end-user documentation to the separate User Documentation skill") that disambiguates the closest sibling skill, keeping conflict risk minimal.

5 / 5

Total

17

/

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

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

15

/

16

Passed

Repository

jscraik/Agent-Skills

Path

Skills/agent-ops/technical-writer/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.