diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f19d055
--- /dev/null
+++ b/README.md
@@ -0,0 +1,47 @@
+# parse-semver-ref-action
+
+This action parses a a GitHub ref (e.g. `refs/tags/v1.2.3`) and outputs it's components.
+
+## Inputs
+
+### `ref` _(Required)_
+
+The github ref to parse (e.g. refs/tags/v1.0.0, refs/tags/pkg@v1.2.3).
+
+## Outputs
+
+### `ref`
+
+The ref that was parsed.
+
+### `matched`
+
+`"true"` if the ref matched the semver pattern, `"false"` otherwise.
+
+### `major`
+
+The major version number from the tag (e.g. `1` from `refs/tags/v1.2.3`).
+
+### `minor`
+
+The minor version number from the tag (e.g. `2` from `refs/tags/v1.2.3`).
+
+### `patch`
+
+The patch version number from the tag (e.g. `3` from `refs/tags/v1.2.3`).
+
+### `prerelease`
+
+The prerelease version from the tag (e.g. `alpha` from `refs/tags/v1.2.3-alpha`).
+
+### `build`
+
+The build version from the tag (e.g. `build` from `refs/tags/v1.2.3+build`).
+
+### `name`
+
+The package name from the tag (e.g. `pkg` from `refs/tags/pkg@v1.2.3`).
+
+### `scope`
+
+The package scope (if any) from the tag (e.g. `org` from `refs/tags/@org/pkg@v1.2.3`).
diff --git a/action.yml b/action.yml
index 175f630..a1ecd52 100644
--- a/action.yml
+++ b/action.yml
@@ -1,28 +1,28 @@
-name: 'Parse Ref Semver'
-description: 'Parse a github ref (usually a tag) and extract the semver version, optional package scope, and optional package name'
+name: 'Parse Semver Ref'
+description: 'Parse a github ref (usually a tag) and extract the semver version, optional package scope, and optional package name.'
 inputs:
   ref:
-    description: 'The github ref to parse (e.g. refs/tags/v1.0.0, refs/tags/pkg@v1.2.3)'
+    description: 'The github ref to parse (e.g. refs/tags/v1.0.0, refs/tags/pkg@v1.2.3).'
     required: true
 outputs:
   ref:
-    description: The ref that was parsed
+    description: 'The ref that was parsed'
   matched:
-    description: \"true\" if the ref matched the semver pattern, \"false\" otherwise
-  scope:
-    description: The package scope (if any) from the tag (e.g. @scope/package-name@v1.2.3 -> scope)
-  name:
-    description: The package name (if any) from the tag (e.g. @scope/package-name@v1.2.3 -> package-name)
+    description: '`"true"` if the ref matched the semver pattern, `"false"` otherwise.'
   major:
-    description: The major version from the tag (e.g. v1.2.3 -> 1)
+    description: 'The major version number from the tag (e.g. `1` from `refs/tags/v1.2.3`).'
   minor:
-    description: The minor version from the tag (e.g. v1.2.3 -> 2)
+    description: 'The minor version number from the tag (e.g. `2` from `refs/tags/v1.2.3`).'
   patch:
-    description: The patch version from the tag (e.g. v1.2.3 -> 3)
+    description: 'The patch version number from the tag (e.g. `3` from `refs/tags/v1.2.3`).'
   prerelease:
-    description: The prerelease version from the tag (e.g. v1.2.3-alpha.1 -> alpha.1)
+    description: 'The prerelease version from the tag (e.g. `alpha` from `refs/tags/v1.2.3-alpha`).'
   build:
-    description: The build metadata from the tag (e.g. v1.2.3+build.1 -> build.1)
+    description: 'The build version from the tag (e.g. `build` from `refs/tags/v1.2.3+build`).'
+  name:
+    description: 'The package name from the tag (e.g. `pkg` from `refs/tags/pkg@v1.2.3`).'
+  scope:
+    description: 'The package scope (if any) from the tag (e.g. `org` from `refs/tags/@org/pkg@v1.2.3`).'
 runs:
   using: 'node20'
   main: 'dist/index.js'