Skill Upstream PR

Skill Upstream PR

You are contributing quality improvements to someone else's open-source skill. The workflow is: fork → clone → improve via skill-creator's retrofit loop → push to fork → open a friendly suggestion PR upstream. You do not own the target repo. Every step assumes you are a polite contributor, not a maintainer.

Repo Sync Before Edits (mandatory)

Before any modification to the cloned fork, pull the latest from the fork's tracked branch:

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If the working tree is dirty: stash, sync, pop. If origin is missing or conflicts occur: stop and ask the user. A stale fork that PRs yesterday's tree is worse than no PR.

When to Use

• User shares a GitHub URL to a public skill repo and asks to "improve", "level up", or "contribute to" it
• User says "open a PR to this skill" or "suggest improvements upstream"
• The target skill scores below 85/8 on asm eval and the user wants the upstream author to benefit

Do not trigger for: editing a local skill with no upstream, authoring a brand-new skill, publishing to the ASM registry, or bulk-improving many repos in one pass. One skill → one PR.

Prerequisites

Verify each before cloning anything. Stop and tell the user if any fails.

• asm on PATH (command -v asm)
• gh on PATH and authenticated (gh auth status)
• git on PATH
• Network access to GitHub
• Write access to your own GitHub account (for the fork)

Input

The user provides a GitHub reference to a skill. Accept any of:

• https://github.com/owner/repo
• https://github.com/owner/repo/tree/<branch>/<path/to/skill>
• github:owner/repo[#ref][:path]

Normalize to owner, repo, optional ref, optional path. If path is not given and the repo has multiple SKILL.md files, ask the user which one.

Workflow

Execute phases in order. Do not skip or reorder.

Phase 0 — Fork and clone

cd "$(mktemp -d)"
gh repo fork "$OWNER/$REPO" --clone --remote
cd "$REPO"
# If a ref was provided:
git checkout "$REF"

gh repo fork --clone --remote creates the fork under your account, clones it locally, sets origin to your fork and upstream to the original repo. Verify with git remote -v before continuing.

Create a dedicated branch for the improvement:

git checkout -b "skill-upstream-pr/improve-$(date +%Y%m%d-%H%M%S)"

Phase 1 — Locate the target SKILL.md

If the user gave a path, use it. Otherwise:

find . -maxdepth 5 -name "SKILL.md" -type f

If more than one match and no path was given, list the candidates and ask the user to pick. Never guess — a wrong PR is worse than a delayed one.

Set SKILL_PATH to the directory containing the chosen SKILL.md (not the file itself) — asm eval takes a directory.

Phase 2 — Delegate to skill-creator's retrofit loop

This skill does not reimplement the improvement loop. Follow skills/skill-creator/references/retrofit-loop.md with $SKILL_PATH as the target:

1. Phase 0: capture .asm-improver/baseline.json
2. Phase 1: asm eval --fix plus frontmatter normalization
3. Phases 2–4: Gate 1 fixes, then the category loop against the 85/8 floor
4. Phases 5–6: version bump and the loop cap (8 iterations / 3 no-move / 2 regressions)
5. Phase 7: .asm-improver/report.md

If the baseline already passes both gates, stop and tell the user — no PR needed for a skill that already meets the floor. Offer to find a different skill or a different target.

Phase 3 — Harvest metrics for the PR

Read two files produced by the retrofit loop:

• .asm-improver/baseline.json — the before snapshot
• The latest .asm-improver/iter-N.json — the after snapshot

Extract for both:

• overallScore, grade
• Every categories[].score (7 categories)
• topSuggestions summary (for context, not quoted verbatim)

Compute deltas. If the overall score did not improve by at least 3 points or no category moved from below 8 to at least 8, stop and tell the user — the change isn't meaningful enough to justify a PR. Offer the retrofit report as feedback they can share informally instead.

Phase 4 — Build the PR body

Read references/pr-template.md and fill it in. The template enforces friendly, suggestion-style tone. Key sections:

• What changed — one-sentence summary
• Before/after metrics — table with overallScore, grade, and all 7 categories
• Files touched — list every modified path under $SKILL_PATH
• Iterations taken — N of 8 from the retrofit loop
• How to verify — the asm eval command the maintainer can run locally

Tone rules (read references/tone-guide.md):

• Lead with "Hi — noticed X, wanted to share Y"
• Frame as a suggestion, not a fix: "happy to adjust if the direction doesn't fit"
• Never imply the maintainer did something wrong
• Thank them for open-sourcing the skill
• Close with "no obligation to merge — totally fine to close if this isn't the right direction"