skills: add a review skill for Gophercloud by winiciusallan · Pull Request #3986 · gophercloud/gophercloud

winiciusallan · 2026-08-27T19:10:15Z

This commit introduces a new skill for helping reviewers and authors to thoroughly review their codes and follow the best project practices, leveraging the use of AI to achieve this.

coveralls · 2026-08-27T19:15:55Z

coverage: 63.588% (+0.008%) from 63.58% — winiciusallan:review-skill into gophercloud:main

This commit introduces a new skill for helping reviewers and authors to thoroughly review their codes and follow the best project practices, leveraging the use of AI to achieve this.

mandre

This is most welcome, thanks! I believe we should try to rely more on AGENTS.md rather than trying to restating some of the project conventions.

mandre · 2026-08-28T06:57:52Z

+- Follow existing package patterns over inventing new ones.
+- List `Page` types whose JSON body has more than one top-level key (besides `*links`) must implement `pagination.KeyedPage` (`ResourceKey()`), so `AllPages` does not guess the collection key. See `pagination/pager.go` and [gophercloud#3947](https://github.com/gophercloud/gophercloud/pull/3947).
+- Assertion order is **expected, actual**: `th.AssertEquals(t, expected, actual)`.
+- Cite code with `startLine:endLine:path`.


Shouldn't it be path:line as above (line 43)? Or perhaps path:startLine-endLine for multiline citations.

yup! specified that.

mandre · 2026-08-28T08:48:09Z

+---
+name: review-gophercloud
+description: Review Gophercloud Go SDK code for API coverage gaps, convention violations, microversion mistakes, missing tests, and bugs. Use when the user invokes this skill or asks to review Gophercloud packages, PRs, diffs, or OpenStack API implementations.
+disable-model-invocation: true


We may actually want to remove the disable-model-invocation: true setting so that the skill is visible to the agent. Otherwise it forces you to invoke the skill with a slash command, which kinda defeats the purpose IMO.

This is tipically the review that you, as a user, would invoke, but is not harmful if your favorite clanker decide to start reviewing some code (there should be something in the context to do so).

With other changes, I removed the model invocation boolean.

mandre · 2026-08-28T08:56:52Z

@@ -0,0 +1,91 @@
+# Gophercloud review checklist
+
+Copy this list into the review notes and check items that apply. Skip items that are N/A and say so.


This new skill has a LOT of overlap with AGENTS.md, which is always loaded as project context. I'd suggest reworking this skill to be more about verification than explaining the project conventions.

Having overlapping content is also another potential source of drift over time.

YES! This makes a lot of sense and I learned a lot how agents work with skills.

Now we have a much smaller skill file and now keeping the project conventions in AGENTS.md as a single source of truth for this. Now, we have general and discoverable instructions about the review process. My personal experience is doing great... if you want to try it out.

The skill drops from ~280 to ~98 lines and no longer restates conventions that belong in AGENTS.md.

winiciusallan · 2026-09-08T20:05:35Z

@mandre may I have another round of review? :)

mandre · 2026-09-14T12:57:14Z

-## Key Reminders
+### 5.3 KeyedPage interface
+
+`AllPages` concatenates list bodies. By default it picks the first top-level JSON key that is not `*links` and whose value is an array.


nit:

Suggested change

`AllPages` concatenates list bodies. By default it picks the first top-level JSON key that is not `*links` and whose value is an array.

`AllPages` concatenates list bodies. By default it picks an arbitrary top-level JSON key that is not `*links` and whose value is an array.

(go map iteration order is non-deterministic).

mandre · 2026-09-14T13:03:46Z

@@ -0,0 +1,98 @@
+---
+name: review-gophercloud
+description: Review Gophercloud Go SDK code for API coverage gaps, convention violations, microversion mistakes, missing tests, and bugs. Use when the user invokes this skill or asks to review Gophercloud packages, PRs, diffs, or OpenStack API implementations.


That's quite a long description, and the second sentence is redundant. Keep in mind that the frontmatter always end up in the system prompt, so if we can save a few char it's nice.

Suggested change

description: Review Gophercloud Go SDK code for API coverage gaps, convention violations, microversion mistakes, missing tests, and bugs. Use when the user invokes this skill or asks to review Gophercloud packages, PRs, diffs, or OpenStack API implementations.

"Gophercloud: Review packages, PRs, and diffs for convention violations, API coverage gaps, microversion mistakes, missing tests, and bugs."

mandre · 2026-09-14T13:07:10Z

+
+## Patterns
+
+Do not restate repository conventions here. Read [AGENTS.md](../../../AGENTS.md) and cite the matching section when a finding is a pattern violation, for example `AGENTS.md § 2.4` or `see § 5.3`.


Pick one convention, and stick with it.

Suggested change

