api-filters

Add, modify, or convert AIP-style query-parameter filters on v3 list endpoints. Use when adding filterable fields to a list API, wiring filter parsing into a handler, converting API filters into pkg/filter predicates, or debugging filter parsing/validation behavior.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

85%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content is highly actionable with executable code and precise file references, and the workflow is clearly sequenced with good test guidance. It is mostly concise and well-structured, though some inlined reference-style material could be split out to improve progressive disclosure.

Suggestions

Move the full operator grammar table and the 'Picking the right filter type' table into a separate reference file under ./references/ and link to it from SKILL.md to reduce the inlined bulk and improve progressive disclosure.

Add an explicit verification checkpoint after `make gen-api` (e.g., confirm the new field appears on the generated params.Filter struct before proceeding to the handler) to strengthen the workflow's feedback loop.

Dedupe the API-layer types table and the predicate/table in 'Common Patterns and Gotchas' to trim repeated content and tighten conciseness.

Dimension	Reasoning	Score
Conciseness	Largely lean and technical, assuming Claude's competence without explaining basics, but a couple of filter-type tables overlap in content and a few explanatory paragraphs could be tightened, keeping it just below the fully-lean anchor.	4 / 5
Actionability	Provides copy-paste-ready Go code for each workflow step with file:line references, exact helper signatures, and concrete test-case lists, fully covering the common cases.	5 / 5
Workflow Clarity	Six clearly sequenced steps with regeneration and test-coverage checkpoints; validation appears through Validate() and 400-case test lists, but there is no explicit 'confirm gen-api succeeded before proceeding' feedback loop, leaving minor gaps.	4 / 5
Progressive Disclosure	Well-sectioned with a one-level-deep Reference Files list and a clearly signaled canonical rule file, but the body is fairly monolithic (~355 lines) with the full operator grammar and two filter-type tables inlined that could live in separate reference files.	4 / 5
	Total	17 / 20 Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is specific, complete, and well-targeted, with concrete actions and an explicit 'Use when' trigger clause covering multiple scenarios. Voice is consistently third person and it is clearly distinguishable from sibling skills.

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions — 'Add, modify, or convert', 'adding filterable fields to a list API', 'wiring filter parsing into a handler', 'converting API filters into pkg/filter predicates', 'debugging filter parsing/validation behavior' — with comprehensive coverage of the skill's surface.	5 / 5
Completeness	Explicitly answers both what ('Add, modify, or convert AIP-style query-parameter filters on v3 list endpoints') and when, via a 'Use when' clause enumerating four concrete trigger scenarios.	5 / 5
Trigger Term Quality	Natural trigger phrases map to real user requests ('adding filterable fields to a list API', 'debugging filter parsing/validation behavior'), with good keyword coverage; a few common synonyms or phrasings users might say are not exhaustively covered, so it sits just below the comprehensive anchor.	4 / 5
Distinctiveness Conflict Risk	Highly specific niche — AIP-style, v3 list endpoints, pkg/filter predicates — with minimal overlap risk, and it even disambiguates against the sibling /api skill.	5 / 5
	Total	19 / 20 Passed

Validation

87%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
relative_links	Relative link issues: 1 suspicious	Warning

	Total	14 / 16 Passed

Repository: openmeterio/openmeter
Path: .agents/skills/api-filters/SKILL.md
Commit: 03a90ec

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.