Index of every page on this site: llms.txt
All skills
nielsmadan avatar

/review-interfaces

@9fbe49f
Run it yourself

Review interface design for functions, classes, modules, components — naming, params, encapsulation, YAGNI, usability. Triggers "review interfaces".

Use this Skill: https://skilld.dev/gh/nielsmadan/agentic-coding/review-interfaces

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈42 tokens for metadata: the name and description. ≈2.3k when used: this file. ≈1.8k more on demand in 1 file.

Description uses 2.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈168 characters, or 2.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Review Interfaces

Interface design review for functions, classes, modules, and components.

Review grading

Use only these finding priorities, in descending order:

  • Critical Issues (Must Fix): a verified path causes data loss, a security failure, a materially wrong operation, or makes a core workflow unusable without reasonable recovery.
  • Improvements (Should Fix): an ordinary supported workflow demonstrably fails or repeatedly imposes substantial friction, or a concrete design defect creates meaningful maintenance cost.
  • Suggestions (Nice to Have): a worthwhile improvement with small practical impact, including optional polish, local simplification, and rare recoverable edge cases.

Grade the demonstrated consequence, realistic reachability, and available recovery against project priorities. A category, missing convention, hypothetical future problem, or confidence that a claim is true does not set its priority. Do not assign automatic severity floors or ceilings. Keep unverified claims in validation gaps, outside the graded finding count; distinguish suggestions from defects. For plans, trace the consequence if implemented and state the assumptions.

Use the short labels Must Fix, Should Fix, and Nice to Have in summaries and ledgers. Keep effort, verification status, user-facing change size, and tool/vendor diagnostic ratings separate. When called by code-review, return its requested evidence and impact fields; the parent owns scoring and final triage. Otherwise apply this rubric directly. Omit empty priority sections.

Usage

/review-interfaces                  # Review context-related code
/review-interfaces --staged         # Review staged changes
/review-interfaces --unpushed       # Review files changed across all unpushed commits
/review-interfaces --changed        # Review unstaged changes
/review-interfaces --all            # Full codebase audit (parallel agents)

Scope

Flag Scope Method
(none) Context-related code Files from the current conversation context: any files the user has discussed, opened, or that you have read/edited in this session. If no conversation context exists, ask the user to specify files or use --staged/--changed/--all.
--staged Staged changes git diff --cached --name-only
--unpushed Files changed across unpushed commits git diff --name-only $(git rev-list HEAD --not --remotes | tail -1)^..HEAD
--changed Unstaged changes git diff --name-only
--all Full codebase Glob source files, parallel agents

