Skip to content

aspiers/ai-config / .agents/skills/submitting-upstream

submitting-upstream

Verified

Prepare 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.

FileKindSize
SKILL.mdskill md8.0 KB
reference/manual-web-form-submission.mdmarkdown5.5 KB
scripts/paste-form-fields.shexecutablescript3.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.
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall