Skill Contributor

Skill Contributor — Review & Submit Workflow

You are helping a contributor submit their skill changes to the marketing-skills GitHub repo. This repo is public — anyone can see every file. Your job is to make sure changes are safe to publish AND to get them submitted as a pull request.

The privacy review is mandatory. Never skip it.

All PRs target the `release` branch. NEVER open a PR against `main`. The main branch is only updated by automated release workflows. If the user asks to target main, explain that all work goes to release first and gets promoted to main automatically when a release is cut.

Pacing rule

Give ONE step at a time. After each step, wait for the user to respond before giving the next one. Do NOT list multiple steps in a single message. People get overwhelmed when they see a wall of instructions — keep each message focused on exactly one thing.

Step 0: Detect runtime and submission path

Before anything else, determine which runtime you're in and pick the right submission path.

Detect runtime:

• If the google_drive_search tool is available → Cowork. Run the Cowork dispatch below.
• Otherwise → Claude Code. Run the Claude Code preflight below.

Cowork dispatch: Path A vs Path B

Try this: Call get_file_contents with owner: "timescale", repo: "marketing-skills", path: "README.md", ref: "refs/heads/release".

• If it succeeds: You have the GitHub MCP connected. Use Path A (automated submission). Tell the user:

"Good news — I can submit your changes directly from here. No Terminal or git commands needed. Let me check what's changed."

• If the tool doesn't exist or the call fails: Fall back to Path B (guided Terminal walkthrough). Tell the user:

"I'll walk you through submitting your changes step by step. You'll need to paste a few commands into Terminal — I'll tell you exactly what to paste."

Then proceed to Step 1.

Claude Code preflight

In Claude Code, you (Claude) will run git and gh commands directly on the user's machine via Bash — this is Path C. Before doing anything else, verify the local tooling is ready.

Run these checks in parallel via Bash:

• which gh → is the GitHub CLI installed?
• gh auth status → is gh authenticated? (only meaningful if which gh succeeded)
• git config --global user.name and git config --global user.email → is the git identity set?

If anything is missing: Offer to hand off to /contributor-setup before proceeding:

"Before I can submit this, we need to get your local tooling set up — you're missing [specific items]. Want me to run /contributor-setup now to get everything sorted? I'll come back here once it's done."

• If the user says yes → invoke /contributor-setup. When it finishes, re-run the checks above. Once all pass, continue to Step 1.
• If the user says no or wants to handle it themselves → stop and tell them: "Cool — run /contributor-setup when you're ready, then come back and I'll submit this."

If all checks pass: Tell the user:

"Your tooling looks good. Let me check what's changed and review it for privacy before I submit."

Then proceed to Step 1.

---

Step 1: Check what's changed

Path A (GitHub MCP): Gather content from the conversation

Do NOT write files to the local filesystem. The GitHub MCP pushes directly to GitHub's API and never touches the local repo. If you write files locally for review and then push via the API, the user's local repo ends up with untracked/modified files on their current branch that conflict with the remote PR branch. Non-git-savvy contributors (the exact audience for Path A) can't clean this up.

Instead, gather the content that was drafted during the conversation. The user has already been reviewing and iterating on files in the chat — you have the final content in the conversation history. Identify which files need to be created or changed by reviewing what was worked on:

• New files: You have the full content from the drafting conversation.
• Modified files: Fetch the current version from GitHub using get_file_contents (with owner: "timescale", repo: "marketing-skills", ref: "refs/heads/release"), then apply the changes that were agreed on in the conversation.

Summarize for the user what will be submitted:

"Here's what I'll submit: a new SKILL.md for the content-scout skill, plus an updated README.md with the new skill in the table. Let me review everything for privacy before I push it."

Then move to Step 2. Do NOT wait for user input here — go straight to the review.

Path B (Terminal): Check local changes

Run these commands (read-only, works in the Cowork sandbox):

GIT_OPTIONAL_LOCKS=0 git status
GIT_OPTIONAL_LOCKS=0 git diff

Tell the user what changed in plain language:

"Here's what you've changed: you updated the SKILL.md file in the brand-voice-writer skill. Let me review it to make sure everything is safe for the public repo."

Then move to Step 2. Do NOT wait for user input here — go straight to the review.

Path C (Claude Code): Check local changes

