helix.mcp: Skill for Claude Code

Context

Use this when adding or redesigning filter parameters on MCP tools — especially when the underlying data model has multiple orthogonal filtering dimensions (e.g., state vs result vs issues). The goal is a filter API that LLMs can use correctly without domain expertise.

Patterns

Prefer named presets over orthogonal parameters

When the underlying data has N independent axes, do NOT expose N separate parameters if:

• Some axis combinations are invalid (e.g., state=pending + result=failed is contradictory)
• The valid combinations map to a small set of common queries
• The consumer is an LLM that picks from AllowedValues, not a human reading docs

Instead, use a single enum parameter whose values are named presets, each mapping to a documented (axis₁, axis₂, …) predicate.

Make preset names self-describing

Preset names ARE the documentation for LLM consumers. 'running' beats 'in-progress'; 'failed' beats 'non-succeeded'. Match the mental model of the caller, not the API's enum names.

Additive expansion is free; breaking changes are expensive

Adding new enum values to AllowedValues is backward-compatible. Renaming parameters, changing defaults, or splitting one parameter into two is a schema break that forces all callers to update.

Keep defaults stable

If 'failed' is the default and existing callers rely on it, don't change the default even if a new preset would be "better." Add the new preset and let callers opt in.

Extract shared predicate logic

When multiple tools use the same filter axis, extract the predicate into a shared helper (e.g., MatchesFilter(record, filterValue)) rather than duplicating switch logic. The helper becomes the single source of truth for what each preset means.

Parent/context walking follows filtering

If a filter narrows records to a subset, the parent-walk logic (including ancestor records for context) should apply uniformly to all non-'all' presets. Don't make parent walking preset-specific unless there's a strong reason.