feat(skills): improve api and api-filters skills

[borosr]

Summary by CodeRabbit

• Documentation
  • Expanded API guidance for list endpoints, including clearer handling of sort fields and error responses.
  • Added v3 filter instructions for status/enum values and supported conversion patterns.
  • Clarified recommended handling for before/after time filters in v1-style requests.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR updates two skill documentation files. It adds guidance for status/enum filter mapping via FromAPIStatusFilter[T], v1 before/after time filter handling via filter.NewFilterTime, and reworks sort field mapping conventions for list endpoints to use converter-layer FromAPI<Resource>SortField functions instead of inline validation.

Changes

API skill documentation updates

Layer / File(s)	Summary
Status filter mapping guidance .agents/skills/api-filters/SKILL.md	Documents filters.FromAPIStatusFilter[T] for mapping API short status values to DB extended sub-statuses, including type constraints, neq rejection, handler wiring, and updated reference/reminder entries clarifying it returns ([]T, error) rather than a *filter.* predicate.
v1 time filter parameter guidance .agents/skills/api-filters/SKILL.md	Adds guidance for v1 before/after time query parameters, recommending filter.NewFilterTime over manually constructed And nodes.
Sort field mapping convention .agents/skills/api-filters/SKILL.md, .agents/skills/api/SKILL.md	Reworks sort field mapping guidance to require FromAPI<Resource>SortField in convert.go returning apierrors.NewUnsupportedSortFieldError, and updates the handler example to call the mapper directly instead of using inline validSortField validation.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• openmeterio/openmeter#4225: Both PRs touch the same .agents/skills/api-filters/SKILL.md guidance around FromAPIFilter*/FromAPIStatusFilter[T] and how it interacts with ApplyToQuery.

Suggested labels

release-note/ignore

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and clearly matches the PR’s main change: improving the api and api-filters skill docs.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/improve-api-n-filter-skills

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR updates the API skills with newer handler guidance.

• Adds short-status enum filter guidance for extended database statuses.
• Documents v1 before/after time conversion with filter.NewFilterTime.
• Moves sort-field mapping guidance toward converter helpers.

Confidence Score: 4/5

The changed skill guidance is mergeable after fixing the malformed Markdown fence.

• The content changes are documentation-only.
• The api-filters example can render incorrectly and lead agents to copy invalid guidance.
• No security-sensitive behavior changes were introduced.

.agents/skills/api-filters/SKILL.md

Important Files Changed

Filename	Overview
.agents/skills/api-filters/SKILL.md	Adds filter guidance, but one new Markdown code fence contains copied UI text.
.agents/skills/api/SKILL.md	Updates the list-handler sort example to call a converter-owned sort mapper.

Comments Outside Diff (1)

1. .agents/skills/api-filters/SKILL.md, line 345 (link)

   Code Fence Includes UI Text

   The closing fence for the short-status example includes copied review UI text, so Markdown renderers can keep the following prose inside the Go block. Agents reading this skill can then copy invalid text or miss the guidance that follows.

   Context Used: AGENTS.md (source)

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
.agents/skills/api-filters/SKILL.md:345
**Code Fence Includes UI Text**

The closing fence for the short-status example includes copied review UI text, so Markdown renderers can keep the following prose inside the Go block. Agents reading this skill can then copy invalid text or miss the guidance that follows.

_{Reviews (1): Last reviewed commit: "feat(skills): improve api and api-filter..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.agents/skills/api-filters/SKILL.md:
- Around line 319-320: The constraint wording for FromAPIStatusFilter[T] is
inaccurate and should be aligned with the actual validator interface. Update the
SKILL.md description near FromAPIStatusFilter[T] to say that T must be ~string
and satisfy expand.Expandable[T] (which provides Values() []T) plus Validate()
error, and remove the mention of comparable so readers don’t infer a constraint
that isn’t required.

🪄 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: 8fb2be53-df07-4e10-abe7-934be9370818

📥 Commits

Reviewing files that changed from the base of the PR and between 34aba20 and 55bb618.

📒 Files selected for processing (2)

• .agents/skills/api-filters/SKILL.md
• .agents/skills/api/SKILL.md