diff --git a/README.md b/README.md
index e69de29..fbf2016 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,70 @@
+# reusable workflows for 44net git
+
+> [docs](https://docs.github.com/en/actions/using-workflows/reusing-workflows)
+
+## examples
+
+### build a container
+
+from `44net/docker-images`
+
+```yml
+jobs:
+  build-debian-base:
+    uses: actions/workflows/.gitea/workflows/build_container.yml@master
+    env:
+      IMAGE_NAME: debian-base
+    with:
+      registry: ${{ env.REGISTRY }}
+      image-name: ${{ env.IMAGE_OWNER }}/${{ env.IMAGE_NAME }}
+      context: ${{ env.IMAGE_NAME }}
+      dockerfile: ${{ env.IMAGE_NAME }}/Dockerfile
+      platforms: linux/amd64,linux/arm64
+    secrets:
+      cr-username: ${{ secrets.CR_USERNAME }}
+      cr-password: ${{ secrets.CR_PASSWORD }}
+```
+
+### run tests (python)
+
+from `44net/fftools`
+
+```yml
+jobs:
+  check-code:
+    uses: actions/workflows/.gitea/workflows/check_python_hatch.yml@master
+    with:
+      run-tests: true
+```
+
+### scan with sonar-scanner (python)
+
+from `44net/fftools`
+
+```yml
+jobs:
+  scan-code:
+    uses: actions/workflows/.gitea/workflows/sonarqube_python.yml@master
+    needs: [check-code]
+    if: gitea.event_name != 'pull_request'
+    with:
+      coverage: true
+    secrets:
+      sonar-host: ${{ secrets.SONARQUBE_HOST }}
+      sonar-token: ${{ secrets.SONARQUBE_TOKEN }}
+```
+
+### build and release package (python)
+
+from `44net/fftools`
+
+```yml
+jobs:
+  build-pypackage:
+    uses: actions/workflows/.gitea/workflows/release_pypackage.yml@master
+    with:
+      repository: https://git.44net.ch/api/packages/44net/pypi
+    secrets:
+      username: actions-bot
+      token: ${{ secrets.PACKAGE_TOKEN }}
+```