skill-upstream-pr

Files (4)

• SKILL.md
• README.md · docs/
• pr-template.md · references/
• tone-guide.md · references/

SKILL.md (first lines)

# 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:

```bash
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

```bash
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:

```bash
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:

```bash
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"

From luongnv89/asm, MIT.

More from luongnv89/asm