Skip to content
cccskills
FreePublished on GitHub

scan-usr

Use when: analysing a project's user-facing health — discoverability, documentation, and product clarity.

The English summary is being prepared. Showing the original description.

See how to install

Files included (1)

  • SKILL.md2.4 KB

SKILL.md (original)

Review the instructions the agent will receive before you install.

User Perspective (USR)

Evaluates how well the project communicates its purpose and value to users, contributors, and integrators. Assigns a score from 0.0 to 1.0 across three dimensions.

Dimensions

README quality — Can someone discover and use this project?

  • Missing README = 0.0
  • Score = min(readmeLength / 2000, 1.0) — 2000+ chars = full score
  • A thin README (<500 chars) generates a high-priority task

Description — Is the package self-describing?

  • If no package.json exists, marked N/A (not applicable to non-npm projects)
  • If package.json exists: non-empty description field = 1.0, missing or empty = 0.0

Changelog — Is the release history communicated?

  • CHANGELOG.md or CHANGELOG present = 1.0
  • Missing = 0.5 (partial credit — not critical)

Scoring

usr_score = (readme + description + changelog) / 3

Score interpretation:

  • 0.9–1.0 Well-documented and discoverable
  • 0.7–0.9 Good documentation with minor gaps
  • 0.5–0.7 Documentation is present but thin — a new user would struggle
  • 0.0–0.5 Project is effectively undiscoverable — documentation is a blocker

Tasks Generated

FindingPriority
No README.mdcritical
README < 500 charshigh
No package.json description (when package.json exists)medium

Agent Analysis Guide

When performing a manual USR analysis:

  1. Read the README as if you are a new user — can you answer: what is this, how do I install it, how do I use it?
  2. Check for usage examples with real commands or code snippets (not just API reference)
  3. If package.json exists: verify the description field accurately describes what the package does in one line; if no package.json, mark this dimension N/A
  4. Check if there is a CHANGELOG and whether it lists breaking changes for major versions
  5. Look for a CONTRIBUTING.md — if contributors cannot find setup instructions they cannot help
  6. Assess any public API surface: are types and parameters documented?
  7. Identify anything a user would need to know that is not in the docs

Output: gaps in user-facing documentation ranked by impact on onboarding friction, with specific sections or files that need to be written or expanded.

Reviews

No reviews yet. Tell others what you thought.

Comments

No login needed. Share how it worked for you, ask a question, or note where it did not run.

No comments yet. Be the first to write one.

Comments are published right away. Do not include personal information such as email addresses or phone numbers. Up to 2 URLs.

0 / 1,000 characters

This form is protected by reCAPTCHA, and the Google Privacy Policy and Terms of Service apply.

More skills from this repository

Universal guardrails loaded by every agent. Defines Verify Before Reporting (VBR), Write-Ahead Log (WAL), and the security baseline. Always-on, role-independent.

The English summary is being prepared. Showing the original description.

Agistra/agistra.dev5Updated Oct 21, 2026

Use when: architecture mode, architect this, ADR, C4, PlantUML, system boundary, design decision, PRD gap, high ambiguity, multiple technical approaches, security architecture, data architecture, integration risk, implementability gap, story ticket, or epic ticket.

The English summary is being prepared. Showing the original description.

Agistra/agistra.dev5Updated Oct 21, 2026

Use when: assumptions audit, audit assumptions, check for hidden assumptions, plan/ticket has ambiguous scope edges, pre-flight before finalizing a ticket, unstated assumptions, or 'what am I assuming'. Surfaces unstated assumptions, ambiguous scope edges, and untested preconditions in a finished plan/ticket/ADR before it is handed to Builder. Optional pass — Architect judges when to apply it; not a mandatory gate on every ticket.

The English summary is being prepared. Showing the original description.

Agistra/agistra.dev5Updated Oct 21, 2026

Use when: Tester needs UI state evidence for VBR, or Builder needs to verify an integration wire is observable end-to-end. Powered by agent-browser MCP — token-efficient browser automation (200–400 tokens/page).

The English summary is being prepared. Showing the original description.

Agistra/agistra.dev5Updated Oct 21, 2026

Use when drafting a bug or defect ticket, reviewing one someone else wrote, or deciding whether a reported problem is ready to file. Keeps what the reporter actually saw separate from what the agent later found out, so a reader can tell which lines are testimony and which are collected proof. Trigger phrases: 'file a bug', 'write up this defect', 'triage this report', 'is this ticket ready to file', 'what did the reporter actually see'.

The English summary is being prepared. Showing the original description.

Agistra/agistra.dev5Updated Oct 21, 2026

Conducts multi-axis code review. Use before merging any change. Use when reviewing code written by yourself, another agent, or a human. Use when you need to assess code quality across multiple dimensions before it enters the main branch.

The English summary is being prepared. Showing the original description.

Agistra/agistra.dev5Updated Oct 21, 2026

See all skills by Agistra

Report a problem with this skill