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
---
name: submitting-upstream
description: >-
  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.
---

# Submitting Upstream

Prepare the kind of upstream submission the user requested. Do not assume
that "submit upstream" means a code change: an issue, feature request, or
discussion needs no branch or commits.

## Choose the submission type

Infer the intended artefact from the request and current context:

- A problem report, feature request, or proposed behaviour normally becomes an
  issue.
- An idea the project explicitly routes to a forum becomes a discussion or
  proposal.
- An implemented local change normally becomes a pull request, merge request,
  or patch series.
- Documentation, security, and support requests may have dedicated channels.

If more than one type is plausible and the choice affects the work, ask one
focused question before preparing anything.

## Find the canonical destination

Identify the canonical project and its actual submission channel rather than
a fork, package mirror, or downstream tracker. Check repository metadata,
project documentation, release activity, and tracker activity when ownership
is not obvious.

Use the `checking-upstream` skill before drafting. Read plausible matches,
including closed reports and the open change queue. Existing work, a prior
resolution, or an explicit rejection may make a new submission unnecessary or
change it into a comment on an existing thread.

## Read the relevant rules

Look for the guidance that applies to the selected submission type. Do not
make code-contribution ceremony a prerequisite for filing an issue.

For any submission, check as applicable:

- issue, discussion, pull-request, or merge-request templates;
- `CONTRIBUTING*`, support and security policies, and project website
  guidance;
- required tracker fields, categories, labels, reproduction details, or prior
  discussion;
- codes of conduct and rules against disclosing sensitive data;
- the project's stance on AI-generated contributions, which
  `checking-upstream` reports. See "AI-generated content" below.

For code contributions, also inspect:

- target-branch and fork policy;
- DCO, CLA, sign-off, and copyright requirements;
- commit-message and history conventions;
- formatting, lint, test, build, changelog, and generated-file requirements;
- CI workflows and a few recent merged changes when written guidance is
  silent.

Treat documented rules as authoritative. If observed practice conflicts with
them, report the conflict instead of silently choosing one.

### AI-generated content

Settle this before drafting anything, since it can decide whether there is
a submission at all.

- **The project objects to AI labels or AI-labelled content.** The user
  approves the exact text before anything is posted, and it carries no AI
  signature or other AI label. This overrides the global rule to sign
  posts as written by Claude.
- **The project rejects AI contributions outright.** Removing the label
  would hide from the maintainer the very thing they asked not to
  receive, so do not draft around the ban. Tell the user what the policy
  says, quoting it with its URL, and ask how to proceed: the user writes
  the submission or code themselves from your notes, asks the maintainer
  first, or does not submit.
- **The scope is unclear**, such as a ban stated in one feature's thread.
  Quote it and let the user judge whether it applies.

## Prepare the submission

### Issues, feature requests, and discussions

No branch or commit is needed.

Follow the project's template and preserve its headings. When there is no
template, draft a concise title and a body containing the useful subset of:

- the problem or requested capability;
- current and expected behaviour;
- reproduction steps and environment for a bug;
- motivation and concrete use cases for a feature;
- relevant logs, screenshots, or minimal examples;
- related issues and the upstream search already performed;
- known workarounds or implementation facts, clearly separated from the
  requested outcome.

State evidence precisely and remove secrets, personal data, private URLs, and
unrelated local details. Do not invent labels, severity, maintainer decisions,
or implementation requirements that the project has not established.

### Do not hard-wrap prose

Leave each paragraph of issue, discussion, pull-request, and comment text as
one long line. These bodies are rendered, not read as source: the wrapping
adds nothing, and it turns any later edit into a reflowed diff that obscures
the real change.

This holds even when the text was drafted in a local file wrapped to a column
limit — an `.editorconfig` `max_line_length` governs the file, not the
submission. Unwrap the prose when transferring it.

Keep the line structure that carries meaning: code blocks, tables, headings,
list items, and deliberate line breaks such as one URL or entry per line.
Wrap prose only where the destination genuinely calls for it, such as a
project whose contribution guide requires it, a plain-text patch submitted by
email, or a commit message.

### Code changes

Only use this path when code is actually being contributed.

1. Fetch the canonical upstream and branch from its required, freshly fetched
   target branch.
2. Port only the relevant change; exclude personal configuration, debug
   output, secrets, and unrelated formatting churn.
3. Shape commits to the project's documented or observed conventions. Never
   add another person's sign-off or claim a CLA on their behalf.
4. Add required tests, documentation, changelog entries, and generated files.
5. Run the project's verification commands as `test-running` describes,
   keeping them away from the user's live services, and distinguish
   introduced failures from pre-existing or environmental ones.
6. Draft the pull request, merge request, or patch text using the project's
   template and requested linkage syntax.

If a required rule is unmet, state it plainly and fix it before presenting
the submission as ready. Legal attestations such as DCO sign-off and CLA
acceptance cannot be waived or fabricated.

## Approval boundary

Creating an issue or discussion, commenting publicly, opening a change
request, or sending patches is outward-facing. Prepare the exact title and
body, or patch, first, then stop for explicit approval before the first
publication action.

Pushing a source branch to the user's own fork is not a submission and needs
no approval, unless the branch holds sensitive, confidential, or personal
content, which should not be in a public fork anyway. Approval is for what
reaches the upstream project.

Present:

- the canonical destination and chosen submission type;
- relevant guidance and whether each requirement is satisfied;
- existing upstream work and how this submission relates to it;
- the exact draft, in an Orca tab when running inside Orca (see the global
  rules);
- for code, the base, commits, diff scope, and verification results;
- the command or action that will publish it.

Once the user approves that prepared artefact, perform only the approved
publication action and return its URL or delivery result. Do not turn approval
to file an issue into permission to open a change request, or approval of one
change request into permission for another.

## Who publishes it

Publishing through an API or CLI is not always the right channel. Offer to
hand the draft to the user to paste into the project's web form when the
tracker applies metadata the API bypasses — a GitHub issue form applies its
`type:` and `labels:` on submission, which `gh issue create` does not — or
when the submission should plainly be the user's own.

For that flow, and for the field-splitting and clipboard sequence it needs,
read [`reference/manual-web-form-submission.md`](reference/manual-web-form-submission.md).

After a code submission, use the `pr-comment-resolving` skill for review
feedback and `watching-ci-runs` when CI results determine the next step.
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