> **api-review** — skill 26 of 31 in [flutter/agent-plugins](https://skillsdocs.com/flutter/agent-plugins).
>
> Book (all skills, one file): https://skillsdocs.com/flutter/agent-plugins.md
> Machine manifest: https://skillsdocs.com/flutter/agent-plugins/.well-known/agent-skills/index.json
> Origin: credited — this skill is installed into this repository and in use here, not published from it, so there is no install command.
> Upstream: https://github.com/flutter/agent-plugins/blob/main/.agents/agents/reidbaker-agent/skills/api-review/SKILL.md @ `main`
> Raw bytes, no header: https://raw.githubusercontent.com/flutter/agent-plugins/main/.agents/agents/reidbaker-agent/skills/api-review/SKILL.md
> Base for relative paths: https://raw.githubusercontent.com/flutter/agent-plugins/main/.agents/agents/reidbaker-agent/skills/api-review/
> Licence: BSD-3-Clause — https://spdx.org/licenses/BSD-3-Clause.html
>
> Bundled files (1), referenced from this skill's directory:
>   - `references/canonical_api_design.md` — https://raw.githubusercontent.com/flutter/agent-plugins/main/.agents/agents/reidbaker-agent/skills/api-review/references/canonical_api_design.md
>
> Content © its authors, served unmodified. Takedown: https://github.com/DreambaseAI/skillsdocs/issues/new?labels=takedown&title=Takedown+request

<!-- Verbatim upstream SKILL.md follows, YAML frontmatter included. -->

---
name: api-review
description: Reviews the specified code against the canonical API Design guidelines. Use this skill when the user asks for an API review or to check code against API design principles.
---

# API review skill

This skill reviews code against the canonical API Design guidelines.

## Instructions

1. **Load Guidelines**: Read the API design guidelines from [references/canonical_api_design.md](references/canonical_api_design.md) to ensure they are fully available in the context.
2. **Identify Target**: Identify the code to review.
   - If the user specified files (e.g., "review main.dart"), use those.
   - If the user has an open file in their context, assume that is the target.
   - If neither, ask the user to specify the target files.
3. **Analyze**: For each target file, perform a deep analysis against the "Foundations of Canonical API Design Principles" (loaded in step 1), specifically looking for:
   - **Contract-First**: Is the interface clear and decoupled from implementation?
   - **KISS/YAGNI**: Are there unnecessary parameters or over-generalized features?
   - **Ergonomics**: Are names intent-revealing? Do they follow the Principle of Least Astonishment?
   - **CQS**: Are commands and queries separated?
   - **Safety**: Are types used strictly (Enums vs Strings)? Is validation visible?
   - **Explicit Configuration**: Are dependencies explicitly injected rather than implicitly resolved via global state, registries, or environment variables?
4. **Report**: Generate a structured report:
   - **Score**: Give a letter grade (A-F) based on alignment.
   - **Critical Issues**: Violations that _must_ be fixed (e.g., severe strictness or safety issues).
   - **Suggestions**: Ergonomic improvements (renaming, rearranging).
   - **Code Examples**: Provide `before` vs `after` code blocks for the suggested improvements.
   - Save the report as a markdown artifact in the conversation artifacts directory (e.g., `<appDataDir>/brain/<conversation-id>/api_review_results.md`).