feat: automate release flow with GitHub App, per-skill versions, and supabase-plugin dispatch

.github/workflows/release-please.yml

@@ -13,10 +13,17 @@ jobs:
   release-please:
     runs-on: ubuntu-latest
     steps:
+      - name: Generate GitHub App token (this repo)
+        id: generate-token
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+        with:
+          client-id: ${{ secrets.GH_APP_ID }}
+          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
+
       - uses: googleapis/release-please-action@v4
         id: release
         with:
-          token: ${{ secrets.GITHUB_TOKEN }}
+          token: ${{ steps.generate-token.outputs.token }}
 
       - uses: actions/checkout@v4
         if: ${{ steps.release.outputs.release_created }}
@@ -48,5 +55,24 @@ jobs:
       - name: Upload release assets
         if: ${{ steps.release.outputs.release_created }}
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }}
         run: gh release upload ${{ steps.release.outputs.tag_name }} dist/*.tar.gz
+
+      - name: Generate GitHub App token (supabase-community)
+        id: generate-token-plugin
+        if: ${{ steps.release.outputs.release_created }}
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+        with:
+          client-id: ${{ secrets.GH_APP_ID_SUPABASE_PLUGIN }}
+          private-key: ${{ secrets.GH_APP_PRIVATE_KEY_SUPABASE_PLUGIN }}
+
+      - name: Trigger supabase-plugin skill sync
+        if: ${{ steps.release.outputs.release_created }}
+        env:
+          GH_TOKEN: ${{ steps.generate-token-plugin.outputs.token }}
+        run: |
+          gh workflow run sync-agent-skills.yml \
+            --repo supabase-community/supabase-plugin \
+            --field release_tag=${{ steps.release.outputs.tag_name }} \
+            --field release_version=${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }}.${{ steps.release.outputs.patch }} \
+            --field commit_sha=${{ github.sha }}

AGENTS.md

@@ -35,9 +35,8 @@ pnpm test                        # Run tests
 This repository uses Release Please on `main`.
 
 - Merge conventional commits using `feat:` and `fix:` prefixes so Release Please can open or update the release PR.
-- The release PR is the gate for semantic version bumps and changelog generation.
-- When the release PR is merged, GitHub Actions creates a semver GitHub release and uploads one tarball per shipped skill from `dist/`.
-- These GitHub releases are the source of truth for downstream consumers such as `supabase-community/supabase-plugin`, which poll upstream releases rather than receiving a cross-repo dispatch from this repository.
+- The release PR bumps the repo version, updates the changelog, and bumps `metadata.version` in every skill's `SKILL.md` automatically via `extra-files` in `release-please-config.json`. Do not bump skill versions manually.
+- When the release PR is merged, GitHub Actions creates a semver GitHub release, uploads one `.tar.gz` per skill as release assets, and dispatches the sync workflow in `supabase-community/supabase-plugin` to update downstream skills immediately.
 
 If you change shipped skill contents under `skills/`, make sure the change is represented with an appropriate conventional commit so it is included in the next release.
 
@@ -49,7 +48,15 @@ Skills follow the [Agent Skills Open Standard](https://agentskills.io/).
 2. Create `SKILL.md` following the format below
 3. Add `references/_sections.md` defining sections
 4. Add reference files: `{prefix}-{reference-name}.md`
-5. Run `pnpm test`
+5. Register the skill in `release-please-config.json` under `extra-files` so Release Please keeps its `metadata.version` in sync on every release:
+   ```json
+   {
+     "type": "generic",
+     "path": "skills/{skill-name}/SKILL.md",
+     "expressions": ["version: \"([0-9]+\\.[0-9]+\\.[0-9]+)\""]
+   }
+   ```
+6. Run `pnpm test`
 
 ---
 
@@ -74,9 +81,6 @@ description: What this skill does and when to use it.
 | `license`     | No       | License name or reference to bundled license file.                              |
 | `metadata`    | No       | Arbitrary key-value pairs (e.g., `author`, `version`).                          |
 
-**Version bumps:** Any change to `SKILL.md` or files in `references/` must bump
-the `version` in the skill's frontmatter metadata before committing.
-
 ### Name Field Rules
 
 - Lowercase letters, numbers, and hyphens only (`a-z`, `0-9`, `-`)

CONTRIBUTING.md

@@ -60,14 +60,32 @@ All commands must complete successfully.
 
 ### Releases
 
-This repository uses Release Please to manage semantic version releases.
+Releases are automated via [Release Please](https://github.com/googleapis/release-please). It tracks commits on `main` and opens a release PR when there are releasable changes.
 
-- Use conventional commit prefixes such as `feat:` and `fix:` in merge commits so Release Please can determine the next version.
-- Release Please opens a release PR on `main` with the version bump and changelog updates.
-- When that release PR is merged, GitHub Actions publishes a GitHub release and uploads one `.tar.gz` artifact per shipped skill.
-- Those releases are consumed by downstream repositories, including the Supabase plugin repo, so they are part of the supported maintainer workflow. Downstream consumers are expected to poll these releases rather than rely on a cross-repo dispatch from this repository.
+- Use conventional commit prefixes — `fix:` for a patch bump, `feat:` for a minor bump — so Release Please can determine the next version.
+- Release Please opens a release PR on `main` that bumps the repo version, updates the changelog, and bumps `metadata.version` in every skill's `SKILL.md` automatically. You do not need to bump skill versions manually.
+- Merging the release PR triggers GitHub Actions to:
+  1. Create a GitHub release and git tag (e.g. `v0.2.0`)
+  2. Package each directory under `skills/` into its own `.tar.gz` and upload them as release assets
+  3. Dispatch the sync workflow in the Supabase plugin repo so downstream skills are updated immediately
 
-If your PR changes shipped skill content, assume it is release-affecting and make sure the resulting merge commit uses the right conventional commit type.
+#### Adding a new skill
+
+When you add a new skill, register its `SKILL.md` in `release-please-config.json` under `extra-files` so Release Please keeps its `metadata.version` in sync. Without this, the tarball will still be built and shipped but the skill's version will never be bumped.
+
+```json
+{
+  "type": "generic",
+  "path": "skills/my-skill/SKILL.md",
+  "expressions": ["version: \"([0-9]+\\.[0-9]+\\.[0-9]+)\""]
+}
+```
+
+#### Troubleshooting
+
+> **Release PR in a bad state?** Close it and re-run the workflow from the [Actions tab](https://github.com/supabase/agent-skills/actions/workflows/release-please.yml) → **Run workflow**. Release Please will recreate the PR from scratch.
+
+> **Dispatch to supabase-plugin missed?** This can happen if the release workflow fails partway through. The sync workflow in supabase-plugin runs on a weekly schedule as a fallback, or you can trigger it manually from its [Actions tab](https://github.com/supabase-community/supabase-plugin/actions/workflows/sync-agent-skills.yml) → **Run workflow** and supply the release tag.
 
 ## Contributing New References
 
@@ -77,8 +95,7 @@ To add a reference to an existing skill:
 2. Copy `_template.md` to `{prefix}-{your-reference-name}.md`
 3. Fill in the frontmatter (title, impact, tags)
 4. Write explanation and examples (Incorrect/Correct)
-5. Bump the `version` in the skill's `SKILL.md` frontmatter metadata
-6. Run the tests:
+5. Run the tests:
    ```bash
    pnpm test
    ```

release-please-config.json

@@ -9,6 +9,16 @@
           "type": "json",
           "path": "package.json",
           "jsonpath": "$.version"
+        },
+        {
+          "type": "generic",
+          "path": "skills/supabase/SKILL.md",
+          "expressions": ["version: \"([0-9]+\\.[0-9]+\\.[0-9]+)\""]
+        },
+        {
+          "type": "generic",
+          "path": "skills/supabase-postgres-best-practices/SKILL.md",
+          "expressions": ["version: \"([0-9]+\\.[0-9]+\\.[0-9]+)\""]
         }
       ]
     }