Skip to content
Back to search

aip-proto

MarketplaceWorks with Claude CodeGitHub

Skills for designing and auditing protobuf/gRPC APIs against Google's API Improvement Proposals.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rustlanglatam--aip-proto/badge.svg)](/listings/rustlanglatam--aip-proto)

HTML

<a href="/listings/rustlanglatam--aip-proto"><img src="/api/listings/rustlanglatam--aip-proto/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Inside a Claude Code session:

/plugin marketplace add RustLangLatam/aip-proto
/plugin install aip-proto@aip-proto

Or from a terminal:

claude plugin marketplace add RustLangLatam/aip-proto
claude plugin install aip-proto@aip-proto

Start a new session afterwards so the skills are loaded. Add `--scope project` to `install` to enable them for the current repository only. The setting is written to `.claude/settings.json`, so collaborators get it too.

**Without the plugin system**, copy both folders:

git clone https://github.com/RustLangLatam/aip-proto.git
cp -r aip-proto/skills/aip-design aip-proto/skills/aip-audit ~/.claude/skills/

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 12 lines
  1. {
  2. "name": "aip-proto",
  3. "owner": { "name": "RustLangLatam" },
  4. "description": "Skills for designing and auditing protobuf/gRPC APIs against Google's API Improvement Proposals.",
  5. "plugins": [
  6. {
  7. "name": "aip-proto",
  8. "source": "./",
  9. "description": "Design and audit .proto APIs against Google AIPs (google.aip.dev) using the official api-linter plus a manual review."
  10. }
  11. ]
  12. }
