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"

Phase 5 — Last-mile confirmation (mandatory)

Opening a PR on someone else's repo is public and hard to reverse. Before pushing anything, show the user:

1. The PR title
2. The full PR body (rendered markdown)
3. The exact diff (git diff upstream/<default-branch>)
4. The commands you are about to run

Ask the user to confirm. If they want edits, apply them and re-preview. Do not push until the user says "go" or equivalent.

Phase 6 — Push and open the PR

After approval:

# Commit the changes
git add -A
git commit -m "$(cat <<'EOF'
improve SKILL.md: clarify triggers, add acceptance criteria, fix frontmatter

Suggested via skill-upstream-pr. See PR body for before/after metrics.
EOF
)"

# Push to the fork
git push -u origin "$(git rev-parse --abbrev-ref HEAD)"

# Open the PR upstream
gh pr create \
  --repo "$OWNER/$REPO" \
  --title "$PR_TITLE" \
  --body-file .asm-improver/pr-body.md

Never push to upstream. Never use --no-verify or other hook-skip flags. If gh pr create fails, stop and report — do not retry in a loop.

Print the PR URL returned by gh pr create so the user can open it.

Step Completion Reports (mandatory)

Emit a compact status block after each phase:

◆ Phase N — [phase name] ([N of 6])
··································································
  [check 1]:         √ pass
  [check 2]:         √ pass (note if relevant)
  [check 3]:         × fail — [reason]
  Criteria:          √ M/K met
  ______________________________
  Result:            PASS | FAIL | PARTIAL

Checks per phase:

• Phase 0 — Fork created, Clone succeeded, Branch created, Remotes correct
• Phase 1 — SKILL.md located, Path unambiguous
• Phase 2 — Baseline captured, Retrofit loop ran, Final score >= 85, All categories >= 8
• Phase 3 — Before/after delta >= 3 points OR category promoted
• Phase 4 — PR body rendered, Tone checks passed
• Phase 5 — User approved
• Phase 6 — Push succeeded, PR opened, URL printed

Acceptance Criteria

• Fork + clone done via gh repo fork --clone --remote — never a direct clone of upstream
• Dedicated feature branch created before any edits
• skill-creator retrofit loop run on the target; baseline + final JSON captured under .asm-improver/
• Overall score improved by ≥ 3 points, OR at least one category moved from below 8 to ≥ 8
• PR body built from references/pr-template.md with the full before/after table
• User explicitly approved the PR preview before push
• git push targets origin (the fork), never upstream
• gh pr create --repo $OWNER/$REPO used — the PR targets the upstream repo
• PR URL printed to the user at the end

Expected output

• A new branch on the user's fork of $OWNER/$REPO
• A public PR on $OWNER/$REPO with a before/after metrics table and friendly tone
• A local .asm-improver/ directory with baseline, iterations, report, and pr-body.md

Edge Cases

• Skill already passes 85/8 — stop at Phase 2; do not open a PR for a skill that already meets the floor
• Improvement too small (< 3 point overall delta AND no category promoted) — stop at Phase 3; offer the retrofit report as informal feedback instead
• Multiple SKILL.md files in the repo — ask the user which one; never batch
• Fork already exists from a prior run — gh repo fork --clone --remote reuses it; rebase on upstream's default branch before editing
• Upstream force-pushed or rewrote history — stop and ask the user; do not force-push the fork to "catch up"
• asm eval --fix writes changes you disagree with — revert SKILL.md.bak and do targeted edits only; don't ship the auto-fix if it harms the skill
• Maintainer has a CONTRIBUTING.md or PR template — read it before Phase 4 and align the PR body with their conventions; their template wins over ours

References

• references/pr-template.md — PR title + body template with before/after table
• references/tone-guide.md — wording patterns for friendly, suggestion-style contributions
• skills/skill-creator/references/retrofit-loop.md — the improvement loop this skill delegates to
• asm eval --help — flag reference for the evaluator