chore: add AIP skills#4134
Merged
tothandras merged 1 commit intomainfrom Apr 13, 2026
Merged
Conversation
tothandras
added
the
release-note/ignore
Contributor
📝 WalkthroughWalkthroughReplaces a monolithic AIP README with many focused AIP rule files and adds an API-filters skill; updates the API skill guidance and removes an outdated AIP symlink. All changes are documentation-only and do not modify exported code entities. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~4 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (5)
.agents/skills/api/rules/aip-181-stability.md (1)
22-24: Clarify whether lifecycle annotations are required vs illustrativeTiny wording tweak: right now this can read like every stage must include those exact markers. If this is an example maturity path, saying that explicitly would avoid over-prescribing.
✍️ Suggested wording tweak
-1. **Development** — both `x-unstable`, `x-internal` and `x-private` applied. -2. **Stabilizing** — `x-internal` and `x-private`; internal consumers may rely on the shape, but the API is not yet public -3. **Public** — no annotations present +1. **Development (example)** — typically `x-unstable` + `x-internal` (optionally `x-private` when not gateway-exposed). +2. **Stabilizing (example)** — typically `x-internal` (and optionally `x-private`); internal consumers may rely on the shape, but the API is not yet public. +3. **Public** — no stability annotations present.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/skills/api/rules/aip-181-stability.md around lines 22 - 24, Update the wording in the three-bullet section that lists "Development — both `x-unstable`, `x-internal` and `x-private`", "Stabilizing — `x-internal` and `x-private`", and "Public — no annotations present" to make clear these are example annotations and not mandatory requirements; explicitly state that this is an illustrative maturity path and teams may use different or additional lifecycle markers as needed, e.g., add a sentence like "These markers are examples of a possible maturity path and are not required; teams may adopt different annotations or conventions." Ensure the clarification is placed adjacent to the existing bullets so readers immediately understand the intent.api/spec/README.md (1)
22-25: Add a pointer to the new AIP guidance locationNice cleanup overall. One small gap: after simplifying this section, there’s no longer a “where to find AIP rules/patterns” pointer. Adding a short reference here would keep onboarding smooth for spec authors. (Line 22–25)
As per coding guidelines, “Completeness: Confirm all features and changes are properly documented.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@api/spec/README.md` around lines 22 - 25, Add a brief pointer to Kong’s AIP guidance in the api/spec/README.md where the OpenMeter and Konnect bullets are described: edit the paragraph that lists "OpenMeter (openmeter.tsp)" and "Konnect (konnect.tsp)" to append a short sentence linking to Kong’s AIP guidance (https://kong-aip.netlify.app/list/) so spec authors know where to find AIP rules/patterns; ensure the sentence mentions "Kong AIP guidance" and places the URL inline for quick access..agents/skills/api/rules/aip-3101-versioning.md (1)
19-25: Optional: unify placeholder style in pathsTiny consistency nit: Line 19–20 uses
{resource}while Line 25 uses<resource>. Using one style throughout would make examples feel tighter.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/skills/api/rules/aip-3101-versioning.md around lines 19 - 25, Unify the placeholder style by making the OpenMeter example use the same curly-brace style as the other paths: change `/api/v3/openmeter/<resource>` to `/api/v3/openmeter/{resource}` so all examples use `{resource}` consistently with `/v{major}/{resource}` and `/{service-prefix}/v{major}/{resource}`..agents/skills/api/rules/aip-160-filtering.md (1)
53-53: Minor: "not currently modeled" vs documented behaviorLine 53 says
existsandnexists"are not currently modeled in anyCommon.*FieldFilteroneOfshape", but then line 66 documentsnexistsusage. The distinction makes sense (not in schema vs. handled at query-parameter layer), but readers might get confused. Maybe a forward reference like "see line 66 for usage despite not being schema-modeled" would help?🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/skills/api/rules/aip-160-filtering.md at line 53, Clarify the phrasing around AIP-160 operators by updating the sentence that says `exists` and `nexists` "are not currently modeled in any `Common.*FieldFilter` `oneOf` shape" to add a forward reference to the later documentation of `nexists` usage; specifically mention that although `Common.*FieldFilter` schemas don't include `exists`/`nexists`, `nexists` is handled at the query-parameter layer (see the later `nexists` usage example) so readers aren’t confused about schema vs. query-layer behavior..agents/skills/api/rules/aip-158-pagination.md (1)
16-16: Tiny terminology note on "XOR cipher"Just a nitpick: "XOR cipher" might be clearer as "XOR-based obfuscation" since XOR alone isn't cryptographically secure. If the goal is just to make cursors opaque (not secure them), that's totally fine - might be worth a quick clarifying word to avoid setting security expectations.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/skills/api/rules/aip-158-pagination.md at line 16, Replace the phrase "XOR cipher" in the sentence that reads "Cursors must be **opaque** to clients... uses base64url with an XOR cipher to obscure cursor internals" with a clearer term like "XOR-based obfuscation" or "XOR-based encoding" to avoid implying cryptographic security; keep the description that base64url plus XOR is for opacity (not security) and optionally add a short parenthetical note that this is obfuscation rather than cryptographic protection.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.agents/skills/api/rules/aip-134-135-crud.md:
- Line 28: Update the Content-Type validation status code: replace the sentence
"Rejects requests with `Content-Type` other than `application/json` with `400
Bad Request`" in .agents/skills/api/rules/aip-134-135-crud.md so it uses `415
Unsupported Media Type` instead of `400 Bad Request`; ensure the text references
`application/json` rejection returning 415 to align with
aip-137-content-type.md.
In @.agents/skills/api/rules/aip-160-filtering.md:
- Line 11: Update the note for `public_labels` to clarify that
`Common.LabelsFieldFilter` is used instead of `PublicLabelsFieldFilter` for
structural reasons: state that both `Common.LabelsFieldFilter` and
`PublicLabelsFieldFilter` are operationally equivalent (both spread
`StringFieldFilter`) so they can be used interchangeably, and that the choice
here reflects how the shared `Shared.ResourceFilters` type was organized rather
than a behavioral difference; reference the symbols `public_labels`,
`Common.LabelsFieldFilter`, `PublicLabelsFieldFilter`, `StringFieldFilter`, and
`Shared.ResourceFilters` so readers can locate the types if they want to verify.
In @.agents/skills/api/rules/aip-193-errors.md:
- Around line 41-48: The table references Common.PayloadTooLarge but that model
and HTTP 413 are not defined in the common TypeSpec error models; either add a
new Common.PayloadTooLarge error model with status 413 to the shared/common
TypeSpec error definitions (alongside other Common.* models) and wire it into
any relevant responses, or remove the `Common.PayloadTooLarge` row from the
table so the doc matches the spec; ensure the Common.* error registry and any
examples are updated to include the new model if you add it.
In @.agents/skills/api/rules/aip-235-bulk-delete.md:
- Around line 23-24: Update the statement in aip-235-bulk-delete.md that
currently says "If any target is missing or the caller lacks permission, the
whole operation fails with `400 Bad Request`" so it follows the access-control
rules in aip-193-errors.md: specify that permission failures return `403
Forbidden` when the resource exists in-tenant but the caller lacks access, and
`404 Not Found` when the resource is not in-tenant or does not exist; replace
the single `400` claim with this bifurcated behavior and add a short
cross-reference to aip-193-errors.md for consistency.
- Line 5: The sentence claiming "DELETE does not accept a body" is misleading;
modify the text in aip-235-bulk-delete.md so it states that this API
intentionally uses POST at "/<entity>/bulk-delete" to express RPC-style
semantics and maximize interoperability (since DELETE request bodies have
undefined semantics per RFCs), rather than asserting DELETE forbids a body.
Update the line that currently reads "DELETE does not accept a body" to a
concise explanation referencing the chosen endpoint "/<entity>/bulk-delete" and
the reasons: clearer RPC semantics and better client/server interoperability.
In @.agents/skills/api/SKILL.md:
- Line 337: The table entry currently reads "Unknown" but should use the
lowercase "unknown" to match the rule document; update the row text in
.agents/skills/api/SKILL.md (the cell referencing `rules/aip-126-enums.md`) to
read `unknown` instead of `Unknown` so the casing matches the
`rules/aip-126-enums.md` specification.
---
Nitpick comments:
In @.agents/skills/api/rules/aip-158-pagination.md:
- Line 16: Replace the phrase "XOR cipher" in the sentence that reads "Cursors
must be **opaque** to clients... uses base64url with an XOR cipher to obscure
cursor internals" with a clearer term like "XOR-based obfuscation" or "XOR-based
encoding" to avoid implying cryptographic security; keep the description that
base64url plus XOR is for opacity (not security) and optionally add a short
parenthetical note that this is obfuscation rather than cryptographic
protection.
In @.agents/skills/api/rules/aip-160-filtering.md:
- Line 53: Clarify the phrasing around AIP-160 operators by updating the
sentence that says `exists` and `nexists` "are not currently modeled in any
`Common.*FieldFilter` `oneOf` shape" to add a forward reference to the later
documentation of `nexists` usage; specifically mention that although
`Common.*FieldFilter` schemas don't include `exists`/`nexists`, `nexists` is
handled at the query-parameter layer (see the later `nexists` usage example) so
readers aren’t confused about schema vs. query-layer behavior.
In @.agents/skills/api/rules/aip-181-stability.md:
- Around line 22-24: Update the wording in the three-bullet section that lists
"Development — both `x-unstable`, `x-internal` and `x-private`", "Stabilizing —
`x-internal` and `x-private`", and "Public — no annotations present" to make
clear these are example annotations and not mandatory requirements; explicitly
state that this is an illustrative maturity path and teams may use different or
additional lifecycle markers as needed, e.g., add a sentence like "These markers
are examples of a possible maturity path and are not required; teams may adopt
different annotations or conventions." Ensure the clarification is placed
adjacent to the existing bullets so readers immediately understand the intent.
In @.agents/skills/api/rules/aip-3101-versioning.md:
- Around line 19-25: Unify the placeholder style by making the OpenMeter example
use the same curly-brace style as the other paths: change
`/api/v3/openmeter/<resource>` to `/api/v3/openmeter/{resource}` so all examples
use `{resource}` consistently with `/v{major}/{resource}` and
`/{service-prefix}/v{major}/{resource}`.
In `@api/spec/README.md`:
- Around line 22-25: Add a brief pointer to Kong’s AIP guidance in the
api/spec/README.md where the OpenMeter and Konnect bullets are described: edit
the paragraph that lists "OpenMeter (openmeter.tsp)" and "Konnect (konnect.tsp)"
to append a short sentence linking to Kong’s AIP guidance
(https://kong-aip.netlify.app/list/) so spec authors know where to find AIP
rules/patterns; ensure the sentence mentions "Kong AIP guidance" and places the
URL inline for quick access.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 0e751c47-2264-42c3-ae3e-1329e7139c10
📒 Files selected for processing (22)
.agents/skills/api-filters/SKILL.md.agents/skills/api/AIP.md.agents/skills/api/SKILL.md.agents/skills/api/rules/aip-122-naming.md.agents/skills/api/rules/aip-126-enums.md.agents/skills/api/rules/aip-129-labels.md.agents/skills/api/rules/aip-132-list.md.agents/skills/api/rules/aip-134-135-crud.md.agents/skills/api/rules/aip-137-content-type.md.agents/skills/api/rules/aip-142-time.md.agents/skills/api/rules/aip-158-pagination.md.agents/skills/api/rules/aip-160-filtering.md.agents/skills/api/rules/aip-181-stability.md.agents/skills/api/rules/aip-193-errors.md.agents/skills/api/rules/aip-235-bulk-delete.md.agents/skills/api/rules/aip-3101-versioning.md.agents/skills/api/rules/aip-3106-empty-fields.md.agents/skills/api/rules/aip-composition.md.agents/skills/api/rules/aip-docs.md.agents/skills/api/rules/aip-visibility.mdapi/spec/README.mdapi/spec/packages/aip/README.md
💤 Files with no reviewable changes (2)
- .agents/skills/api/AIP.md
- api/spec/packages/aip/README.md
tothandras
force-pushed
the
chore/api-v3-skills
branch
from
5d02c35 to
cd07925
Compare
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@api/spec/packages/aip/src/common/error.tsp`:
- Around line 64-72: The new model PayloadTooLarge is defined but not exposed in
the shared error contract; update the shared aliases and mapping so 413 is
included: add the PayloadTooLarge response to the alias ErrorResponses (so the
413 model is part of the union) and update the ErrorResponse definition in
api/spec/packages/aip/common/definitions/errors.yaml by adding '413':
'#/components/responses/PayloadTooLarge' to the oneOf/discriminator.mapping
entries; ensure you reference the model name PayloadTooLarge and the alias
ErrorResponses and ErrorResponse when making these edits so the 413 response is
surfaced consistently.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 527d0087-517f-4ec2-9e28-98b3d568104c
📒 Files selected for processing (23)
.agents/skills/api-filters/SKILL.md.agents/skills/api/AIP.md.agents/skills/api/SKILL.md.agents/skills/api/rules/aip-122-naming.md.agents/skills/api/rules/aip-126-enums.md.agents/skills/api/rules/aip-129-labels.md.agents/skills/api/rules/aip-132-list.md.agents/skills/api/rules/aip-134-135-crud.md.agents/skills/api/rules/aip-137-content-type.md.agents/skills/api/rules/aip-142-time.md.agents/skills/api/rules/aip-158-pagination.md.agents/skills/api/rules/aip-160-filtering.md.agents/skills/api/rules/aip-181-stability.md.agents/skills/api/rules/aip-193-errors.md.agents/skills/api/rules/aip-235-bulk-delete.md.agents/skills/api/rules/aip-3101-versioning.md.agents/skills/api/rules/aip-3106-empty-fields.md.agents/skills/api/rules/aip-composition.md.agents/skills/api/rules/aip-docs.md.agents/skills/api/rules/aip-visibility.mdapi/spec/README.mdapi/spec/packages/aip/README.mdapi/spec/packages/aip/src/common/error.tsp
💤 Files with no reviewable changes (2)
- .agents/skills/api/AIP.md
- api/spec/packages/aip/README.md
✅ Files skipped from review due to trivial changes (18)
- .agents/skills/api/rules/aip-3101-versioning.md
- .agents/skills/api/rules/aip-visibility.md
- .agents/skills/api/rules/aip-composition.md
- .agents/skills/api/rules/aip-docs.md
- .agents/skills/api/rules/aip-3106-empty-fields.md
- .agents/skills/api/rules/aip-137-content-type.md
- .agents/skills/api/rules/aip-142-time.md
- .agents/skills/api/rules/aip-122-naming.md
- .agents/skills/api/rules/aip-235-bulk-delete.md
- .agents/skills/api/rules/aip-193-errors.md
- .agents/skills/api/rules/aip-132-list.md
- .agents/skills/api/rules/aip-129-labels.md
- .agents/skills/api/rules/aip-181-stability.md
- .agents/skills/api/SKILL.md
- .agents/skills/api/rules/aip-158-pagination.md
- .agents/skills/api/rules/aip-134-135-crud.md
- api/spec/README.md
- .agents/skills/api/rules/aip-160-filtering.md
🚧 Files skipped from review as they are similar to previous changes (2)
- .agents/skills/api/rules/aip-126-enums.md
- .agents/skills/api-filters/SKILL.md
chrisgacsal
approved these changes
Apr 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Based on https://kong-aip.netlify.app/
Summary by CodeRabbit