Menu
In-code documentation, folder READMEs, and code comments. Use when writing README.md files, JSDoc comments, or explaining code organization.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
TanStack Query integration with wellcrafted's createQueryFactories, defineQuery, and defineMutation. Use when setting up queries/mutations that return Result types or using reactive options and imperative helpers.
Working with Result types, Ok, Err, trySync, tryAsync, and utility functions from wellcrafted. Use when wrapping unsafe code, handling errors with Results, or destructuring { data, error } responses.
Architectural patterns for code that uses wellcrafted. Covers control flow with trySync/tryAsync, factory function composition, service layers with Result types, error composition across boundaries, and the single-or-array pattern.
Type-safe distinct primitives with Brand from wellcrafted. Use when creating nominal types for IDs, tokens, or any primitive that shouldn't be interchangeable.
Define typed, serializable error variants with defineErrors from wellcrafted. Use when creating error types, handling domain errors, or reviewing error definitions.
Human-readable control flow patterns for early returns, guard clauses, and linearizing nested logic. Use when refactoring nested conditionals, replacing try-catch with linear flow, or restructuring decision logic.
| name | documentation |
| description | In-code documentation, folder READMEs, and code comments. Use when writing README.md files, JSDoc comments, or explaining code organization. |
Follow writing-voice for tone.
Documentation explains why, not what. Users can read code to see what it does. They need you to explain the reasoning.
Primary job: explain why this folder exists and the mental model.
ls# Converters
Transform field schemas into format-specific representations.
```
┌─────────────┐ ┌──────────────┐
│ Field Schema│────▶│ to-arktype │────▶ Runtime validation
└─────────────┘ ├──────────────┤
│ to-drizzle │────▶ SQLite columns
└──────────────┘
```
Field schemas are pure JSON Schema objects with `x-component` hints. Each converter takes the same input and produces output for a specific consumer.
# Converters
- `to-arktype.ts` - Converts to ArkType
- `to-drizzle.ts` - Converts to Drizzle
- `index.ts` - Exports
The bad example just lists files without explaining the pattern or when to add new converters.
JSDoc explains when and why to use something, not just what it does.
/**
* Get all table helpers as an array.
*
* Useful for providers and indexes that need to iterate over all tables.
* Returns only the table helpers, excluding utility methods like `clearAll`.
*
* @example
* ```typescript
* for (const table of tables.defined()) {
* console.log(table.name, table.count());
* }
* ```
*/
defined() { ... }
/** Returns all table helpers as an array. */
defined() { ... }
@example blocks with realistic usageComments explain why, not what.
// Y.Doc clientIDs are random 32-bit integers, so we can't rely on ordering.
// Use timestamps from the entries themselves for deterministic sorting.
const sorted = entries.sort((a, b) => a.timestamp - b.timestamp);
// Sort the entries
const sorted = entries.sort((a, b) => a.timestamp - b.timestamp);