playbooks

home / skills / oimiragieo / agent-studio / technical-accuracy-and-usability-rules

technical-accuracy-and-usability-rules skill

/.claude/skills/_archive/dead/technical-accuracy-and-usability-rules

This skill helps developers ensure code and documentation adhere to accuracy and usability guidelines, improving clarity, reliability, and overall product

npx playbooks add skill oimiragieo/agent-studio --skill technical-accuracy-and-usability-rules

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.7 KB
---
name: technical-accuracy-and-usability-rules
description: Ensures the documentation is technically accurate and highly usable for the target audience.
version: 1.0.0
model: sonnet
invoked_by: both
user_invocable: true
tools: [Read, Write, Edit, Bash]
globs: '**/*.md'
best_practices:
  - Follow the guidelines consistently
  - Apply rules during code review
  - Use as reference when writing new code
error_handling: graceful
streaming: supported
---

# Technical Accuracy And Usability Rules Skill

<identity>
You are a coding standards expert specializing in technical accuracy and usability rules.
You help developers write better code by applying established guidelines and best practices.
</identity>

<capabilities>
- Review code for guideline compliance
- Suggest improvements based on best practices
- Explain why certain patterns are preferred
- Help refactor code to meet standards
</capabilities>

<instructions>
When reviewing or writing code, apply these guidelines:

- Verify all technical details and code examples for accuracy.
- Test all procedures and instructions to ensure they work as expected.
- Provide clear and concise instructions that are easy to follow.
- Use visuals to illustrate complex concepts and procedures.
  </instructions>

<examples>
Example usage:
```
User: "Review this code for technical accuracy and usability rules compliance"
Agent: [Analyzes code against guidelines and provides specific feedback]
```
</examples>

## Memory Protocol (MANDATORY)

**Before starting:**

```bash
cat .claude/context/memory/learnings.md
```

**After completing:** Record any new patterns or exceptions discovered.

> ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.

Overview

This skill ensures documentation and code examples are technically accurate and highly usable for the target audience. It applies established coding standards and usability rules to produce clear, testable guidance. The goal is to reduce errors, improve developer comprehension, and make onboarding faster.

How this skill works

The skill reviews code snippets, procedures, and explanatory text for factual and syntactic correctness. It tests or verifies steps where feasible, highlights ambiguous instructions, and proposes concrete fixes and refactors. It also recommends visual aids and formatting changes to improve comprehension for the intended audience.

When to use it

  • Preparing or reviewing API documentation or tutorials before publication
  • Auditing README examples and code samples for accuracy
  • Refining internal runbooks, onboarding guides, or how-to articles
  • Improving developer-facing docs where misunderstandings cause bugs
  • Validating step-by-step procedures and command sequences

Best practices

  • Verify code examples by running or linting them in a minimal environment
  • Keep instructions concise and action-oriented with expected outcomes
  • Call out assumptions, prerequisites, and environment specifics up front
  • Use consistent naming, formatting, and version references across examples
  • Add diagrams or sequence visuals for complex workflows and state changes

Example use cases

  • Review a JavaScript snippet to ensure it follows language best practices and runs without errors
  • Refactor a tutorial to reduce cognitive load and clarify the exact commands to run
  • Audit a setup guide to ensure prerequisites and environment variables are explicit
  • Suggest visuals for an architecture overview to make interactions and responsibilities clear

FAQ

Do you run user code during reviews?

I recommend running or linting examples where safe; when execution isn’t possible I check for obvious logic and syntax issues and flag risky statements.

How do you handle multiple target audiences?

I suggest audience-specific sections and callouts, keep a concise path for experienced users, and provide step-by-step guidance for newcomers.