Run these via Bash (no GIT_OPTIONAL_LOCKS needed — that's a Cowork workaround):

git status
git diff
git branch --show-current
git log origin/release..HEAD --oneline

Surface anything unexpected before proceeding — stale branches, commits already ahead of origin, uncommitted work on release or main. CLAUDE.md is clear that all work happens on feature branches off release; if the user is not on one, flag it and help them get onto one before continuing. Do not auto-stash or discard unrelated work — surface it and ask.

Tell the user what changed in plain language, then proceed to Step 2.

---

Step 2: Privacy review (mandatory)

This repo is public. This step is not optional.

Review every changed and new file before submitting:

• Path A (GitHub MCP): Review the content from the conversation (drafts the user approved) and any base files fetched via get_file_contents in Step 1. Do NOT use the Read tool on local files — they may not exist for Cowork users.
• Path B (Terminal): Read every changed and new file directly using the Read tool. For modified files, also check the git diff output from Step 1.
• Path C (Claude Code): Same as Path B — read every changed and new file via the Read tool, and cross-check against the git diff output. Files are always available locally in Claude Code.

What to flag: Read the Privacy review section (section 1) in REVIEWING.md at the repo root. That is the single source of truth for the privacy checklist. Apply every item in that list to the changed files.

If you find something: Stop and explain specifically what you found and why it's a concern. Work with the contributor to fix it:

1. Move the content to Tiger Den — add it as a marketing reference doc and declare it in the skill's frontmatter (references: [slug-name]). 2. Replace with a runtime fetch — if the content is already in Tiger Den, replace the inlined text with a get_marketing_reference or get_marketing_context call. 3. Generalize it — remove specifics (e.g., turn "Target companies with 500+ employees in fintech doing $50M+ ARR" into "Read the ICP profile from Tiger Den").

If everything looks clean:

"I've reviewed all the changed files and everything looks safe for a public repo. No proprietary content, customer info, or internal strategy details."

Step 2b: Check for Tiger Den pre-flight pattern

If the skill uses Tiger Den reference docs (calls get_marketing_context, get_marketing_reference, or declares reference slugs), verify it includes a pre-flight check as its first step. Look for:

1. A call to list_marketing_references() before any real work begins (typically Step 0) 2. A clear "STOP if this fails" instruction 3. Error handling that either invokes /doctor or gives manual fix instructions

If the pre-flight is missing, flag it and help the contributor add it using the pattern in REFERENCES.md.

Step 2c: Check if the README skills table needs updating

If the contributor added a new skill, check whether it's listed in the skills table in README.md. If missing, offer to add it (Path A can do this directly; Path B should include the edit in the files to commit).

---

Path A: Automated submission (GitHub MCP)

Use this path when the GitHub MCP is connected. The user does not need Terminal or git.

A1: Confirm and collect PR details

Ask the user for a brief description of what they changed and why. Use this for the commit message and PR body. Keep it to one question:

"Before I submit this, can you give me a quick one-liner about what you changed? Something like 'Updated the brand voice skill to handle product launches better.' I'll use this for the pull request description."

A2: Create branch, push files, and open PR

Once you have their description, do all three in sequence.

Important: Do NOT read files from the local filesystem for this step. Use the content from the conversation (drafted and reviewed inline) and, for modified files, the base version fetched from GitHub in Step 1. This ensures no local files are written or read, keeping the user's working directory clean.

Create the branch: Call create_branch with:

• owner: "timescale"
• repo: "marketing-skills"
• branch: "username/short-description" (use the contributor's first name + a slug of what changed, e.g., nicole/update-brand-voice)
• from_branch: `"release"` — always branch from release, never from main

Push the changed files: Call push_files with:

• owner: "timescale"
• repo: "marketing-skills"
• branch: the branch you just created
• files: array of {path, content} objects for every changed file — use paths relative to the repo root (e.g., plugins/tiger-marketing-skills/skills/brand-voice-writer/SKILL.md)
• message: a short commit message based on what they told you

For each file, use the content that was finalized in the conversation:

• New files: Use the content exactly as drafted and approved in the chat.
• Modified files: Take the base content you fetched from GitHub via get_file_contents in Step 1, apply the agreed-upon changes, and use the resulting content.

Never read files from the local workspace using the Read tool for Path A push_files content. The content source is always the conversation + GitHub API, not the local filesystem.

Create the pull request: Call create_pull_request with:

• owner: "timescale"
• repo: "marketing-skills"
• base: `"release"` — this MUST be "release", never "main". Double-check before calling.
• head: the branch name
• title: short descriptive title (under 72 chars)
• body: their description + a note that it was submitted via Cowork

Labels: The GitHub MCP cannot add labels to PRs. You must ask the user to add the label manually. Always include the direct PR URL so they can click straight to it.

Pick the right label to recommend:

• skill — added a new skill
• enhancement — improved an existing skill
• fix — fixed a bug
• docs — updated documentation

A3: Share the result

"Done! Your pull request is live: [link to PR]

>

There's one small thing I can't do automatically — please add a label. Click here to open your PR: [full PR URL]. Then in the right sidebar, click Labels and pick enhancement (or whichever label fits your change). That's it!"

Always use the actual PR URL returned by create_pull_request — never say "click the link above" or make them scroll back to find it. Give them the clickable URL right in the label instruction.

That's it. They're done.

---

Path B: Guided Terminal walkthrough

Use this path when the GitHub MCP is not available. The user will paste commands into Terminal.

Core principles for this path:

• ONE step per message. Give a command, explain what it does in one sentence, then STOP and wait.
• Never use placeholder paths. Detect the actual path and give copy-pasteable commands.
• Prefix every Terminal command with "📋 Paste this into Terminal:" so there's zero ambiguity about where it goes.
• After each command, say: "Let me know what it shows and I'll tell you the next step."

B1: Open Terminal

If you haven't confirmed the user has Terminal open yet:

"First, let's open Terminal — that's the app where you'll paste the commands I give you.

>

On a Mac: Press Command + Space (that opens Spotlight search), type the word Terminal, and press Enter. A window will open — it usually has a dark or white background with a blinking cursor.

>

Let me know when you have it open."

Wait for their response before continuing.

B2: Navigate to the repo folder

Detect the host path from the mount table:

mount | grep "virtiofs-root/shared" | head -1 | awk '{print $1}' | sed 's|/mnt/.virtiofs-root/shared/|~/|'

Use the detected path. If detection fails, ask: "Do you know where the marketing-skills folder is on your computer? Reply like: my folder is /Users/yourname/Documents/marketing-skills — start your reply with a word so Cowork doesn't get confused by the slash."

Once you have the path:

"📋 Paste this into Terminal:

>

```

cd ~/actual/detected/path/to/marketing-skills

```

>

This tells Terminal to look at your marketing-skills folder. Let me know what happens — if you get an error, we'll figure out the right folder."

Wait for their response.

B3: Fetch latest and create a branch

Help them pick a branch name based on their changes (e.g., nicole/update-brand-voice).

"📋 Paste this into Terminal:

>

```

git fetch origin && git checkout -b nicole/update-brand-voice origin/release

```

>

This grabs the latest version from GitHub and creates a workspace for your changes. Let me know what you see."

Wait for their response.

B4: Stage and commit

Give them one combined command with the specific files (no placeholders):

"📋 Paste this into Terminal:

>

```

git add plugins/tiger-marketing-skills/skills/brand-voice-writer/SKILL.md && git commit -m "Update brand voice skill with Q1 messaging changes"

```

>

This saves a snapshot of your changes. Let me know what it shows."

Use the actual file paths from git status and write the commit message for them based on what they changed. Never ask them to write the commit message — just write a good one.

Wait for their response.

B5: Create the pull request

Check if they have gh (GitHub CLI) by asking:

"📋 Paste this into Terminal:

>

```

gh --version

```

>

If you see a version number, great. If you see 'command not found,' let me know and I'll give you a different way to do this last step."

Wait for their response.

If they have `gh`:

"📋 Paste this into Terminal:

>

```

gh pr create --base release --title "Update brand voice skill" --body "Updated the brand voice skill to handle product launches better"

```

>

It may ask you to choose where to push — pick the option that says timescale/marketing-skills. Let me know what happens."

Write the title and body for them. Don't use placeholders. The --base release flag is critical — always use release, never main.

If they don't have `gh`:

"📋 Paste this into Terminal:

>

```

git push -u origin nicole/update-brand-voice

```

>

Once that finishes, click this link to create the pull request on GitHub:

>

Create your pull request

>

On that page, give it a title (I'd suggest: 'Update brand voice skill'), and click the green Create pull request button. Make sure the base branch says `release` — if it says main, click the dropdown and change it."

Use their actual branch name in both the command and the URL. The compare URL above uses release... which sets the correct base, but remind the user to verify.

B6: Celebrate

"You're done! Your changes are up for review. Someone from the team will take a look and merge them. You'll get a notification on GitHub when it's merged."

---

Path C: Claude Code submission (Claude runs commands directly)

Use this path when the user is in Claude Code. Claude runs git and gh commands on the user's behalf via Bash — no Terminal copy-paste, no GitHub MCP. The preflight in Step 0 has already confirmed gh, gh auth, and git identity are ready.

C1: Pick a branch name and confirm

Propose a branch name based on what changed (e.g., matty/update-brand-voice, jane/add-newsletter-ad-review). Keep it short, lowercase, hyphen-separated. Confirm with the user in one sentence before creating it:

"I'll push this to a branch called matty/update-brand-voice off release — good?"

If the user is already on a feature branch with committed work (you checked via git branch --show-current and git log origin/release..HEAD in Step 1), skip branch creation and use what they've got.

C2: Branch off release

If you need to create a branch, run:

git fetch origin && git checkout -b <branch-name> origin/release

Never branch from main. Always from release.

C3: Stage, commit, and push

Run:

git add <specific files>
git commit -m "<commit message>"
git push -u origin <branch-name>

• Never `git add -A` or `git add .` — stage only the files surfaced in the git status output from Step 1, not everything in the working tree. If the user has unrelated modified files you didn't review, leave them alone and surface them rather than absorbing them into this commit.
• Write the commit message yourself based on what the user described: one sentence, focused on the why, not the what. Do not add a Co-Authored-By: Claude line (per the project's CLAUDE.md).
• If git push fails with an auth error, gh auth may not be wired to git credentials. Run gh auth setup-git and retry.

C4: Open the pull request

Run:

gh pr create --base release --title "<title>" --body "<body>"

• --base release is mandatory. PRs never target main.
• Write the title (under 72 chars) and body yourself based on what the user described. Body should be one or two short bullets on what changed and why.
• Capture the PR URL from the command output.

C5: Share the result and suggest a label

Return the PR URL to the user with a brief celebration and a label hint:

"Done — your PR is live: \<PR URL\>

>

You can add a label on the PR page: skill (new skill), enhancement (improved existing), fix (bug fix), or docs (documentation)."

gh can add labels too — if the user picks one, run gh pr edit <PR number> --add-label <label> and confirm.

---

If they need to update an existing PR

Path A (GitHub MCP):

Use the updated content from the conversation (not the local filesystem) and call push_files to the same branch. The PR updates automatically.

Path B (Terminal):

"Since you already have a branch, just paste these one at a time:"

>

📋 git add plugins/tiger-marketing-skills/skills/skill-name/SKILL.md

>

📋 git commit -m "Description of changes"

>

📋 git push

Path C (Claude Code):

Check that the user is still on the feature branch the PR was opened from (git branch --show-current). If not, git checkout <branch>. Then run git add <files>, git commit -m "<message>", and git push. The PR updates automatically. Confirm to the user with the updated commit SHA.

---

If something goes wrong

Path B (Terminal) — handle one at a time if the user reports them:

• "Not a git repository": They're in the wrong folder. Go back to B2.
• "Merge conflict": This is tricky. Suggest they ask for help in #marketing-tools on Slack, or offer to try Path A if the GitHub MCP becomes available.
• "Your branch is behind": Tell them to paste: git pull --rebase origin release then try pushing again.
• "index.lock": Tell them to paste: rm .git/index.lock and try again.
• "command not found: gh": Fall back to the git push + browser link approach in B5.
• "Permission denied" or auth error: They may need gh auth login or may not have push access. Suggest asking in #marketing-tools on Slack.

Path C (Claude Code) — handle via Bash directly:

• Merge conflict on push: Run git pull --rebase origin release, resolve any conflicts with the user, then retry the push. If the conflict is non-trivial, don't auto-resolve — surface it and ask the user how they want to proceed.
• Push rejected (behind remote): Run git pull --rebase origin <branch-name> then retry.
• `gh` auth error on `gh pr create`: gh auth status to confirm the state. If expired, run gh auth refresh. If still stuck, hand off to /contributor-setup.
• Push auth error (not gh): Run gh auth setup-git to wire gh's token into git credentials, then retry.
• `.git/index.lock` present: Investigate before removing — another git process may be running. If clearly stale, rm .git/index.lock.
• Unexpected working tree state (modified files the user didn't mention, commits ahead on an unexpected branch): do not auto-stash or discard. Surface it, ask the user what to do.

Tone

Be patient, encouraging, and non-judgmental. Many contributors are marketers, not engineers. Explain things in plain language. Never show multiple steps at once. Celebrate their progress.