diff --git a/.github/workflows/README.md b/.github/workflows/README.md
new file mode 100644
index 0000000..c0615ec
--- /dev/null
+++ b/.github/workflows/README.md
@@ -0,0 +1,84 @@
+# GitHub Actions Workflows
+
+This directory contains reusable and repo-specific GitHub Actions workflows for the privilegedescalation organization.
+
+## Available Tools on Runners
+
+### Always Available
+- `curl` - HTTP client (use this instead of `gh` CLI for API calls)
+- `jq` - JSON processor
+- `bash` - Shell
+- `git` - Version control
+- `docker` / `podman` - Container runtime (depending on runner)
+
+### NOT Available (must install if needed)
+- `gh` CLI - GitHub CLI is **not** pre-installed on runners. Use `curl` with the GitHub API instead.
+
+## Best Practices
+
+### GitHub API Calls
+Instead of using `gh` CLI (which is not installed), use `curl` with the GitHub API:
+
+```yaml
+- name: Set PR label
+  env:
+    GH_TOKEN: ${{ github.token }}
+    REPO: ${{ github.repository }}
+    PR_NUMBER: ${{ github.event.pull_request.number }}
+  run: |
+    curl -sf \
+      -X POST \
+      -H "Authorization: Bearer ${GH_TOKEN}" \
+      -H "Accept: application/vnd.github.v3+json" \
+      "https://api.github.com/repos/${REPO}/issues/${PR_NUMBER}/labels" \
+      -d '{"labels":["label-name"]}'
+```
+
+### Workflow Validation
+Run actionlint locally before pushing:
+
+```bash
+actionlint -color .github/workflows/*.yaml
+```
+
+### Reusable Workflows
+- `plugin-ci.yaml` - Standard CI for Headlamp plugins
+- `plugin-e2e.yaml` - E2E testing for Headlamp plugins
+- `dual-approval-check.yaml` - Checks for CTO and QA approval
+- `detect-pr-pipeline.yaml` - Detects Pipeline A vs Pipeline B based on changed files
+
+## Workflow Naming Convention
+
+- Use kebab-case: `my-workflow.yaml`
+- Be descriptive: `plugin-ci.yaml` not `ci.yaml`
+- For reusable workflows, keep the name clear about its purpose
+
+## Required Gates
+
+All PRs must pass:
+1. `actionlint` validation (workflow YAML syntax)
+2. Shell script validation (if scripts are used)
+3. Any repo-specific CI checks
+
+## Common Patterns
+
+### Getting Changed Files
+Use `tj-actions/changed-files`:
+
+```yaml
+- name: Get changed files
+  id: changed-files
+  uses: tj-actions/changed-files@v44
+  with:
+    files_separator: '\n'
+```
+
+### Setting Job Outputs
+```yaml
+- name: Set output
+  id: detect
+  run: |
+    echo "pipeline-type=pipeline-a" >> $GITHUB_OUTPUT
+```
+
+Access in downstream jobs: `${{ jobs.job-name.outputs.pipeline-type }}`