diff --git a/.github/workflows/check-plugin-structure.yml b/.github/workflows/check-plugin-structure.yml
index 97780e63..e71b3503 100644
--- a/.github/workflows/check-plugin-structure.yml
+++ b/.github/workflows/check-plugin-structure.yml
@@ -75,6 +75,10 @@ jobs:
             }
 
             if (errors.length > 0) {
+              const prBranch = context.payload.pull_request.head.ref;
+              const prRepo = context.payload.pull_request.head.repo.full_name;
+              const isFork = context.payload.pull_request.head.repo.fork;
+
               const body = [
                 '⚠️ **Materialized files or symlinks detected in plugin directories**',
                 '',
@@ -83,9 +87,32 @@ jobs:
                 '- `README.md`',
                 '',
                 'Agent, command, and skill files are copied in automatically when publishing to `main`.',
-                'Please remove the following:',
                 '',
+                '**Issues found:**',
                 ...errors.map(e => `- ${e}`),
+                '',
+                '---',
+                '',
+                '### How to fix',
+                '',
+                'It looks like your branch may be based on `main` (which contains materialized files). Here are two options:',
+                '',
+                '**Option 1: Rebase onto `staged`** (recommended if you have few commits)',
+                '```bash',
+                `git fetch origin staged`,
+                `git rebase --onto origin/staged origin/main ${prBranch}`,
+                `git push --force-with-lease`,
+                '```',
+                '',
+                '**Option 2: Remove the extra files manually**',
+                '```bash',
+                '# Remove materialized files from plugin directories',
+                'find plugins/ -mindepth 2 -maxdepth 2 -type d \\( -name agents -o -name commands -o -name skills \\) -exec rm -rf {} +',
+                '# Remove any symlinks',
+                'find plugins/ -type l -delete',
+                'git add -A && git commit -m "fix: remove materialized plugin files"',
+                'git push',
+                '```',
               ].join('\n');
 
               await github.rest.pulls.createReview({