Guide · Agent skill
How to use the Migrate to Shoehorn agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The migrate-to-shoehorn skill tells an AI agent to rewrite TypeScript test files that use `as` type casts to fake data, swapping them for helpers from the @total-typescript/shoehorn library. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and where it should not be used. By the end you will know how to run the migration on a TypeScript test suite and check the result with your type checker.
Migrate to Shoehornmattpocock/skills · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ for all projects or in a project's .claude/skills/ folder.
- 2Or upload it in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
- 3Install the library. Run npm i @total-typescript/shoehorn in your TypeScript project.
- 4Ask for the migration. Make a request that mentions shoehorn or replacing `as` in tests. The agent will ask which files and which cases to cover.
- 5Let the agent find the casts. The agent searches *.test.ts and *.spec.ts files for `as` assertions using grep.
- 6Replace the casts. The agent swaps `as Type` for fromPartial() and `as unknown as Type` for fromAny(), and adds imports.
- 7Run the type check. Run your project's type check command to confirm the migrated tests compile.
What the migrate-to-shoehorn skill makes the agent do
The skill is for test code only. It targets TypeScript test files that use `as` assertions to pass fake data, such as `{ body: { id: "123" } } as Request`. The source says these casts are a problem because they are easy to misuse, you must specify the target type by hand, and intentionally wrong data needs the double cast `as unknown as Type`.
The agent replaces these casts with three helpers from @total-typescript/shoehorn: `fromPartial()` for partial data that still type-checks, `fromAny()` for deliberately wrong data, and `fromExact()` to require a full object.
- Large objects where a test only needs a few properties: wrap the partial object in `fromPartial()`.
- `as Type` casts: replace with `fromPartial()`.
- `as unknown as Type` casts: replace with `fromAny()`.
- `fromExact()` forces a full object and can be swapped in for `fromPartial()` later.
Install the agent skill (ZIP or project folder)
Download the ZIP for this skill from this page and unzip it. To make the skill available to Claude Code for all your projects, place the unzipped skill folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder.
In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.
- Personal (all projects): ~/.claude/skills/
- Single project: .claude/skills/ inside the project
- Claude apps: Settings → Capabilities → Skills, then upload
Install the shoehorn library
The skill's install step uses npm. The agent can run this for you, or you can run it yourself in the project root. You need Node.js and npm, and a TypeScript project with a type check command.
npm i @total-typescript/shoehornTrigger the skill with natural requests
You do not need a special command. The skill description says it applies when you mention shoehorn, ask to replace `as` in tests, or need partial test data. The agent will then ask you a few questions before changing files.
The agent asks which test files have `as` assertions causing problems, whether the objects are large with only some properties mattering, and whether you need to pass intentionally wrong data for error testing.
- "Migrate the tests in this repo from `as` casts to shoehorn."
- "Replace the `as Request` casts in the user service tests with fromPartial."
- "I need partial test data for these large config objects. Can shoehorn help?"
- "Some tests pass wrong types on purpose. Switch those to shoehorn's fromAny."
What the agent does during the migration
The skill's workflow has the agent install the package, find test files containing `as` assertions with a search command, replace each cast with the matching helper, add the imports from `@total-typescript/shoehorn`, and run a type check to verify the result.
The search command the skill uses is shown below. It looks in files named *.test.ts and *.spec.ts.
- Install the package.
- Find casts with grep.
- Replace `as Type` with `fromPartial()` and `as unknown as Type` with `fromAny()`.
- Add the imports.
- Run your type check.
grep -r " as [A-Z]" --include="*.test.ts" --include="*.spec.ts"Example: migrating a request test
Take a test that passes a large Request type but only uses `body.id`. Before, the test had to fake every property. After, it wraps only the needed part in `fromPartial()`, so the other properties do not have to be written out.
For intentionally invalid input, the skill uses `fromAny()` instead of the double cast. The source notes that this keeps autocomplete.
import { fromPartial } from "@total-typescript/shoehorn";
it("gets user by id", () => {
getUser(
fromPartial({
body: { id: "123" },
}),
);
});Safety notes and limits
The skill itself says shoehorn must never be used in production code, because it bypasses type checking. Keep the helpers inside test files only.
Note that `fromPartial` relaxes the check for missing fields. If your team relies on the type checker to catch incomplete test data, this migration may weaken that. The skill's listed requirements say it runs no scripts and uses no network access beyond what the npm install step needs. Review the agent's changes before committing.
- Do not use shoehorn in production code.
- Use `fromExact()` where you want the type checker to demand a full object.
- The skill runs no scripts itself, according to its listing; the agent still runs npm and grep commands during the workflow.
Tips for a clean migration
Start with one test file, run your type check, and confirm the result before moving on to the rest of the suite. Ask the agent to find casts first and show you the list so you can decide which ones to convert.
- Migrate one directory at a time.
- Use `fromExact()` for tests where missing fields should still be an error.
- Keep `fromAny()` for the few cases that need deliberately wrong data.
What people use it for
- Replacing `as Request` casts in API handler tests with fromPartial so only the fields under test are written out.
- Passing partial configuration objects to functions whose config type has many required properties.
- Writing error-handling tests that pass deliberately malformed input using fromAny.
- Auditing a test suite for `as` casts with a grep search before a refactor.
Frequently asked questions
How do I install the migrate to shoehorn skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
What does @total-typescript/shoehorn need to run?
The source lists Node.js and npm, a TypeScript project with a type check command, and the @total-typescript/shoehorn npm package. You install the package with npm i @total-typescript/shoehorn.
Is the migrate to shoehorn skill free?
The skill is listed under the MIT licence. The source does not mention pricing for it, so check the licence file in the repository for the terms.
Can I use shoehorn in production code?
No. The skill itself says shoehorn is for test code only, because it bypasses type checking.
What is the difference between fromPartial and fromAny?
fromPartial() passes partial data that still type-checks. fromAny() passes intentionally wrong data for error tests and keeps autocomplete, according to the skill's table.
Does the skill work for projects that do not use TypeScript?
No. The source says the migration has no meaning in projects that do not use TypeScript.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits TypeScript teams whose test files are full of `as` casts, especially with large request or config types where tests only need a few properties. Skip it for production code, non-TypeScript projects, or test suites that depend on the type checker to flag missing fields, since fromPartial relaxes that check.
Download the skill