菜单
Walk an adopter through promoting a local `.apache-magpie-overrides/<skill>.md` file into a PR against `apache/magpie`. After the PR merges and the adopter runs `/magpie-setup upgrade`, the override file is no longer needed and the skill prompts for its removal.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/apache/magpie --skill magpie-setup-override-upstream命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
Walk a maintainer through deep, sequential code review of open pull requests on the configured `<upstream>` repo. Defaults to the **"my reviews"** queue (the union of five maintainer signals — see the Inputs table); selectors can narrow to a single PR, an area label, or a collaborator subset. Drafts an `approve` / `request-changes` / `comment` review per PR and posts on the maintainer's confirmation.
Author a new skill for the Apache Magpie framework, or update an existing one. Walks the user through the framework's skill shape (frontmatter, resources, placeholder convention, prompt-injection defences, Privacy-LLM gate-check) and validates via the framework's existing [`tools/skill-and-tool-validator`](../../tools/skill-and-tool-validator/). Scaffolds new skills via `init_skill.py`.
Help an adopter or framework developer file a clean, redacted GitHub issue against the Apache Magpie framework repo when a skill, tool, or doc misbehaves. It gathers the problem from the user — never from the raw session transcript — then runs a mandatory public-disclosure scrub before rendering the report into the framework's `bug_report` / `change_proposal` issue template, checking for duplicates, and filing via `gh issue create --web` only on explicit confirmation. The scrub is the point: the destination is a public repo, so the skill strips any private tracker, embargoed-CVE, private-list, or cross-project content the report would otherwise leak.
基于 SOC 职业分类
正在显示 SKILL.md
| name | magpie-setup-override-upstream |
| family | setup |
| mode | Meta |
| description | Walk an adopter through promoting a local `.apache-magpie-overrides/<skill>.md` file into a PR against `apache/magpie`. After the PR merges and the adopter runs `/magpie-setup upgrade`, the override file is no longer needed and the skill prompts for its removal. |
| when_to_use | Invoke when the user says "upstream my override", "promote this override to the framework", "convert my local modification into a magpie feature", "make this override a framework feature", "open a PR to apache-magpie for this override", or similar — typically after running the override locally for a while and deciding the change is worth contributing back. |
| argument-hint | [skill-name] |
| capability | capability:platform |
| license | Apache-2.0 |
This skill is the path from local override to framework
feature. It takes a single
.apache-magpie-overrides/<skill>.md file in an adopter
repo, walks the user through deciding whether the change is
worth upstreaming, designs the framework-level abstraction,
implements it in apache/magpie, and opens a PR.
The override mechanism (per
docs/setup/agentic-overrides.md)
is deliberately agentic and adopter-local: there's no
schema, no anchors, no patch tool. That makes overrides
quick to write but hard to share — every adopter who wants
the same behaviour writes their own. Upstreaming is the
escape hatch: when an override stops being project-specific
and starts looking like a missing feature, the right move
is a PR that bakes the change into the framework's default,
making every adopter benefit on their next
/magpie-setup upgrade.
Before running the default behaviour documented below, this
skill consults
.apache-magpie-local/setup-override-upstream.md (personal, gitignored) and .apache-magpie-overrides/setup-override-upstream.md (committed, project-wide)
in the adopter repo if it exists, and applies any
agent-readable overrides it finds. See
docs/setup/agentic-overrides.md
for the contract — what overrides may contain, hard rules,
the reconciliation flow on framework upgrade, upstreaming
guidance.
Hard rule: agents NEVER modify the snapshot under
<adopter-repo>/.apache-magpie/. Local modifications go in
the override file. Framework changes go via PR to
apache/magpie.
Also at the top of every run, this skill compares the
gitignored .apache-magpie.local.lock (per-machine
fetch) against the committed .apache-magpie.lock (the
project pin). On mismatch the skill surfaces the gap and
proposes
/magpie-setup upgrade.
The proposal is non-blocking — the user may defer if
they want to run with the local snapshot for now. See
docs/setup/install-recipes.md § Subsequent runs and drift detection
for the full flow.
Drift severity:
git-branch
local is behind upstream tip) → ⚠ sync needed.svn-zip SHA-512 mismatches the committed
anchor → ✗ security-flagged; investigate before
upgrading.Doubly important here: the skill is about to design a framework-level abstraction by reading the snapshot's framework skill. If the snapshot is stale, the abstraction may be designed against a version that has already changed upstream. Address drift before proceeding.
Golden rule 1 — not every override should be upstreamed. Many overrides encode genuinely project-specific choices: the wording of a canned response, the project's scope-label taxonomy, milestone-format regex, a tone-of-voice preference. These should stay in the adopter repo. The skill explicitly walks through this decision and stops early if the change is not generalisable.
Golden rule 2 — write to <framework-clone>, never to
the snapshot. The framework PR is implemented in the
user's local apache-magpie clone (a separate working
directory from the adopter's .apache-magpie/ snapshot,
which is gitignored and read-only). If the user does not
have a clone yet, the skill helps them set one up.
Golden rule 3 — assistant proposes, user fires. Per the
framework convention (see
AGENTS.md), every state-changing
action — clone, branch, commit, push, gh pr create — is
proposed by the skill and only happens on explicit user
confirmation. Public PR content is shown to the user before
it is posted.
Golden rule 4 — decouple PR from override deletion.
Opening the framework PR is one step; deleting the now-
redundant override file in the adopter repo is a separate
step that happens AFTER the PR has merged AND the adopter
has run /magpie-setup upgrade to pick up the framework
change. The skill ends with a clear pointer at the
post-merge cleanup; it does not delete the override
preemptively.
<adopter-repo>/.apache-magpie.lock and
<adopter-repo>/.apache-magpie-overrides/). If not,
stop — the skill is for adopters with at least one
override file./magpie-setup upgrade first.<framework-clone> — the user's local clone
of apache/magpie. Common locations:
~/code/magpie/, ~/work/magpie/.
If not found, surface and ask the user where it is, or
help them clone it (git clone git@github.com:apache/magpie.git). The clone
is separate from <adopter-repo>/.apache-magpie/
(the snapshot).List <adopter-repo>/.apache-magpie-overrides/*.md
(excluding the directory's own README.md). For each,
print the file name + first headline.
Read the chosen override file. Surface to the user:
### Override N — ...)Then read the framework skill it modifies, from the
snapshot at
<adopter-repo>/.apache-magpie/skills/<framework-skill>/.
Surface:
Goal: both the user and the agent should now have a clear mental model of what the change is and where it applies.
Walk through with the user. Common categories:
If the user is unsure, lean toward stop — keep the override local until a second adopter wants the same thing.
Once the user confirms the change is upstreamable, design the framework-side change. Pick one of:
| Shape | When |
|---|---|
Add a config knob in <project-config>/ | The change is opt-in per-adopter; default behaviour is unchanged. |
| Change a default | The new behaviour is better for the majority; the framework's existing default becomes a <project-config>/ opt-out. |
| Add an optional step | The change is an additional step (not a substitute for an existing one). |
| Refactor existing step | The change rewrites how an existing step works. No new config; the new behaviour is universal. |
Surface the proposal to the user. Iterate. The output of this step is a concrete plan: which framework files to modify, what to add / remove / change, what tests or verification the framework already has that may need updating.
In <framework-clone>:
git fetch origin && git checkout -b feat/<short-description> origin/mainAGENTS.md, the relevant supporting files of the
modified skill) to match conventions.prek run --all-files. Fix anything that fires.git diff). Get explicit
confirmation before committing.feat(skills): ... for new framework behaviour,
refactor(skills): ... for restructure, etc.). End the
message with a Generated-by: <agent> (<model>) trailer,
where <agent> and <model> are the actual agent and
model you are running as (e.g. Claude (Opus 4.8),
OpenCode (Big Pickle)) — do not hardcode either, per
the framework's no-coauthored-by hook.git push -u <fork-remote> feat/<branch>. If no fork
remote is configured, surface and help the user add one
(git remote add fork <user>/magpie.git).
Draft the PR title + body. Include:
Confirm with the user before posting. Show the
exact title + body. Wait for "OK to post" / "yes" /
"send" / similar before running gh pr create.
Pick the labels. Every framework PR carries at least one
family:* and one capability:* label per
docs/labels-and-capabilities.md.
The override is upstreaming a change to skill <skill>, so:
family:* — follow the skill's family
(family:pr-management for pr-management-*, family:security
for security-*, family:setup for setup-*, family:issue
for issue-*, etc.).capability:* — the capability the change is implementing,
not the file paths touched. Look up the skill's capability in
the skill-to-capability map at
docs/labels-and-capabilities.md#capability-to-skill-map.kind:* and mode:* when they apply per the same doc.Surface the chosen labels in the confirmation preview alongside the PR title and body, so the user sees them before posting.
Write the PR body to a tempfile first, then create the PR:
# Write tool: file_path: /tmp/override-pr-body.md, content: <PR body>
gh pr create --repo apache/magpie --base main \
--head <user>:<branch> --title "..." --body-file /tmp/override-pr-body.md \
--label "family:<family>" --label "capability:<capability>"
After the PR is open, surface to the user:
Framework PR opened: <PR URL>
Next steps once it merges:
1. /magpie-setup upgrade (in <adopter-repo>)
- Bumps the snapshot to the new framework version.
- .apache-magpie.lock will reflect the new pin.
2. Delete .apache-magpie-overrides/<skill>.md in <adopter-repo>
- The override is now redundant; the framework does
what the override used to do.
3. Commit the deletion + the bumped lock together.
The skill does not delete the override file itself — that happens after the PR merges, and the skill cannot predict when (or if) the framework reviewers accept the PR. Deletion is the user's manual cleanup once the PR lands.
✓ Override picked: .apache-magpie-overrides/<skill>.md
✓ Framework skill: <framework-skill>
✓ Decision: upstreamable as <shape from Step 4>
✓ Framework clone: <framework-clone>
✓ Branch: feat/<short-description>
✓ Commits: <count>
✓ PR opened: <PR URL>
Next: wait for the PR to merge, then in <adopter-repo>:
/magpie-setup upgrade
rm .apache-magpie-overrides/<skill>.md
git add -A && git commit -m "Remove override <skill>: upstreamed in apache/magpie#<N>"
| Symptom | Likely cause | Remediation |
|---|---|---|
<adopter-repo> has no .apache-magpie-overrides/ | not adopted, or adopted without the overrides scaffold | run /magpie-setup adopt (idempotent) |
| Step 1 finds zero overrides | nothing to upstream — adopter has no local modifications recorded | stop |
<framework-clone> not found | user has not cloned apache/magpie yet | help them clone, then resume |
| Framework pre-commit fails after the implementation | the change does not match framework conventions | iterate with the user, re-run pre-commit, do not bypass with --no-verify |
| User decides mid-flow that the override is project-specific after all | wrong call in Step 3 | stop without opening a PR; the override file in the adopter repo is unchanged, no harm done |
docs/setup/agentic-overrides.md./magpie-setup override <skill>./magpie-setup upgrade.
Run that BEFORE this skill if drift exists.docs/setup/agentic-overrides.md — the override contract.setup/overrides.md — how to create / open an override.setup/upgrade.md — how to upgrade the snapshot post-merge.