skill-upstream-pr

Name: skill-upstream-pr
Author: luongnv89

742stars61forks

How to install skill-upstream-pr?

luongnv89/asm/skill-upstream-pr

$npx -y skills add luongnv89/asm --skill skill-upstream-pr

Installs into the current project.

Summary

Improve an open-source GitHub skill and open a friendly suggestion PR upstream: fork, run skill-auto-improver, attach asm eval before/after metrics. Don't use for local-only skills, authoring from scratch, bulk repos, or registry publish.

Files · 1

View on GitHub

SKILL.md

1	# Skill Upstream PR
2
3	You are contributing quality improvements to someone else's open-source skill. The workflow is: fork → clone → improve via `skill-auto-improver` → 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.
4
5	## Repo Sync Before Edits (mandatory)
6
7	Before any modification to the cloned fork, pull the latest from the fork's tracked branch:
8
9	```bash
10	branch="$(git rev-parse --abbrev-ref HEAD)"
11	git fetch origin
12	git pull --rebase origin "$branch"
13	```
14
15	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.
16
17	## When to Use
18
19	- User shares a GitHub URL to a public skill repo and asks to "improve", "level up", or "contribute to" it
20	- User says "open a PR to this skill" or "suggest improvements upstream"
21	- The target skill scores below 85/8 on `asm eval` and the user wants the upstream author to benefit
22
23	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.
24
25	## Prerequisites
26
27	Verify each before cloning anything. Stop and tell the user if any fails.
28
29	- `asm` on PATH (`command -v asm`)
30	- `gh` on PATH and authenticated (`gh auth status`)
31	- `git` on PATH
32	- Network access to GitHub
33	- Write access to your own GitHub account (for the fork)
34
35	## Input
36
37	The user provides a GitHub reference to a skill. Accept any of:
38
39	- `https://github.com/owner/repo`
40	- `https://github.com/owner/repo/tree/<branch>/<path/to/skill>`
41	- `github:owner/repo[#ref][:path]`
42
43	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.
44
45	## Workflow
46
47	Execute phases in order. Do not skip or reorder.
48
49	### Phase 0 — Fork and clone
50
51	```bash
52	cd "$(mktemp -d)"
53	gh repo fork "$OWNER/$REPO" --clone --remote
54	cd "$REPO"
55	# If a ref was provided:
56	git checkout "$REF"
57	```
58
59	`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.
60
61	Create a dedicated branch for the improvement:
62
63	```bash
64	git checkout -b "skill-upstream-pr/improve-$(date +%Y%m%d-%H%M%S)"
65	```
66
67	### Phase 1 — Locate the target SKILL.md
68
69	If the user gave a `path`, use it. Otherwise:
70
71	```bash
72	find . -maxdepth 5 -name "SKILL.md" -type f
73	```
74
75	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.
76
77	Set `SKILL_PATH` to the directory containing the chosen SKILL.md (not the file itself) — `asm eval` takes a directory.
78
79	### Phase 2 — Delegate to skill-auto-improver
80
81	This skill does not reimplement the improvement loop. Follow the workflow in `skills/skill-auto-improver/SKILL.md` with `$SKILL_PATH` as the target:
82
83	1. Phase 0 of that skill: capture `.asm-improver/baseline.json`
84	2. Phase 1: `asm eval --fix`
85	3. Phases 2-4: category-by-category loop with the 85/8 floor
86	4. Phase 5: `.asm-improver/report.md`
87
88	If the baseline already passes 85/8, 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.
89
90	### Phase 3 — Harvest metrics for the PR
91
92	Read two files produced by the auto-improver:
93
94	- `.asm-improver/baseline.json` — the before snapshot
95	- The latest `.asm-improver/iter-N.json` — the after snapshot
96
97	Extract for both:
98
99	- `overallScore`, `grade`
100	- Every `categories[].score` (7 categories)
101	- `topSuggestions` summary (for context, not quoted verbatim)
102
103	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 auto-improver report as feedback they can share informally instead.
104
105	### Phase 4 — Build the PR body
106
107	Read `references/pr-template.md` and fill it in. The template enforces friendly, suggestion-style tone. Key sections:
108
109	- What changed — one-sentence summary
110	- Before/after metrics — table with overallScore, grade, and all 7 categories
111	- Files touched — list every modified path under `$SKILL_PATH`
112	- Iterations taken — N of 8 from the auto-improver loop
113	- How to verify — the `asm eval` command the maintainer can run locally
114
115	Tone rules (read `references/tone-guide.m

