Search guides, workflows, and reference pages.

Docs/Mentoring

Agentic Mentoring skill family

Scope. Works on any project, ASF or not — no Apache-Software-Foundation-specific assumptions baked in.

Maintainer-facing skills that join contributor threads in a teaching register, author newcomer-ready issues, curate the existing backlog for newcomers, orient first-time contributors, explain issue context to newcomers, and track a contributor’s readiness path to committer nomination. Six skills shipped at experimental.

MISSION names Agentic Mentoring as the highest-value project-side mode and the one off-the-shelf agent tooling skips. The framework lands the spec — tone guide, hand-off protocol, adopter contract — and the skill implementations together, so the project’s tone choices are reviewable independently of runtime behaviour and can be evolved without editing the skill body.

Install & first runs

Install & first runs has the install command for this family, the files to configure before the first run, and the skills to try first.

Skills

Skill Purpose Status
pr-management-thread-mentor Draft a teaching-register comment on a single GitHub issue or PR thread; waits for maintainer confirmation before posting. experimental
good-first-issue-author Draft one net-new good first issue from a supplied gap or small task; a suitability gate and R1–R9 readiness checklist gate the draft; waits for maintainer confirmation before filing via gh. experimental
mentoring-welcome Draft a first-contact orientation comment for a first-time contributor on a newly opened issue or PR; detects first-time authorship via the GitHub author_association field; skips repeat contributors. experimental
newcomer-issue-explainer Explain a single issue’s context, relevant code paths, and expected approach to a newcomer who has claimed it; teaching register, never gatekeeps. experimental
good-first-issue-sweep Sweep the open issue backlog for existing issues that could be labelled as good first issues; scores each against the G1–G7 suitability rubric and classifies as READY / NEAR-MISS / SKIP; proposes labels only after explicit maintainer confirmation. experimental
contributor-to-committer Read-only brief showing a contributor’s GitHub activity next to the adopter’s committer/PMC reference levels as plain numbers with the difference; surfaces information only — no ranking, status, or readiness verdict, the PMC decides. (family: contributor-growth — cross-listed here for the mentoring path continuity.) experimental

All six skills are read-only on tracker state or draft-then-confirm: no skill posts, labels, closes, or files anything without explicit maintainer confirmation in-session.

What each skill covers

  • pr-management-thread-mentor — the thread-level Agentic Mentoring skill. Invoke it with /magpie-pr-management:thread-mentor. The magpie-pr-management plugin provides it. It reads an issue or PR thread, decides whether a teaching-register intervention is warranted (clarifying question, convention pointer, paired example from a prior PR), drafts the comment, and waits for maintainer confirmation before posting. Never reviews code, routes PRs, or authors fixes — those are Agentic Triage and Agentic Drafting respectively.
  • good-first-issue-author — the issue on-ramp skill. Takes a maintainer- supplied gap or small task, applies a suitability gate (too large, security- sensitive, or requiring a design decision → decline), runs through R1–R9 readiness criteria, and drafts one self-contained issue a newcomer can pick up without prior repo context: scope, code pointers, contributing-doc links, acceptance criteria, and a rough effort estimate.
  • mentoring-welcome — the first-contact skill. Triggered immediately after a first-time contributor opens an issue or PR. Drafts a lightweight orientation comment (contributing-guide link, community-norm pointers, expected next steps). Skips silently for repeat contributors and security-sensitive threads.
  • newcomer-issue-explainer — the issue-context skill. When a newcomer claims a good-first-issue, explains the relevant code paths, project context, and expected approach in a teaching register.
  • contributor-to-committer — the activity-brief skill. Takes a GitHub handle, fetches their public activity on <upstream>, and shows it next to the adopter’s committer or PMC reference levels from committer-readiness.md, as plain numbers with the difference. It only surfaces information: no status, band, ranking, or readiness verdict — the PMC decides. Read-only; never opens a nomination thread, sends a message, or modifies any record.
  • good-first-issue-sweep — the backlog-curation skill. Sweeps the open issue backlog and scores each issue against the G1–G7 suitability rubric (scope, self-containment, code pointer, small effort, no security sensitivity, no architectural decision, no deprecation decision). Classifies each as READY (propose the GFI label), NEAR-MISS (surface specific edits that would make it GFI-ready), or SKIP (not suitable). Complements good-first-issue-author: the sweep stocks the on-ramp queue from existing work; the author creates net-new issues from supplied gaps. Read-only; proposes labels only after explicit maintainer confirmation.

Adopter contract

The generated table under Before the first run lists every file these skills read. The spec’s adopter-contract section documents the keys inside each one.

Status

Experimental. Six skills shipped. No adopter has run the full contributor-to-committer interaction path under evaluation conditions yet; shape may change between framework versions.

To provide pilot feedback, copy docs/pilot-report-template.md into your project notes, fill in each section, and optionally validate the filled-in report with:

uv run --project tools/pilot-report-validator pilot-report-validate <your-report.md>

Cross-references

Suggest a change