Do not restate repository conventions here. Read [AGENTS.md](../../../AGENTS.md) and cite the matching section when a finding is a pattern violation, for example `AGENTS.md § 2.4` or `see § 5.3`.

Do not restate repository conventions here. Read [AGENTS.md](../../../AGENTS.md) and cite the matching section when a finding is a pattern violation, for example `AGENTS.md § 2.4`.

mandre · 2026-09-14T13:10:36Z

+
+Do not restate repository conventions here. Read [AGENTS.md](../../../AGENTS.md) and cite the matching section when a finding is a pattern violation, for example `AGENTS.md § 2.4` or `see § 5.3`.
+
+Consult AGENTS.md for: running tests and lint (§ 1); imports, file layout, naming, and OptsBuilder (§ 2.1–2.3); pointers, `omitempty`, errors, and GoDoc (§ 2.4–2.6); unit and acceptance tests (§ 2.7); microversions (§ 3, § 6); pull requests (§ 4); `context.Context`, pagination, and the KeyedPage interface (§ 5).


I have a suspicion the paragraph number is going to drift very quickly :D. Consider removing them.

github-actions Bot added semver:patch No API change backport-v2 This PR will be backported to v2 labels Aug 27, 2026

skills: add a review skill for Gophercloud

ef79e32

This commit introduces a new skill for helping reviewers and authors to thoroughly review their codes and follow the best project practices, leveraging the use of AI to achieve this.

winiciusallan force-pushed the review-skill branch from 0d90297 to ef79e32 Compare August 27, 2026 19:36

mandre reviewed Aug 28, 2026

View reviewed changes

skills: slim the review skill and improve from usage

e9c66bc

The skill drops from ~280 to ~98 lines and no longer restates conventions that belong in AGENTS.md.

github-actions Bot added semver:minor Backwards-compatible change and removed semver:patch No API change labels Sep 8, 2026

mandre reviewed Sep 14, 2026

View reviewed changes

Navigation Menu

Uh oh!

skills: add a review skill for Gophercloud - #3986

skills: add a review skill for Gophercloud#3986
winiciusallan wants to merge 2 commits into
gophercloud:mainfrom
winiciusallan:review-skill

winiciusallan commented Aug 27, 2026

Uh oh!

coveralls commented Aug 27, 2026 •

edited

Loading

Uh oh!

mandre left a comment

Uh oh!

mandre Aug 28, 2026

Uh oh!

winiciusallan Sep 8, 2026

Uh oh!

mandre Aug 28, 2026

Uh oh!

winiciusallan Sep 8, 2026 •

edited

Loading

Uh oh!

mandre Aug 28, 2026

Uh oh!

winiciusallan Sep 8, 2026

Uh oh!

winiciusallan commented Sep 8, 2026

Uh oh!

mandre Sep 14, 2026

Uh oh!

mandre Sep 14, 2026

Uh oh!

mandre Sep 14, 2026

Uh oh!

mandre Sep 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		@@ -0,0 +1,91 @@
		# Gophercloud review checklist

		Copy this list into the review notes and check items that apply. Skip items that are N/A and say so.

	`AllPages` concatenates list bodies. By default it picks the first top-level JSON key that is not `*links` and whose value is an array.
	`AllPages` concatenates list bodies. By default it picks an arbitrary top-level JSON key that is not `*links` and whose value is an array.

	description: Review Gophercloud Go SDK code for API coverage gaps, convention violations, microversion mistakes, missing tests, and bugs. Use when the user invokes this skill or asks to review Gophercloud packages, PRs, diffs, or OpenStack API implementations.
	"Gophercloud: Review packages, PRs, and diffs for convention violations, API coverage gaps, microversion mistakes, missing tests, and bugs."


		## Patterns

		Do not restate repository conventions here. Read [AGENTS.md](../../../AGENTS.md) and cite the matching section when a finding is a pattern violation, for example `AGENTS.md § 2.4` or `see § 5.3`.


		Do not restate repository conventions here. Read [AGENTS.md](../../../AGENTS.md) and cite the matching section when a finding is a pattern violation, for example `AGENTS.md § 2.4` or `see § 5.3`.

		Consult AGENTS.md for: running tests and lint (§ 1); imports, file layout, naming, and OptsBuilder (§ 2.1–2.3); pointers, `omitempty`, errors, and GoDoc (§ 2.4–2.6); unit and acceptance tests (§ 2.7); microversions (§ 3, § 6); pull requests (§ 4); `context.Context`, pagination, and the KeyedPage interface (§ 5).

Uh oh!

Conversation

winiciusallan commented Aug 27, 2026

Uh oh!

coveralls commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mandre left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

winiciusallan Sep 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

winiciusallan commented Sep 8, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

coveralls commented Aug 27, 2026 •

edited

Loading

winiciusallan Sep 8, 2026 •

edited

Loading