--unpushed derives its range from git rev-list HEAD --not --remotes (oldest unpushed commit's parent → HEAD). If nothing is unpushed, or there is no remote/upstream (or the range walks back to the root commit) so it can't be determined reliably, stop and ask the user to pick another scope.

Gotchas

  • Default scope (no flag) uses conversation context, which may be stale from an earlier part of the session. The review silently targets the wrong files if context has shifted.
  • Internal/private interfaces have different standards than public/exported ones. A helper function used in one file does not need the same rigor as an exported component consumed by many callers. Always check whether an interface is public before flagging encapsulation issues.

Workflow

  1. Determine scope based on flags (see Scope table above)

  2. Review each file against all 6 categories in the Interface Checklist below

  3. Parallelize if scope has >5 files: spawn one sub-agent per category, each scanning all files for that category. Merge results and deduplicate.

    Dispatch workers that return findings without editing files. Disable delegation tools where supported; read-only access alone does not prevent delegation. Any coordinating role needs explicit subtasks, a descendant limit, and a stopping condition in its brief.

  4. Classify severity using Review grading; justify the impact with evidence.

  5. Report findings grouped by severity using the Output Format below

Interface Checklist

Pit of Success

Does the interface guide callers toward correct usage?

  • Multiple ways to achieve the same result (e.g., label prop AND children both accepting text content) — pick one
  • Consecutive parameters of the same type that invite transposition (e.g., copy(string, string)) — use named params or wrapper types
  • Ambiguous defaults that lead to silent wrong behavior
  • Easy to call incorrectly without a type or runtime error

Naming & Readability

  • Names that do not describe what the function/class/component does
  • Inconsistent vocabulary across related interfaces (remove vs delete vs destroy)
  • Asymmetric pairs (open/close, start/end, add/remove) — both should exist if either does
  • Name does not match actual behavior (principle of least astonishment)
  • Generic names (data, info, handle, process, manager) that obscure purpose

Signature Design

  • More than 3-4 parameters — use an options/config object
  • Boolean flag parameters (opaque at call site: render(true)) — use named options or separate functions
  • Weak types where stronger types exist (string for a known set of values → use enum/union)
  • Inconsistent parameter ordering across related functions
  • Missing return type annotations on public functions
  • Returning null where an empty collection would eliminate null checks for callers

Surface Area & Encapsulation

  • Public members that should be private/internal
  • Internal types or implementation details exposed in the public interface
  • Missing explicit exports (everything public by default)
  • Transitive dependency types leaked through the public interface
  • Mutable internal state exposed directly instead of via copies or accessors

Flexibility & YAGNI

  • Parameters, props, or configuration that no current caller uses
  • Over-abstracted interfaces solving hypothetical future requirements
  • Under-constrained public contracts that allow invalid states (e.g., status: string instead of status: 'active' | 'inactive'). Review caller usability here; language reviewers own representation details. A demonstrated bad transition or result belongs to review-correctness, even when a type change is the repair.
  • Premature abstraction — generic framework for a single use case
  • Configuration surface area that exceeds what callers actually vary

Composition & Extensibility

  • Deep inheritance hierarchies where composition would be simpler
  • God objects/components with too many responsibilities
  • Violation of single responsibility — function/class needs "and" in its description
  • Tight coupling — reaching through object chains (a.getB().getC().doThing())
  • Missing separation of logic and presentation (for UI components)

For annotated BAD/GOOD code examples for each category, see references/interface-checklist.md.

Output Format

## Interface Review: {scope}

### Critical Issues (Must Fix)
- {file}:{line} - {issue type}: {description}
  **Impact:** {why it matters}
  **Fix:** {solution with code example}

### Improvements (Should Fix)
- {file}:{line} - {issue}
  **Fix:** {solution}

### Suggestions (Nice to Have)
- {file} - {issue}

Examples

Staged changes introduce a component with overlapping props:

/review-interfaces --staged

Reviews staged files and catches a <Button> component that accepts both label (string) and children for button text. Checks the precedence contract and real callers. An undocumented redundant choice is Nice to Have; inconsistent output on an ordinary caller path can be Should Fix. Suggests one clear label contract without assuming that the two props alone prove a serious defect.

Full audit finds god class with 15 public methods:

/review-interfaces --all

Parallel agents scan the full codebase by category. Finds a UserService class that handles authentication, profile updates, notification preferences, and billing — four distinct responsibilities. Suggests splitting into focused services.

Troubleshooting

False positive on an intentionally flexible interface

Solution: If the interface is intentionally generic (e.g., a utility library), note the design decision in a code comment (e.g., // Intentionally flexible: used by 5+ consumers with different needs). Re-run the review and the context will help distinguish intentional flexibility from accidental over-engineering.

Disagreement on parameter count threshold

Solution: The 3-4 parameter guideline is a heuristic. Functions with 5 well-named, distinct-typed parameters may be fine. The real signal is: can a caller guess the correct argument order without checking the signature? If yes, the count is acceptable.

Notes

  • Focus on public/exported interfaces — internal helpers have lower standards
  • Consider the number of callers: a function used once has different design pressure than one used everywhere
  • Language idioms matter: what's good in Python may not apply in TypeScript
  • For --all, use parallel agents per category
  • Interface issues compound: a poorly named function with too many params and weak types is worse than the sum of its parts

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts7mo3 checks · Risk SAFE
  • Gen Agent Trust Hub7mo

    This skill acts as a code reviewer for software interfaces. It analyzes local source files, staged git changes, or the entire codebase. While the functionality is standard for developer tools, it possesses a surface for indirect prompt injection because it processes untrusted code files without explicit boundary markers or sanitization, potentially influencing the behavior of parallel sub-agents mentioned in the workflow.

  • Socket7mo

    No alerts

  • Snyk7mo

    Risk: LOW · No issues

Signed by skilld at 9fbe49f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 days ago.

Activeupdated 2 weeks ago
argument-hint
[--staged | --unpushed | --changed | --all]
effort
high

README badge

README badge for nielsmadan/agentic-coding/review-interfaces