technical-writing-clarity
Use this skill when writing documentation, READMEs, technical specs, runbooks, or any text that explains a system or process to other engineers. Apply before writing any developer-facing document.
68
Quality
83%
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
Technical Writing for Clarity
Principles:
- Lead with the purpose: What is this document for and who is it for?
- One idea per paragraph. Long paragraphs hide key information.
- Use active voice:
Run the scriptnotThe script should be run. - Concrete over abstract: Show an example rather than describing it abstractly.
- Avoid jargon you have not defined unless the audience definitely knows it.
Structure for runbooks/how-tos:
- Overview (1–2 sentences)
- Prerequisites
- Steps (numbered, imperative)
- Verification / expected output
- Troubleshooting
Anti-patterns: Documenting what without why, outdated examples, walls of text without headers.
- Repository
- aiming-lab/MetaClaw
- Commit
922caf3
- Last updated
- First committed
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.