Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
- [Linking tracker issues and PRs](#linking-tracker-issues-and-prs)
- [Mentioning project maintainers and security-team members](#mentioning-project-maintainers-and-security-team-members)
- [Reusable skills](#reusable-skills)
- [Reviewing pull requests](#reviewing-pull-requests)
- [Keeping evals and mode-economics in sync](#keeping-evals-and-mode-economics-in-sync)
- [When the rule fires](#when-the-rule-fires)
- [Before submitting](#before-submitting)
Expand Down Expand Up @@ -917,6 +918,20 @@ When adding a new skill:
- avoid agent-specific syntax so the skill remains portable across tools;
- **ship a behavioural eval suite** under [`tools/skill-evals/evals/<skill-name>/`](tools/skill-evals/) — see [Keeping evals and mode-economics in sync](#keeping-evals-and-mode-economics-in-sync). The [`write-skill`](skills/write-skill/SKILL.md) skill prompts for the capability frontmatter on every new-skill scaffold. A skill PR without a matching eval suite is incomplete.

### Reviewing pull requests

For PR code review in this repo, use the
[`pr-management-code-review`](skills/pr-management-code-review/SKILL.md)
skill — not an ad-hoc review pass or a generic review command. It
anchors every finding as an **inline review comment** (`file:line`),
presents the drafted comments to the maintainer **individually for
accept/skip**, and posts the accepted set as a single review. A
body-only review is the explicit opt-out (`inline:off`), never the
default; findings that cannot be anchored to a changed line go in the
review body. Adopters that install the `pr-management-*` family inherit
the same default in their own `AGENTS.md` (wired by
[`skills/setup/adopt.md`](skills/setup/adopt.md)).

## Keeping evals and mode-economics in sync

When you change a skill or a tool adapter the skills load, two
Expand Down
17 changes: 11 additions & 6 deletions skills/pr-management-code-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -509,12 +509,17 @@ For each PR in the list, run the per-PR review loop in
[`posting.md#disposition`](posting.md), apply Golden rules 7
and 8, and produce a draft body using the templates in
[`posting.md`](posting.md).
6. **Show the inline-comments picker** — for every anchored
finding the skill drafts an inline review comment and
presents them in a numbered list with all entries enabled
by default. The maintainer picks `[A]ll` / `[N]one` /
`[<indices>]` / drops a few. Suppressed for the whole
session if `inline:off` was passed.
6. **Show the inline-comments picker** — inline review
comments are the **default and preferred** output of this
skill: for every anchored finding the skill drafts an
inline review comment and presents them in a numbered list
with all entries enabled by default, so the maintainer
accepts them individually. The maintainer picks `[A]ll` /
`[N]one` / `[<indices>]` / drops a few. A body-only review
is the explicit exception, reached only by passing
`inline:off`, which suppresses the picker for the whole
session. Findings that cannot be anchored to a `file:line`
(e.g. on unchanged lines) go in the review body instead.
7. **Show the draft to the maintainer** — full body, count of
inline comments to be posted, and the chosen disposition.
8. **On confirmation** — post via the GraphQL
Expand Down
18 changes: 18 additions & 0 deletions skills/setup/adopt.md
Original file line number Diff line number Diff line change
Expand Up @@ -1120,6 +1120,24 @@ framework before they hit a "skill not found" error:
[`apache/magpie`](https://github.com/apache/magpie).
```

**If the adopter installed the `pr-management-*` family**
(Step 5), append the following subsection to the
`AGENTS.md` block above, so the adopter's agent defaults to
the framework's review skill. Skip it entirely for adopters
who did not take that family.

```markdown
### Reviewing pull requests

With apache-magpie installed locally, use the
`magpie-pr-management-code-review` skill for PR code
review. It posts findings as **inline review comments**
anchored to `file:line`, presented **individually for
accept/skip** before anything is submitted — prefer it
over an ad-hoc review pass or a generic review command. A
body-only review is the explicit opt-out (`inline:off`).
```

Do not create `AGENTS.md` if it does not already exist —
the contributor-facing section in `README.md` is the
authoritative entry-point, and an empty `AGENTS.md` would
Expand Down