README.md · README · 310 lines
  1. # aip-proto
  2. Two [Agent Skills](https://agentskills.io/specification) that check protobuf / gRPC APIs against Google's
  3. [API Improvement Proposals](https://google.aip.dev/general) (AIPs): one for writing new `.proto` files, one for
  4. auditing existing ones. They work in Claude Code, OpenAI Codex, Gemini CLI, Cursor, GitHub Copilot, OpenCode and
  5. any other client that reads `SKILL.md` folders, with any model.
  6. The automated layer is Google's own [`api-linter`](https://github.com/googleapis/api-linter). In v2.4.1 it has
  7. 340 rules covering 46 of the 73 general AIPs. The skills run it rather than imitate it. The second layer is a
  8. 38-item checklist that the agent works through by reading the protos and, when available, the server code. It
  9. covers what the linter cannot see. In this repository's own test fixture, the linter reports 42 findings but
  10. misses that `Book` is a resource identified by `int64 bookID`, and that `int64 created` is a timestamp stored
  11. as an integer. The checklist catches both ([worked report](docs/examples/AIP-AUDIT.fixture.md)).
  12. > This is an independent, unofficial project. It is not affiliated with or endorsed by Google. A "CERTIFIED"
  13. > verdict is a self-assessment against public guidance.
  14. ## Contents
  15. - [Requirements](#requirements)
  16. - [Install in Claude Code (plugin)](#install-in-claude-code-plugin)
  17. - [Using the skills](#using-the-skills)
  18. - [Install in other clients](#install-in-other-clients)
  19. - [What it does](#what-it-does)
  20. - [The lint script on its own](#the-lint-script-on-its-own)
  21. - [What it does not do](#what-it-does-not-do)
  22. - [Documentation](#documentation)
  23. - [Repository layout](#repository-layout)
  24. ## Requirements
  25. The agent needs a shell tool that can run `bash`. Every client listed below has one. On the machine:
  26. | Tool | Needed for | Install |
  27. |---|---|---|
  28. | **api-linter** | the automated layer (required) | `go install github.com/googleapis/api-linter/v2/cmd/api-linter@latest` (needs Go) |
  29. | **buf** | downloading the `google/api/*.proto` imports once; compatibility checks with `--against` | [buf.build/docs/installation](https://buf.build/docs/installation) |
  30. | bash, find, grep, sed | the wrapper script | preinstalled on Linux and macOS; on Windows use WSL or Git Bash |
  31. If you already have a googleapis checkout, set `AIP_GOOGLEAPIS=/path/to/googleapis` and buf becomes optional.
  32. The first run without it downloads the imports into `~/.cache/aip-proto/googleapis`.
  33. Check your setup:
  34. ```bash
  35. api-linter --version # api-linter 2.4.1 or later
  36. buf --version
  37. ```
  38. Without api-linter, `aip-audit` still does the manual review, but its verdict is always NOT CERTIFIED, and
  39. `aip-design` will not claim that a proto is lint-clean.
  40. ## Install in Claude Code (plugin)
  41. Inside a Claude Code session:
  42. ```
  43. /plugin marketplace add RustLangLatam/aip-proto
  44. /plugin install aip-proto@aip-proto
  45. ```
  46. Or from a terminal:
  47. ```bash
  48. claude plugin marketplace add RustLangLatam/aip-proto
  49. claude plugin install aip-proto@aip-proto
  50. ```
  51. Start a new session afterwards so the skills are loaded. Add `--scope project` to `install` to enable them for
  52. the current repository only. The setting is written to `.claude/settings.json`, so collaborators get it too.
  53. **Without the plugin system**, copy both folders:
  54. ```bash
  55. git clone https://github.com/RustLangLatam/aip-proto.git
  56. cp -r aip-proto/skills/aip-design aip-proto/skills/aip-audit ~/.claude/skills/
  57. ```
  58. ## Using the skills
  59. ### Automatic use (the default)
  60. You do not need to name them. `aip-design` loads when you ask to create, design, scaffold or extend a `.proto`
  61. or gRPC API. `aip-audit` loads when you ask to audit, review, lint, validate or certify protos, or to check AIP
  62. compliance.
  63. ### Explicit use
  64. | Installed as | Design | Audit |
  65. |---|---|---|
  66. | Claude Code plugin | `/aip-proto:aip-design` | `/aip-proto:aip-audit` |
  67. | Plain skill (Claude Code, Cursor, Copilot) | `/aip-design` | `/aip-audit` |
  68. | OpenAI Codex | `$aip-design` | `$aip-audit` |
  69. | OpenCode | `@aip-design` | `@aip-audit` |
  70. | Gemini CLI | automatic; it asks you to activate the skill | same |
  71. Examples:
  72. ```
  73. Design a gRPC API for invoices: customers own invoices, list with filtering by status, and an async PDF export.
  74. Add a Shelf resource with Get and List to proto/acme/library/v1/library.proto.
  75. Audit proto/ for AIP compliance and write AIP-AUDIT.md.
  76. Audit only the protos changed on this branch, against main, in strict mode. The server code is in internal/server.
  77. Audit api/ and fix what you can without breaking v1 clients.
  78. ```
  79. ### What you will see
  80. **When you design**, the agent first writes down the resource model: resources, parents, resource name patterns,
  81. type names, which standard methods each resource gets, and which operations need a custom method or a
  82. long-running operation. If the domain is ambiguous, it asks you about it. Then it copies the
  83. [lint-clean template](skills/aip-design/assets/acme/library/v1/library.proto), adapts it, and runs the linter
  84. until there are 0 findings. It ends by listing what it left out and the behaviour your server must implement (for
  85. example `update_mask` semantics).
  86. **When you audit**, it runs the linter and walks the
  87. [checklist](skills/aip-audit/references/manual-review.md). Each item gets PASS / FAIL / N/A / NOT VERIFIED, with
  88. a file:line reference. The result is an `AIP-AUDIT.md` in [this format](docs/examples/AIP-AUDIT.fixture.md):
  89. verdict, blocking findings with fixes, warnings, justified disables, and the full checklist. If you ask for fixes
  90. on a published API, it adds and deprecates rather than renaming or renumbering, because those break clients
  91. (AIP-180).
  92. ### Managing it
  93. | Task | Command |
  94. |---|---|
  95. | Check that it is installed | `claude plugin list` |
  96. | Update | `claude plugin marketplace update aip-proto` then `claude plugin update aip-proto@aip-proto` |
  97. | Turn off temporarily | `claude plugin disable aip-proto@aip-proto` |
  98. | Turn back on | `claude plugin enable aip-proto@aip-proto` |
  99. | Uninstall | `claude plugin uninstall aip-proto@aip-proto` |
  100. Inside a session, `/plugin` opens the same options interactively.
  101. ## Install in other clients
  102. Each skill is a standard folder under `skills/`. The frontmatter has only `name`, `description`, `license` and
  103. `compatibility`, and the instructions use no client-specific variables, tools or commands. The script paths are
  104. relative to each `SKILL.md`, so the skills work from whatever directory your client loads them. The plugin
  105. manifests in `.claude-plugin/` are read only by Claude Code, and other clients ignore them.
  106. **Always install both folders side by side.** `aip-design` runs the lint script from `../aip-audit/scripts/`.
  107. **One copy covers most clients.** Codex, Gemini CLI, Cursor and OpenCode all read `~/.agents/skills/`:
  108. ```bash
  109. git clone https://github.com/RustLangLatam/aip-proto.git
  110. mkdir -p ~/.agents/skills
  111. cp -r aip-proto/skills/aip-design aip-proto/skills/aip-audit ~/.agents/skills/
  112. ```
  113. To install for one repository only, copy them to `<repo>/.agents/skills/` instead. To get updates with
  114. `git pull`, symlink them instead of copying:
  115. `ln -s "$(pwd)/aip-proto/skills/aip-design" "$(pwd)/aip-proto/skills/aip-audit" ~/.agents/skills/`.
  116. | Client | User directory | Project directory | How it is invoked |
  117. |---|---|---|---|
  118. | **Claude Code** | `~/.claude/skills/` (or the plugin) | `.claude/skills/` | Automatic, or `/aip-audit` |
  119. | **OpenAI Codex** | `~/.agents/skills/` | `.agents/skills/` | Automatic, or `$aip-audit`; `/skills` lists them |
  120. | **Gemini CLI** | `~/.gemini/skills/` or `~/.agents/skills/` | `.gemini/skills/` or `.agents/skills/` | Automatic (asks to activate); `/skills list` to check |
  121. | **Cursor** | `~/.cursor/skills/` or `~/.agents/skills/` (also reads `~/.claude/skills/`) | `.cursor/skills/` or `.agents/skills/` | Automatic, or `/aip-audit` in Agent chat |
  122. | **GitHub Copilot** (VS Code) | `~/.copilot/skills/` | `.github/skills/` | Automatic, or `/aip-audit` |
  123. | **OpenCode** | `~/.config/opencode/skills/` or `~/.agents/skills/` (also reads `~/.claude/skills/`) | `.opencode/skills/` or `.agents/skills/` | Automatic, or `@aip-audit` |
  124. Client-specific notes:
  125. - **Gemini CLI** can install straight from GitHub, one skill at a time:
  126. ```bash
  127. gemini skills install https://github.com/RustLangLatam/aip-proto.git --path skills/aip-audit
  128. gemini skills install https://github.com/RustLangLatam/aip-proto.git --path skills/aip-design
  129. ```
  130. Google's documentation states that Gemini CLI was succeeded by Antigravity CLI in June 2026. Check that
  131. client's docs for its current skills path.
  132. - **GitHub Copilot** does not read `~/.agents/skills/`. Copy both folders to `~/.copilot/skills/` or `.github/skills/`.
  133. - **Cursor and OpenCode** already read `~/.claude/skills/`. A plain-skill install for Claude Code works for them
  134. with no extra step. The Claude Code *plugin* install lives elsewhere, so they do not see it.
  135. - **Clients that ask for approval before shell commands** will prompt for `aip-lint.sh`. Allow-listing it in the client settings stops the prompts.
  136. - **Several clients on one machine:** install once in `~/.agents/skills/`, add a copy (or the plugin) for Claude
  137. Code and one in `~/.copilot/skills/` for Copilot. Do not leave two copies visible to the same client, or it may
  138. list the skills twice.
  139. These paths come from each client's documentation as of November 2026
  140. ([Agent Skills spec](https://agentskills.io/specification), [Codex](https://developers.openai.com/codex/skills),
  141. [Gemini CLI](https://geminicli.com/docs/cli/skills/), [Cursor](https://cursor.com/docs/context/skills),
  142. [VS Code Copilot](https://code.visualstudio.com/docs/copilot/customization/agent-skills),
  143. [OpenCode](https://opencode.ai/docs/skills)). Clients change quickly. If a path stops working, check the linked
  144. page and open an issue.
  145. ## What it does
  146. ### aip-audit
  147. 1. **Scopes** the proto root (the directory that package paths are relative to). It notes whether the API is
  148. already published and whether server code is available.
  149. 2. **Runs `aip-lint.sh`**: api-linter, plus `buf breaking` when there is a base to compare against.
  150. 3. **Walks the checklist**. Its 38 items link 31 AIPs, in five groups:
  151. | Group | Covers | Example item |
  152. |---|---|---|
  153. | R. Resource model | AIP-121–124, 156, 180, 203 | R6: every resource has a `string name` and a resource type, including the ones the linter cannot recognise |
  154. | M. Methods & behaviour | AIP-134, 136, 151, 154, 155, 158, 160, 163, 164, 217 | M4: an omitted `update_mask` means all populated fields, and `*` means full replacement |
  155. | F. Fields | AIP-129, 134, 141–143, 147, 149, 203, 210, 216 | F1: a `REQUIRED` field is really required, and `OUTPUT_ONLY` input is cleared, not rejected |
  156. | E. Errors, auth, retries | AIP-193, 194, 211 | E2: authorization is checked before any validation, so existence is never leaked |
  157. | C. Compatibility | AIP-180, 185, 213, 215 | C1: nothing removed, renamed, retyped or moved within a major version |
  158. 4. **Decides the verdict**:
  159. | Verdict | Condition |
  160. |---|---|
  161. | **CERTIFIED** | 0 linter findings (a disable is allowed only with a written reason), every MUST and SHOULD item PASS or N/A |
  162. | **CERTIFIED WITH WARNINGS** | 0 linter findings, no MUST item FAIL, and either a SHOULD FAIL or a MUST item NOT VERIFIED |
  163. | **NOT CERTIFIED** | any linter finding, any MUST FAIL, a breaking change in a stable version, or the linter was not run |
  164. A proto-only audit, without server code, cannot get past CERTIFIED WITH WARNINGS, because nobody has seen the
  165. behaviour. MUST and SHOULD follow the wording of each AIP, as checked on 2026-11-22. Optional features (MAY,
  166. such as `etag` or `request_id`) are N/A when absent, and when present their MUST parts apply. Findings on
  167. AIP-162 (Draft) and AIP-182 (Reviewing) never block.
  168. 5. **Writes `AIP-AUDIT.md`**, and fixes findings if you asked for that.
  169. ### aip-design
  170. 1. Resource model first (AIP-121/122/123), confirmed with you when the domain is ambiguous.
  171. 2. Copy and adapt the template: the package matches the directory, language options are consistent,
  172. `google.api.resource` is on each resource, `google.api.http` and `method_signature` are on each RPC, and each
  173. field has a `field_behavior` and a comment.
  174. 3. Lint until there are 0 findings. It never suppresses a rule just to reach 0.
  175. 4. Hand-off: what was built, what was left out, and the server behaviour still to implement.
  176. A one-page [cheatsheet](skills/aip-design/references/aip-cheatsheet.md) covers the method table (HTTP mapping,
  177. request fields, return types), field naming, LRO, pagination, filtering, etags, idempotency, soft delete and
  178. error codes. Each entry links its AIP.
  179. ## The lint script on its own
  180. [`skills/aip-audit/scripts/aip-lint.sh`](skills/aip-audit/scripts/aip-lint.sh) needs no agent, so you can use it
  181. in CI or as a pre-commit hook:
  182. ```bash
  183. aip-lint.sh [-o report.json] [--strict] [--against '.git#branch=main,subdir=proto'] <proto_root> [file.proto ...]
  184. ```
  185. | Option | Effect |
  186. |---|---|
  187. | `-o FILE` | JSON report path (api-linter's format: `rule_id`, `rule_doc_uri`, `message`, `location`) |
  188. | `--strict` | ignore inline `(-- api-linter: rule=disabled --)` comments |
  189. | `--against REF` | also run `buf breaking` against a git ref or other buf input. Needs buf and a `buf.yaml` in the root. Local paths are relative to where you run the script, so add `,subdir=<root>` when the root is not the repo root |
  190. | `.api-linter.yaml` in the root | picked up automatically as api-linter config |
  191. | `API_LINTER`, `AIP_GOOGLEAPIS` | override the linter binary and the googleapis directory |
  192. | exit code | `0` clean · `1` findings or breaking changes · `2` setup, compile or buf error (a failed comparison is never reported as clean) |
  193. The [technical report, §5](docs/TECHNICAL_REPORT.md#5-tool-reference-aip-lintsh) has the full reference: file
  194. discovery, config format, inline disables, the JSON schema, and ready-made GitHub Actions, GitLab CI and
  195. pre-commit snippets.
  196. ## What it does not do
  197. - It does **not** issue a Google certification. The verdict is a self-assessment.
  198. - It does **not** cover REST or OpenAPI-only APIs. AIPs are written around protobuf.
  199. - It does **not** run your service. Behaviour (validation, authorization order, error payloads) is checked by
  200. reading code. Without that code, those items stay NOT VERIFIED.
  201. - It does **not** follow AIP updates on its own. The checklist reflects google.aip.dev as of 2026-11-22. New
  202. upstream rules reach the linter first.
  203. - How well different models handle the judgement items, such as "is this custom method justified?", has not
  204. been measured.
  205. - The client-library AIPs (4200 series) are out of scope.
  206. ## Documentation
  207. - [`docs/TECHNICAL_REPORT.md`](docs/TECHNICAL_REPORT.md): the approach (why two layers), how the coverage boundary
  208. was drawn, the verdict model, portability, execution protocols, the full `aip-lint.sh` reference with CI
  209. recipes, measured behaviour, threats to validity, and an AIP-by-AIP coverage index.
  210. - [`docs/examples/AIP-AUDIT.fixture.md`](docs/examples/AIP-AUDIT.fixture.md): a complete audit report on the test fixture.
  211. - [`skills/aip-audit/SKILL.md`](skills/aip-audit/SKILL.md), [`skills/aip-design/SKILL.md`](skills/aip-design/SKILL.md): the skills themselves.
  212. - [`CHANGELOG.md`](CHANGELOG.md): release history.
  213. ## Repository layout
  214. ```
  215. .claude-plugin/
  216. plugin.json Claude Code plugin manifest
  217. marketplace.json single-plugin marketplace (enables /plugin marketplace add)
  218. skills/aip-audit/
  219. SKILL.md audit workflow, verdict, report format
  220. references/manual-review.md 38-item checklist + AIP coverage map
  221. scripts/aip-lint.sh api-linter / buf breaking wrapper
  222. skills/aip-design/
  223. SKILL.md design workflow
  224. references/aip-cheatsheet.md
  225. assets/acme/library/v1/library.proto lint-clean template
  226. docs/
  227. TECHNICAL_REPORT.md
  228. examples/AIP-AUDIT.fixture.md
  229. tests/
  230. run.sh template lints clean; fixture trips 5 known rules; --against exit codes
  231. check_docs.py coverage tables and counts in the docs match the checklist and the linter
  232. fixtures/violations/… deliberately non-compliant proto
  233. .github/workflows/test.yml runs tests/run.sh against the latest api-linter
  234. CITATION.cff · CHANGELOG.md · LICENSE
  235. ```
  236. ## Contributing
  237. Run `tests/run.sh` before opening a PR. When you add a checklist item, link its AIP, keep the AIP's own MUST or
  238. SHOULD, and add a row to Appendix A of the technical report.
  239. ## License
  240. MIT for the skills, script and documentation. The AIP texts at google.aip.dev are © Google, licensed CC BY 4.0.
  241. This repository links to and paraphrases them, but does not copy them.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.