# Improve Technical Writing Clarity

Technical content can feel clear to experts while confusing learners. This skill reviews drafts for audience fit, jargon, missing context, accessibility, and practical revision steps.

## Install

```bash
npx skillstore add 92bilal26/technical-clarity
```

## Metadata

- - Status: approved
- - Slug: 92bilal26-technical-clarity
- - Version: 1.0.0
- - Author: 92Bilal26
- - GitHub username: 92Bilal26
- - License: MIT
- - Repository: https://github.com/92Bilal26/TaskPilotAI/tree/main/.claude/skills/technical-clarity
- - Ref: main
- - Supported tools: Claude, Codex, Claude Code
- - Risk level: safe
- - Quality score: 80
- - Quality tier: silver
- - Public page: https://skillstore.pages.dev/skills/92bilal26-technical-clarity
- - Manifest: https://skillstore.pages.dev/api/skills/92bilal26-technical-clarity/manifest

## Capabilities

- Reviews documentation, tutorials, examples, and educational content for learner comprehension.
- Checks audience level, prerequisite assumptions, reading difficulty, and sentence complexity.
- Identifies gatekeeping language, undefined jargon, missing context, and abstract-first explanations.
- Suggests clearer definitions, examples, prerequisites, motivations, and accessibility improvements.
- Produces structured clarity reports with issue severity, impact, and specific fixes.
- Applies accessibility checks for alt text, semantic structure, code readability, and color dependence.

## Use Cases

- Review a Beginner Tutorial: Check whether a tutorial explains prerequisites, defines terms, and avoids expert assumptions.
- Prepare API Documentation: Improve reference text so readers understand purpose, constraints, examples, and error cases.
- Audit Course Material: Assess lessons for reading level, jargon density, accessibility, and learner confidence.

## Prompt Templates

### Quick Clarity Check

```
Review this technical explanation for clarity. Identify confusing phrases, undefined terms, and missing context. Target audience: beginner. Draft: [paste text].
```

### Audience-Level Review

```
Audit this content for a B1 intermediate learner. Check sentence length, jargon density, prerequisites, examples, and accessibility. Provide prioritized fixes. Content: [paste text].
```

### Tutorial Revision Plan

```
Review this tutorial and create a revision plan. Focus on show-before-tell structure, definitions, motivation, error cases, and learner confidence. Tutorial: [paste text].
```

### Full Documentation Audit

```
Perform a full technical clarity audit for this documentation. Include audience assumptions, readability risks, accessibility issues, issue severity, impact, and rewritten examples where useful. Documentation: [paste text].
```

## Limitations

- It provides editorial review and does not verify technical runtime correctness.
- Readability scores are guidance and may need external measurement for strict compliance.
- It depends on the user to provide the target audience and source material.
- It does not replace a review by real learners or accessibility specialists.

## Best Practices

- Provide the target audience, learning context, and expected prerequisite knowledge.
- Ask for issue severity, learner impact, and concrete rewrite suggestions.
- Review the revised text again after applying major clarity changes.

## Anti Patterns

- Do not ask for generic proofreading when you need learner-comprehension analysis.
- Do not omit the target proficiency level or expected reader background.
- Do not accept readability scores without checking examples, context, and accessibility.

## Security Audit

- - Safe to publish: true
- - Audited at: 2026-06-27T18:26:03.589\+00:00
- - Summary: Static analysis reported shell execution, weak cryptography, and system reconnaissance patterns. Review found these are false positives from Markdown fences, inline code formatting, HTTPS examples, accessibility prose, and readability metrics in SKILL.md. No executable scripts, network calls, credential access, prompt injection attempts, or malicious intent were found.

## Stats

- - Views: 194
- - Downloads: 13
- - Favorites: 0
- - Popularity score: 0