diff --git a/.github/styles/vocab.txt b/.github/styles/vocab.txt
index 5b8624c97f..4ff766e5e2 100644
--- a/.github/styles/vocab.txt
+++ b/.github/styles/vocab.txt
@@ -38,6 +38,8 @@ codeblocks
 Codecov
 codehilite
 Codehilite
+codemod
+codemods
 codeowners
 composability
 composable
diff --git a/packages/codemods/README.md b/packages/codemods/README.md
index 139213c0c1..0679bed74d 100644
--- a/packages/codemods/README.md
+++ b/packages/codemods/README.md
@@ -1,22 +1,24 @@
-# e2e-test
+# @backstage/codemods
 
-End-to-end test for verifying Backstage packages.
+A collection of codemods for use with Backstage projects.
 
 ## Usage
 
-This package is only meant for usage within the Backstage monorepo.
+This package is a wrapper around [`jscodeshift`](https://github.com/facebook/jscodeshift) with some included transforms. The transforms can either be executed via the included CLI or directly via `jscodeshift`.
 
-All packages need to be installed and built before running the test. In a fresh clone of this repo you first need to run the following from the repo root:
+To run the `core-imports` codemod towards all source files in a package, run the following:
 
 ```sh
-yarn install
-yarn tsc
-yarn build
+npx @backstage/codemods core-imports .
 ```
 
-Once those tasks have completed, you can now run the test using `yarn e2e-test run`.
+Note that this will modify the source files directly, but it's possible to do a dry-run by adding the `--dry` flag.
 
-If you make changes to other packages you will need to rerun `yarn tsc && yarn build`. Changes to this package do not require a rebuild.
+The transforms are located within the `transforms/` directory in this package, so running directly with `jscodeshift` looks like this:
+
+```sh
+npx jscodeshift --parser=tsx --extensions=tsx,js,ts,tsx --transform=node_modules/@backstage/codemods/transforms/core-imports.js .
+```
 
 ## Documentation