People who liked this also viewed

6 picks

Type

skill-upstream-pr

742stars61forks

View on GitHub

How to install skill-upstream-pr?

luongnv89/asm/skill-upstream-pr

$npx -y skills add luongnv89/asm --skill skill-upstream-pr

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Skill Upstream PR
2
3	You are contributing quality improvements to someone else's open-source skill. The workflow is: fork → clone → improve via `skill-auto-improver` → 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.
4
5	## Repo Sync Before Edits (mandatory)
6
7	Before any modification to the cloned fork, pull the latest from the fork's tracked branch:
8
9	```bash
10	branch="$(git rev-parse --abbrev-ref HEAD)"
11	git fetch origin
12	git pull --rebase origin "$branch"
13	```
14
15	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.
16
17	## When to Use
18
19	- User shares a GitHub URL to a public skill repo and asks to "improve", "level up", or "contribute to" it
20	- User says "open a PR to this skill" or "suggest improvements upstream"
21	- The target skill scores below 85/8 on `asm eval` and the user wants the upstream author to benefit
22
23	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.
24
25	## Prerequisites
26
27	Verify each before cloning anything. Stop and tell the user if any fails.
28
29	- `asm` on PATH (`command -v asm`)
30	- `gh` on PATH and authenticated (`gh auth status`)
31	- `git` on PATH
32	- Network access to GitHub
33	- Write access to your own GitHub account (for the fork)
34
35	## Input
36
37	The user provides a GitHub reference to a skill. Accept any of:
38
39	- `https://github.com/owner/repo`
40	- `https://github.com/owner/repo/tree/<branch>/<path/to/skill>`
41	- `github:owner/repo[#ref][:path]`
42
43	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.
44
45	## Workflow
46
47	Execute phases in order. Do not skip or reorder.
48
49	### Phase 0 — Fork and clone
50
51	```bash
52	cd "$(mktemp -d)"
53	gh repo fork "$OWNER/$REPO" --clone --remote
54	cd "$REPO"
55	# If a ref was provided:
56	git checkout "$REF"
57	```
58
59	`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.
60
61	Create a dedicated branch for the improvement:
62
63	```bash
64	git checkout -b "skill-upstream-pr/improve-$(date +%Y%m%d-%H%M%S)"
65	```
66
67	### Phase 1 — Locate the target SKILL.md
68
69	If the user gave a `path`, use it. Otherwise:
70
71	```bash
72	find . -maxdepth 5 -name "SKILL.md" -type f
73	```
74
75	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.
76
77	Set `SKILL_PATH` to the directory containing the chosen SKILL.md (not the file itself) — `asm eval` takes a directory.
78
79	### Phase 2 — Delegate to skill-auto-improver
80
81	This skill does not reimplement the improvement loop. Follow the workflow in `skills/skill-auto-improver/SKILL.md` with `$SKILL_PATH` as the target:
82
83	1. Phase 0 of that skill: capture `.asm-improver/baseline.json`
84	2. Phase 1: `asm eval --fix`
85	3. Phases 2-4: category-by-category loop with the 85/8 floor
86	4. Phase 5: `.asm-improver/report.md`
87
88	If the baseline already passes 85/8, 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.
89
90	### Phase 3 — Harvest metrics for the PR
91
92	Read two files produced by the auto-improver:
93
94	- `.asm-improver/baseline.json` — the before snapshot
95	- The latest `.asm-improver/iter-N.json` — the after snapshot
96
97	Extract for both:
98
99	- `overallScore`, `grade`
100	- Every `categories[].score` (7 categories)
101	- `topSuggestions` summary (for context, not quoted verbatim)
102
103	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 auto-improver report as feedback they can share informally instead.
104
105	### Phase 4 — Build the PR body
106
107	Read `references/pr-template.md` and fill it in. The template enforces friendly, suggestion-style tone. Key sections:
108
109	- What changed — one-sentence summary
110	- Before/after metrics — table with overallScore, grade, and all 7 categories
111	- Files touched — list every modified path under `$SKILL_PATH`
112	- Iterations taken — N of 8 from the auto-improver loop
113	- How to verify — the `asm eval` command the maintainer can run locally
114
115	Tone rules (read `references/tone-guide.m

People who liked this also viewed

6 picks

Type