better-result skills for agents
better-result
Two better-result skills: an error-handling audit of a TypeScript project with step-by-step Result adoption, and a 2.x to 3.0 migration with a codemod
- 2,002 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The adoption skill edits the project's source code and runs formatting, lint, type check and test commands
- The migration script writes changes to project files with the `--write` flag
- The audit branch writes a report file into the repository documentation
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/better-resultDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The adoption skill edits the project's source code and runs formatting, lint, type check and test commands
- The migration script writes changes to project files with the `--write` flag
- The audit branch writes a report file into the repository documentation
This is third-party code. Review the repository files before installing.
What it does
better-result is a zero-dependency `Result` type library for TypeScript: a function explicitly returns a success or an expected error, and `Result.gen` composes steps into a linear chain that stops at the first failure. The repository holds two skills that help an agent bring it into someone else's project. The `adopt-better-result` skill works in two branches. In the audit branch the agent reads repository instructions and manifests, checks the installed version and API, walks every area of production code, keeps a report of the failure paths it finds, assigns each a disposition (expected error, defect or other), decides on transport boundaries and ranks vertical migration slices. The only repository change at this stage is the report file in the repository's established documentation location, falling back to `docs/better-result-adoption.md`. The slice branch starts only after explicit approval of one named slice: the agent traces the failure path from source to handling point, converts it to `Result` and `TaggedError`, runs formatting, lint, type checks and tests and recommends the next slice. The `migrate-better-result-3` skill moves a project from version 2.x to 3.0. The agent inventories affected sites, runs the `migrate-tagged-error-v3.mjs` script with `--list`, `--write` and `--check` to replace the `TaggedError` syntax, moves removed serialization helpers to validated codecs, works through changed type inference in `tryRecover`, `matchError` and `Result.partition`, updates the dependency and runs tests.
Who it is for. For TypeScript developers who want to move a project's error handling to a typed `Result` step by step or update a project already using the library from version 2.x.
Good fit when
- You want to see where errors are lost or mixed in a project and get an adoption plan for `Result` with a queue of slices
- You decided to move one module or boundary to `Result` and the agent should carry the slice from the failure source to handling
- A project uses better-result 2.x and has to move to 3.0 without breaking call behavior
- You want to replace the version 2 `TaggedError` syntax automatically and verify nothing is left
- You need to replace the removed `Result.serialize`, `Result.deserialize` and `Result.hydrate` with schema codecs
Not a fit when
- The project is not TypeScript: the library requires TypeScript 5.4 or newer and ships only as ESM
- You want to rewrite the whole project in one go: the adoption skill deliberately works in slices and waits for approval of each
- You want a ready library with no discussion: the skills only help adoption, and the library itself installs separately with `npm install better-result`
- The project is already built on Effect: it has its own approach to errors and the better-result skills do not apply
Example request
Audit error handling in this repository with the adopt-better-result skill and suggest which slice to start adopting Result fromLimitations
The skills target TypeScript projects and better-result versions 2.x and 3.0. The audit branch does not change production code: it writes only a report and stops at approval, so a second request naming a slice is needed before adoption. The `migrate-better-result-3` script changes only the `TaggedError` inheritance shape, and annotations like `TaggedErrorClass<Tag, Props>` have to be fixed by hand. Generated and vendored code is left alone.
After the upgrade, `Result` trees holding `TaggedError` errors can no longer be compared structurally in tests because the errors became iterable; split such checks into status and error fields. For internal exchange between your own services `serializeUnsafe` and `deserializeUnsafe` can be used: they panic on a contract violation. At public and persisted boundaries the skill recommends the safe methods. MIT license.
How to disable. Remove the skills from the agent's skills folder. The library stays in the project: uninstall it with your package manager, for example `npm uninstall better-result`, and revert the changes made by slices through Git history. Delete the `docs/better-result-adoption.md` report by hand.
FAQ
Which errors count as expected and which as defects?
An expected error is one the calling code can react to meaningfully: invalid input, a missing record, rejected credentials, an unavailable upstream service, a validation failure at a boundary. Unexpected callback failures and broken invariants are represented by the library as `Panic`, instead of widening the error type to `unknown`.
What is a vertical slice?
One failure path from its source through the calling functions to the place where it is handled or passed across a boundary. The skill converts that whole path to `Result`, not scattered individual functions, and only after approval of a named slice.
How do I install the library and what does it need?
With `npm install better-result`; `pnpm add` and `bun add` also work. It needs TypeScript 5.4 or newer, the package is ESM-only and has no runtime dependencies. Documentation lives at better-result.dev.
How do I check that the syntax migration is finished?
Run `migrate-tagged-error-v3.mjs` with `--check`: it exits successfully when no version 2 factory calls remain. The skill also asks you to search for leftover two-argument `TaggedErrorClass` uses, excluding generated and vendored files.
Why is there an audit-better-result-dependents skill in the repository?
It lives in `.agents/skills` and is for maintainers: it checks whether an API change breaks known dependent projects from Prisma and Better T Stack. It is not meant for library users and is not in the install list.
Discussion
No questions or reviews yet.
Related
SkillsAn Effect v4 skill for TypeScript: schemas, services and layers, config, retries, caches, streams, the HTTP client and tests with virtual time
An agent skill with TypeScript conventions: types, discriminated unions, functions, naming, source layout, React and tests, loaded per topic
The /improve skill: a strong model audits a repository and writes self-contained fix plans, and you hand the execution to a cheaper model
A Rust CLI for TypeScript and JavaScript: dead code, duplicates, cycles, complexity and architecture boundaries from one graph, plus MCP and skills
Oxc migration skills for Oxlint and Oxfmt
Oxc migration skills
Two official Oxc skills: the agent moves a project from ESLint to the Oxlint linter and from Prettier or Biome to the Oxfmt formatter
A code review skill across many languages and frameworks: architecture, performance, security, anti-patterns and common bugs
README in short
The library description starts with a port validation example and three principles: make failures explicit, write multi-step workflows in order, and keep expected errors apart from defects. It then covers the mental model, a step-by-step checkout built on `Result.gen`, transformations, recovery, retries, collections and transport boundaries, an API map, migration from version 2 and an agents section linking to the adoption skill. A separate file in the skills folder explains installation and manual setup. The repository holds type and runtime tests, a documentation site and research notes.
README badge
Original SKILL.md
--- name: adopt-better-result description: Adopt better-result in an existing TypeScript codebase. Use for a repository-wide error-handling audit and proposal, or for implementing a named vertical slice with TaggedError and Result. --- # Adopt better-result Start with evidence, then work at the scale named by the user. ## Choose the branch - **Audit branch:** Use when the user requests a repository-wide audit or proposal, or has not named an implementation slice. Complete the audit branch before changing production code. - **Named-slice branch:** Use when the user explicitly requests implementation of a function, module, boundary, or previously proposed slice. Limit evidence collection to that slice and its propagation path. An approved slice from the audit branch continues through the named-slice branch. ## Audit branch: repository-wide proposal ### 1. Establish the repository and API facts Read the repository instructions, package manifests, source layout, test commands, and architecture documentation. Determine whether `better-result` is installed and which version/API is available. Prefer installed types and source over remembered APIs. Map every production-code area before studying individual failures. Exclude generated and vendored code from the audit; inspect tests for intended behavior. **Complete when:** every production-code area is listed, the validation commands are known, and the available `better-result` API has been verified. ### 2. Audit every production-code area Follow [`references/repository-audit.md`](references/repository-audit.md). Trace search evidence into end-to-end failure paths, keep grouped sites accountable with counts, and record obscured paths as unknown. Write the audit to the repository's established documentation or planning location, falling back to `docs/better-result-adoption.md`. **Complete when:** the report satisfies the coverage and completion requirements in `repository-audit.md`. ### 3. Design the target model Apply the failure taxonomy in [`references/tagged-errors.md`](references/tagged-errors.md) and make each boundary decision with [`references/result-boundaries.md`](references/result-boundaries.md). Add the proposed dispositions, user-facing mappings, boundary decisions, and ranked vertical migration slices to the report. Recommend the best first slice and explain why it is bounded and valuable. **Complete when:** every catalogued failure has a disposition, every boundary has a recorded codec decision, and one first slice is recommended. ### 4. Present the approval gate Present the report and recommendation. The audit branch's only repository change is the report. **Complete when:** the report is presented. An explicit approval of one named vertical slice starts the implementation branch; otherwise the run ends here. ## Named-slice branch: implementation