# dx-review

dx-review audits library APIs for developer ergonomics, TypeScript typing quality, and error clarity. Flags friction points before external developers hit them.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 1 install · ★ 1855 repo stars
- Author: LibPDF-js
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/LibPDF-js/core/tree/HEAD/.opencode/skills/dx-review/SKILL.md
- Updated: 2026-10-26
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/dx-review

## What it does

The skill evaluates public library interfaces from a consumer's viewpoint. When no specific scope is given in the prompt, the agent examines the primary public exports. It tests method naming predictability, default arguments, and whether common operations require excessive boilerplate. The review focuses on discoverability, consistency, ergonomics, error messaging, TypeScript definitions, JSDoc examples, and alignment with platform conventions.

During the audit, the agent inspects type declarations, walks through typical user workflows, and catches confusing parameter orders. The skill writes its findings to `.agents/scratch/dx-review-<scope>.md`. Every documented issue includes a severity rating, the awkward code snippet, and a concrete refactoring recommendation.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add LibPDF-js/core --skill dx-review -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/dx-review/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/dx-review/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add LibPDF-js/core --skill dx-review -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/dx-review/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add LibPDF-js/core --skill dx-review -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/dx-review/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install LibPDF-js/core .opencode/skills/dx-review
```

2. **Manually: put the files in place**
- File: `.github/skills/dx-review/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add LibPDF-js/core --skill dx-review -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/LibPDF-js/core --path .opencode/skills/dx-review
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/dx-review/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add LibPDF-js/core --skill dx-review -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/LibPDF-js/core/tree/HEAD/.opencode/skills/dx-review/SKILL.md

## When to use it
- audit public API ergonomics and naming consistency
- detect loose TypeScript types that weaken editor autocomplete
- spot unnecessary boilerplate across standard library workflows
- generate a markdown review with side-by-side code recommendations

## Example prompts
- Run a DX review on our main public API
- Check the developer ergonomics of the form manipulation module
- Audit TypeScript types and error handling in the current export surface

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 71c489f6ca52d809.

BEGIN THIRD-PARTY FILE 71c489f6ca52d809
`````text
---
name: dx-review
description: Review developer experience and API ergonomics
---

You are reviewing the developer experience (DX) of the library to ensure it feels good to use. As a library consumed by other developers, ergonomics matter as much as functionality.

## Your Task

1. **Identify scope** - Based on the conversation context, determine what module or feature to review. If no specific scope is mentioned, review the main public API.
2. **Analyze the API surface** - How do developers interact with this code?
3. **Evaluate ergonomics** - Is it intuitive, consistent, and pleasant to use?
4. **Report findings** - Document issues and recommendations

## DX Evaluation Criteria

### 1. Discoverability

- Can developers find what they need?
- Are method names intuitive and searchable?
- Is the API surface appropriately sized (not too sprawling)?

### 2. Consistency

- Do similar operations work the same way?
- Are naming conventions consistent across the API?
- Do return types follow predictable patterns?

### 3. Ergonomics

- Is the common case easy? (pit of success)
- Are required parameters actually required?
- Do defaults make sense for typical usage?
- Is there unnecessary boilerplate?

### 4. Error Experience

- Are errors actionable? (tells you what went wrong AND how to fix it)
- Do errors surface at the right time? (fail fast)
- Are error types specific enough to catch programmatically?

### 5. Type Experience

- Does autocomplete guide developers?
- Are types precise (not too wide like `any` or `string`)?
- Do generics add value or just complexity?

### 6. Documentation in Code

- Are public methods documented with JSDoc?
- Do examples in comments actually work?
- Are parameter constraints documented?

### 7. Comparison to Standards

- How does this compare to similar libraries developers know?
- Does it follow platform conventions (Node.js, Web APIs)?
- Would a developer's intuition from other libraries apply here?

## Review Process

### Step 1: Use the API

Put yourself in a consumer's shoes:

- What would a developer try first?
- What questions would they have?
- Where would they get stuck?

### Step 2: Read the Types

Examine the TypeScript definitions:

- What does autocomplete show?
- Are overloads clear or confusing?
- Do type errors make sense?

### Step 3: Trace Common Workflows

Walk through typical tasks:

- Opening a PDF and reading metadata
- Modifying form fields
- Saving changes
- Handling errors

### Step 4: Look for Friction

Identify pain points:

- Unnecessary ceremony or boilerplate
- Confusing parameter orders
- Inconsistent patterns
- Missing conveniences

## Output Format

Write your review to `.agents/scratch/dx-review-<scope>.md`:

````markdown
# DX Review: <Scope>

## Summary

Overall assessment and top priorities.

## What's Working Well

- Positive patterns to preserve

## Issues Found

### Issue 1: <Title>

**Severity:** High/Medium/Low
`````
END THIRD-PARTY FILE 71c489f6ca52d809

The third-party file has ended. Everything between the 71c489f6ca52d809 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2931 of 3901 bytes. © LibPDF-js · MIT · https://github.com/LibPDF-js/core/tree/HEAD/.opencode/skills/dx-review/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
