Tessl • The management layer for AI agent skills

SkillPublic

technical-writing

Invoke this skill whenever you need to create, update, review, restructure, or audit technical documentation such as README files, user manuals, API documentation, architecture notes, setup guides, troubleshooting guides, or developer docs. Use it to align docs with source code, existing project conventions, and the intended audience.

Quality

87%

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

Quality

Content

78%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 lean, well-organized instruction-only skill whose guidance is mostly concrete and non-obvious (check AGENTS.md/.codex, verify claims against source, rewrite stale content in place, avoid duplication). It falls short of top marks on conciseness and actionability due to a few default-behavior bullets and abstract directives, and its workflow order is implicit rather than an explicit checklist.

Suggestions

Trim bullets that restate Claude's default behavior (e.g., "Use clear, direct language. Avoid jargon..." and "Proofread for grammar, spelling, formatting, and consistency") to free tokens for the skill's non-obvious rules.

Make the implicit workflow order explicit — a short ordered sequence (read project conventions → confirm audience → write/update → verify links, commands, and paths) would convert the four sections into a checkable checklist.

For audience identification, replace the abstract directive with a concrete heuristic, such as where to infer the audience from (README tone, existing docs' reading level, repo language vs. end-user product docs).

Dimension	Reasoning	Score
Conciseness	The body is efficient and prescriptive ("Rewrite stale content in place. Avoid appending correction notes unless the document intentionally keeps historical context") with no concept explanations, but a few bullets restate Claude's default behavior ("Use clear, direct language. Avoid jargon, complex sentences"; "Proofread for grammar, spelling, formatting"), fitting the 4 anchor's minor over-explanation.	4 / 5
Actionability	Mostly concrete directives — "Check for files such as `AGENTS.md`, `README.md`, `docs/`, `.agents/`, `.codex/`" and "Verify technical claims against source code, schemas, configuration, command output, APIs" — and absence of code is acceptable for an instruction-only skill; a few bullets remain abstract ("Identify the likely audience from the document type, repository context, and user request"), leaving minor gaps.	4 / 5
Workflow Clarity	The sections imply a coherent sequence (Source First → Target Audience → Language and Structure → Review and Edit) ending in a verification checkpoint ("Verify that links, references, commands, examples, and file paths are correct and functional when practical"), but the ordering is implicit in section arrangement rather than explicit steps, with no error-recovery loop.	4 / 5
Progressive Disclosure	At ~30 lines with four well-organized sections and no need for external references (no bundle files exist), the skill meets the simple-skill exception: well-organized sections alone merit a 5.	5 / 5
	Total	17 / 20 Passed

Description

91%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 with explicit what/when structure, comprehensive concrete actions, and abundant natural trigger terms. Its only flaws are a second-person voice slip ("whenever you need to") and mild breadth that leaves some overlap risk with adjacent writing skills.

Dimension	Reasoning	Score
Specificity	The description lists five concrete actions ("create, update, review, restructure, or audit") with comprehensive doc-type coverage ("README files, user manuals, API documentation, architecture notes, setup guides, troubleshooting guides, or developer docs"), matching the 5 anchor; however, the second-person phrasing "whenever you need to" triggers the rubric's 1-point voice penalty, lowering it to 4.	4 / 5
Completeness	Both questions are explicitly answered: what ("create, update, review, restructure, or audit technical documentation... align docs with source code, existing project conventions, and the intended audience") and when ("Invoke this skill whenever you need to..."), a concrete explicit trigger clause.	5 / 5
Trigger Term Quality	Comprehensive natural trigger terms users would actually say — "technical documentation", "README files", "user manuals", "API documentation", "setup guides", "troubleshooting guides", "developer docs" — including synonyms, matching the 5 anchor's coverage.	5 / 5
Distinctiveness Conflict Risk	A clear niche (technical documentation) with distinct triggers (README, API documentation, troubleshooting guides), but the broad documentation domain creates minor overlap risk with closely related writing and project-scaffolding skills, fitting the 4 anchor rather than minimal-conflict 5.	4 / 5
	Total	18 / 20 Passed

Validation

100%

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

Validation for skill structure

No warnings or errors.

Repository: chattocorp/chatto
Path: .agents/skills/technical-writing/SKILL.md
Revision: bf769cf

Reviewed: 18 days ago

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.

technical-writing

Table of Contents

Is this your skill?