intervals-icu-mcp: Skill for Claude Code

What you're producing

An MCP tool is an LLM-consumed artifact. The tool's name and description are read by every Claude/GPT/etc. model that connects to this server, on every session, before the user has typed anything. Be ruthless about clarity and length. Write for the model, not for human readers (humans read docs/tools.md and the README).

Prerequisites

Before starting:

• Verify the Intervals.icu API endpoint exists in openapi-spec.json — check the request/response schema, enum values, and required fields.
• Decide the tier the tool belongs to: core (daily-use, exposed by default) or full (specialty/coach, opt-in via INTERVALS_ICU_TOOLSET=full). When tier work lands per issue #27, tag accordingly.
• Check for confusable names in the existing tool surface. If your tool name shares a prefix or noun with another tool (e.g. get_activity_*, *_event, create_*), the opening sentence of the description MUST lead with the distinguishing access pattern, not the shared concept.
• Decide whether a new API client method is needed in client.py.

Steps

1. Add the API client method (if needed)

File: src/intervals_icu_mcp/client.py

Add an async method to ICUClient following the existing pattern. Type the local variable so pyright doesn't widen Any:

async def get_something(self, athlete_id: str | None = None) -> list[dict[str, Any]]:
    """Fetch something from the API."""
    athlete_id = athlete_id or self.config.intervals_icu_athlete_id
    response = await self._request("GET", f"/athlete/{athlete_id}/something")
    result: list[dict[str, Any]] = response.json()
    return result

Trust the API contract — don't add if isinstance(data, list) else [] defensive ternaries unless there's a real reason. Pydantic models are preferred when the response shape is stable; raw dicts are fine for variable-shape endpoints (e.g. custom_items.content).