diff --git a/workflow-parser/README.md b/workflow-parser/README.md
new file mode 100644
index 0000000..5045e00
--- /dev/null
+++ b/workflow-parser/README.md
@@ -0,0 +1,79 @@
+# actions/workflow-parser
+
+`@actions/workflow-parser` is a library to parse GitHub Actions [workflows](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions).
+
+## Installation
+
+The [package](https://www.npmjs.com/package/@actions/workflow-parser) contains TypeScript types and compiled ECMAScript modules.
+
+```bash
+npm install @actions/workflow-parser
+```
+
+## Usage
+
+The parser is driven by a custom schema defined in [`worflows-v1.0.json`](./src/workflow-v1.0.json).
+
+### Simple example
+
+`parseWorkflow` parses the workflow YAML into an intermediate representation and validates that it conforms to the schema. Any parsing errors are returned in the `errors` property of the result context.
+
+```typescript
+var trace: TraceWriter;
+
+const result = parseWorkflow(
+  {
+    name: "test.yaml",
+    content: `on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - run: echo 'hello'`
+  },
+  trace
+);
+```
+
+`convertWorkflowTemplate` then takes that intermediate representation and converts it to a [`WorkflowTemplate`](./src/workflow-template.ts) object, which is a more convenient representation for working with workflows.
+
+```typescript
+const workflowTemplate = await convertWorkflowTemplate(result.context, result.value);
+
+// workflowTemplate.jobs[0].id === "build"
+// workflowTemplate.jobs[0].steps[0].run === "echo 'hello'"
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+or to watch for changes
+
+```bash
+npm run watch
+```
+
+### Test
+
+```bash
+npm test
+```
+
+or to watch for changes and run tests:
+
+```bash
+npm run test-watch
+```
+
+### Lint
+
+```bash
+npm run format-check
+```
+
+## License
+
+This project is licensed under the terms of the MIT open source license. Please refer to [MIT](../LICENSE) for the full terms.