docs(agents): point skill authoring at agent-skills, not the synced plugin copy#2475
docs(agents): point skill authoring at agent-skills, not the synced plugin copy#2475devantler wants to merge 1 commit into
Conversation
…lugin copy § Agent definition locations named plugins/agentic-engineering/skills/agent-improvement/SKILL.md as a version-controlled authoring surface. That file carries metadata.github-repo provenance and is re-pulled by the daily update-agent-skills workflow, so an edit there survives until the next sync and then silently disappears — no conflict, no CI failure, no signal. The same plugin directory's agents/agent-improver.agent.md carries no provenance and IS authored there, so the rule is per-file, not per-directory. Points skill bodies at devantler-tech/agent-skills, keeps the agents half unchanged, and states the grep -l github-repo check so the next new file is classified rather than guessed. Adds a guard test (4 assertions, each individually RED-proven) wired into CI through its own paths filter, which lists the guard and ci.yaml so deleting either still runs it.
Readiness evidence @
|
| # | Assertion | Mutation | Result |
|---|---|---|---|
| 1 | no concrete plugins/<p>/skills/<s>/SKILL.md named |
re-insert the old path | FAIL ✓ |
| 2 | devantler-tech/agent-skills named |
rewrite the slug | FAIL ✓ |
| 3 | agents/agent-improver.agent.md still named |
rename it | FAIL ✓ |
| 4 | metadata.github-repo check stated |
drop the key | FAIL ✓ |
Unmutated: 4/4 pass. Full-tree RED/GREEN also run against the pre-fix AGENTS.md from
origin/main (FAIL) and the fixed text (OK).
Two of these assertions were vacuous when first written and were caught by the probes,
not by inspection — agent-skills was satisfied by the update-agent-skills workflow
name in the same paragraph, and a bare github-repo by neighbouring prose. Both were
tightened to the full slug and the exact metadata key.
Full contract suite: 15/15 green. Repo CI at this head: 25 success / 7 skipped / 0 failure.
Wiring verified behaviourally, not by inspection. The job's paths-filter output was
initially not declared on the changes job, which would have left
needs.changes.outputs.authoring-surface empty and the job silently never running —
a green CI that proves nothing. Declared it, then cross-checked that every filter has an
output and every output has a consumer (both clean), and confirmed the check-run actually
executed at this head rather than skipping:
Test authoring-surface provenance — success (00:21:39Z → 00:21:44Z)
Tried as a user. I used the new instruction on its own subject this run: ran
grep -l github-repo against the merged agent-plugins tip and it correctly classified
skills/agent-improvement/SKILL.md as synced (github-repo: …/agent-skills,
github-ref: refs/tags/v1.9.1) and agents/agent-improver.agent.md as authored
(no provenance). Confirmed agent-skills really does own agent-improvement/SKILL.md.
The instruction answers the question it claims to answer.
@coderabbitai review |
|
✅ Action performedReview finished.
|
|
Warning Review limit reached
Next review available in: 12 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Repository YAML (base), Organization UI (inherited) Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (3)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Closing as a duplicate of #2474, which predates this by 78 minutes (23:02:48Z vs Per the claim protocol I abandon rather than compete. I diffed the two implementations
Issue #2476 (filed here for the defect) stays open and is the tracking issue for #2474. |
1 participant
Why
The contract told a future agent to edit a file that silently discards its edits.
§ Agent definition locationsnamed the Agent Improver's skill body insideagent-pluginsas a place to author changes — but that copy is pulled in from anotherrepository every day, so an edit there looks fine, passes review, merges, and then
quietly disappears at the next sync. No conflict, no failing check, nothing to notice.
The trap is easy to fall into because the same folder holds both kinds of file: the
agent definition next to it really is authored there. This was caught for real on an
agent-pluginsPR last week and rated a major finding.What
Points skill changes at the repository that actually owns them, leaves the agent half
alone, and states the one-line check that tells the two apart — so the next file added
to that folder gets classified rather than guessed at.
Adds a guard so the contract cannot drift back, wired into CI in a way that still runs
if a later change tries to delete the guard itself.
Fixes #2476