diff --git a/prompts/seed-cli.md b/prompts/seed-cli.md
index 32d262c..a2f3160 100644
--- a/prompts/seed-cli.md
+++ b/prompts/seed-cli.md
@@ -151,7 +151,7 @@ After the repo is pushed to GitHub:
    | macOS notarization | 5 secrets in `release` environment |
    | Homebrew tap | `secrets.HOMEBREW_TAP_TOKEN` |
    | AUR publish | `secrets.AUR_SSH_KEY` |
-   | Skills sync | `vars.SKILLS_APP_ID` + `secrets.SKILLS_APP_PRIVATE_KEY` |
+   | Skills sync | `vars.SKILLS_APP_ID` + `secrets.SKILLS_APP_PRIVATE_KEY` (App installation needs Contents: write + Issues: write on `basecamp/skills`; token creation fails if either is missing) |
 
    All features are off by default and degrade gracefully.
 
diff --git a/seed/RELEASING.md.tmpl b/seed/RELEASING.md.tmpl
index 707e1af..1aba6bc 100644
--- a/seed/RELEASING.md.tmpl
+++ b/seed/RELEASING.md.tmpl
@@ -71,6 +71,13 @@ vars are added.
 | `SKILLS_APP_ID` (var) | GitHub App ID for skills sync (optional) |
 | `SKILLS_APP_PRIVATE_KEY` | GitHub App private key for skills sync (optional) |
 
+The skills-sync App installation must grant **Contents: write** and
+**Issues: write** on `basecamp/skills` — the workflow requests both
+(`permission-contents` / `permission-issues`), and token creation fails
+outright if a requested permission is missing from the installation.
+Existing Apps set up with Contents only need the added Issues permission
+and the installation update approved before sync works again.
+
 **Environment secrets** (`release` environment — Settings > Environments):
 
 | Secret | Purpose |