helix.mcp: Skill for Claude Code

Context

Use this when adding parameters to one MCP tool in a family where sibling tools already share a parameter pattern. Inconsistency causes hard schema-rejection errors for calling models that learn the pattern from one sibling and apply it to others.

Pattern

Identify the canonical parameter set for each resource type

For Helix tools, the canonical per-work-item parameter set is:

(string jobId, string? workItem = null, ...)

Where jobId accepts a GUID, a job URL, or a full work-item URL (with workItem auto-extracted via HelixIdResolver.TryResolveJobAndWorkItem).

Every tool that can be scoped to a single work item MUST accept workItem.

The URL extraction pattern (replicated in each MCP tool method)

// If workItem not provided, try to extract from jobId URL
if (string.IsNullOrEmpty(workItem) && HelixIdResolver.TryResolveJobAndWorkItem(jobId, out var resolvedJobId, out var resolvedWorkItem))
{
    if (!string.IsNullOrEmpty(resolvedWorkItem))
    {
        jobId = resolvedJobId;
        workItem = resolvedWorkItem;
    }
}

This is intentionally repeated per tool (not centralized) so each tool's parameter flow is self-contained.

Single-item fast path in the service

When workItem is added to a multi-item scan method (e.g., FindFilesAsync), add a fast path:

if (!string.IsNullOrWhiteSpace(workItem))
{
    // Skip ListWorkItemsAsync; query single item directly
    var files = await _api.ListWorkItemFilesAsync(workItem, id, cancellationToken);
    // ... apply filter, build result
    return new FindFilesResults(..., Truncated: false, TotalWorkItems: 1);
}
// ... original multi-item scan path

Watch for parameter ordering in modified signatures

When inserting a new optional parameter into an existing method, any callers that pass subsequent optional params POSITIONALLY will silently bind to the wrong slot (type-compatible) or fail to compile (type-incompatible). Prefer named arguments for optional params after the first.