aspiers/ai-config / .agents/skills/submitting-upstream
submitting-upstream
VerifiedPrepare and publish upstream issues, feature requests, discussions, pull or merge requests, and patch submissions in the channel the canonical project expects. Use when reporting a problem upstream, requesting a feature, contributing a change, or asking to submit upstream.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.0 KB |
| reference/manual-web-form-submission.md | markdown | 5.5 KB |
| scripts/paste-form-fields.shexecutable | script | 3.7 KB |
reference/manual-web-form-submission.md
View on GitHub# Manual submission through the project's web form
Hand the prepared draft to the user to paste into the upstream web form
themselves, instead of publishing it through an API or CLI.
## When this is the right channel
Prefer it whenever any of these hold:
- **The tracker applies metadata the API does not.** A GitHub issue form
(`.github/ISSUE_TEMPLATE/*.yml`) applies its `type:` and `labels:` on
submission. `gh issue create` bypasses the form, so those must be set by
hand and are easy to get subtly wrong.
- **Attribution should be the user's.** A submission filed through the user's
browser session is plainly theirs. Some projects also treat agent-filed
reports differently.
- **The form has required fields or validation** that only the rendered form
enforces.
- **The user asks to file it themselves.** Their call, not a decision to argue
with.
Publishing by API stays fine for a project with no form, or when the user has
asked for the API path specifically.
## Prepare the draft as separable fields
Write the draft so each form field is a self-contained block, in the form's
own order. Cover every field the user will meet: the title, checkboxes,
dropdowns, and optional fields left empty, not only those that take a paste.
For a GitHub issue form, read the template first and use one block per `body`
element other than `markdown`.
A field that takes a click rather than a paste, or stays empty, gets a block
holding only a `#NOTE:` line saying what to do, such as `#NOTE: choose
Navigation`, `#NOTE: tick "I'm willing to submit a PR"` or `#NOTE: leave
empty`. Never fold one field's instruction into another field's note: on two
issues filed with only the text fields announced, a checkbox mentioned in a
neighbouring field's note came through unticked.
Keep the whole draft in one scratch file, with each field under a top-level
Markdown heading naming the form field:
```markdown
# Title
[Feature]: ...
# Category
#NOTE: choose Navigation
# Problem or use case
...
# Proposed solution
...
```
Then split it into one file per field, so a single mis-paste is recoverable
without regenerating anything:
```bash
python3 - <<'EOF'
import re, pathlib
src = pathlib.Path('issue-draft.md').read_text()
parts = re.split(r'(?m)^# (.+)$', src)
for i in range(1, len(parts), 2):
slug = re.sub(r'[^a-z0-9]+', '-', parts[i].lower()).strip('-')
pathlib.Path(f'{i // 2 + 1}-{slug}.txt').write_text(parts[i + 1].strip() + '\n')
EOF
```
The headings are scaffolding for the split. The form supplies its own field
labels, so they are not pasted.
## Drive the paste sequence
1. Open the form with the `open-in-user-browser` skill. Use the template's
direct URL where one exists, so the user does not have to pick from the
chooser:
```text
https://github.com/OWNER/REPO/issues/new?template=feature_request.yml
```
2. Where the user needs a field-specific hint, such as a template-prefilled
title that needs select-all, make the file's first line `#NOTE: <text>`.
The hint appears in the notification and is not copied. A hint covers
only its own field.
3. Tell the user the sequence is about to start and what to watch for in the
fields; the notifications only name the field.
4. Run [`scripts/paste-form-fields.sh`](../scripts/paste-form-fields.sh) in
the foreground on the field files, in form order:
```bash
scripts/paste-form-fields.sh 1-title.txt 2-problem-or-use-case.txt ...
```
For each field it loads the clipboard without a trailing newline, reads
it back and aborts on a mismatch, then shows a desktop notification naming
the form field. A file holding only a `#NOTE:` line gets a notification
saying what to set, and the clipboard keeps its last contents.
Notifications stay up for 10 seconds and stack, and the
script advances every 5 seconds, so the user pastes without reporting back
between fields. `-f` sets the first delay, `-d` the later ones and `-t`
the display time, all in seconds; use them when the user asks for a
different pace.
It picks `wl-copy`, `xclip`, `xsel` or `pbcopy` to suit the session, and
`notify-send` or macOS `osascript` for notifications. Under `osascript`,
macOS decides how long a notification stays up.
5. Name the field file paths once, so the user can re-run the script on a
single field if a paste goes wrong or they miss a window.
## Before they submit
Ask them to confirm the things only the rendered form reveals:
- issue-number and user references resolved to real links;
- fenced code blocks rendered as code, not reflowed prose;
- the template's `type` and labels actually applied;
- every checkbox and dropdown set as the draft says.
## After it is filed
Ask for the resulting URL or number — there is no API response to read it
from. Then verify it landed as intended, and record it wherever the work is
tracked. Compare the filed body with the draft, checkbox states and dropdown
values included, since nothing else catches a missed click. Tell the user
about any difference so they can edit the issue.
```bash
gh api repos/OWNER/REPO/issues/NUMBER \
--jq '"#\(.number) \(.title)\nstate=\(.state) type=\(.type.name // "none") labels=\(.labels|map(.name)|join(",")) author=\(.user.login)"'
gh api repos/OWNER/REPO/issues/NUMBER --jq .body
```
## Approval boundary
This path does not relax the boundary in the main skill: the user performs the
publication, so nothing is published without them. Opening the form and
loading the clipboard are preparation, not publication, and need no separate
approval once the draft itself is agreed.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |