Skip to content

wrsmith108/linear-claude-skill

Managing Linear issues, projects, and teams. Use when working with Linear tasks, creating issues, updating status, querying projects, or managing team workflows.

FileKindSize
SKILL.mdskill md22.7 KB
scripts/__tests__/bulk-create.test.tsscript5.0 KB
scripts/__tests__/issue-description.test.tsscript6.8 KB
scripts/__tests__/lin-cli.test.tsscript3.8 KB
scripts/__tests__/lint-issues.test.tsscript2.3 KB
scripts/__tests__/retry.test.tsscript8.2 KB
scripts/__tests__/smoke.test.tsscript7.0 KB
scripts/__tests__/validate-description.test.tsscript4.3 KB
scripts/build.mjsscript1.4 KB
scripts/bulk-create.tsscript12.5 KB
scripts/create-initiative-update.tsscript5.8 KB
scripts/create-issue-with-project.tsscript8.0 KB
scripts/create-project-update.tsscript5.5 KB
scripts/extract-image.tsscript2.2 KB
scripts/lib/agent-selection.tsscript8.7 KB
scripts/lib/exit-codes.tsscript357 B
scripts/lib/index.tsscript3.1 KB
scripts/lib/initiative.tsscript5.0 KB
scripts/lib/issue-description.tsscript7.1 KB
scripts/lib/labels.tsscript7.6 KB
scripts/lib/lin-cli.tsscript7.3 KB
scripts/lib/linear-utils.tsscript9.3 KB
scripts/lib/project-template.tsscript8.8 KB
scripts/lib/retry.tsscript4.8 KB
scripts/lib/taxonomy-data.tsscript8.1 KB
scripts/lib/taxonomy-validation.tsscript10.0 KB
scripts/lib/taxonomy.tsscript3.6 KB
scripts/lib/verify.tsscript6.6 KB
scripts/linear-api.mjsexecutablescript12.1 KB
scripts/linear-ops.tsscript69.1 KB
scripts/lint-issues.tsscript6.9 KB
scripts/phase-complete.tsscript12.4 KB
scripts/query.shexecutablescript498 B
scripts/query.tsscript3.5 KB
scripts/run.shexecutablescript321 B
scripts/setup.tsscript8.6 KB
scripts/sync-skill-version.mjsscript2.0 KB
scripts/sync.tsscript5.7 KB
scripts/upload-image.tsscript4.4 KB

scripts/lib/linear-utils.ts

View on GitHub
/**
 * Shared Linear API utilities
 *
 * Common patterns extracted from Linear scripts for consistent
 * API key validation, entity lookups, and type definitions.
 */

import { LinearClient } from '@linear/sdk';
import { withRetry } from './retry';

// ============================================================================
// Types
// ============================================================================

/**
 * Health status for project and initiative updates
 */
export type HealthStatus = 'onTrack' | 'atRisk' | 'offTrack';

/**
 * Valid health status values
 */
export const VALID_HEALTH_VALUES: readonly HealthStatus[] = ['onTrack', 'atRisk', 'offTrack'] as const;

/**
 * Project information returned by findProjectByName
 */
export interface ProjectInfo {
  id: string;
  name: string;
  slugId: string;
}

/**
 * Initiative information returned by findInitiativeByName
 */
export interface InitiativeInfo {
  id: string;
  name: string;
  description?: string;
}

/**
 * Team information returned by findTeamByKey
 */
export interface TeamInfo {
  id: string;
  key: string;
  name: string;
}

/**
 * Label lookup result with case-insensitive missing-label reporting
 */
export interface LabelLookupResult {
  ids: string[];
  found: Array<{ id: string; name: string }>;
  missing: string[];
}

// ============================================================================
// Type Guards
// ============================================================================

/**
 * Type guard to check if a string is a valid health status
 */
export function isValidHealth(value: string): value is HealthStatus {
  return VALID_HEALTH_VALUES.includes(value as HealthStatus);
}

// ============================================================================
// Client Initialization
// ============================================================================

/**
 * Create a LinearClient instance with the provided API key
 *
 * @param apiKey Linear API key
 * @returns LinearClient instance
 */
export function createLinearClient(apiKey: string): LinearClient {
  return new LinearClient({ apiKey });
}

let _cachedClient: LinearClient | null = null;

/**
 * Get a LinearClient instance with API key validation
 *
 * Reads the API key from LINEAR_API_KEY environment variable.
 * Returns a cached instance on subsequent calls.
 *
 * @throws Error if LINEAR_API_KEY environment variable is not set
 * @returns LinearClient instance
 */
export function getLinearClient(): LinearClient {
  if (_cachedClient) return _cachedClient;

  const apiKey = process.env.LINEAR_API_KEY;

  if (!apiKey) {
    throw new Error('LINEAR_API_KEY environment variable is required');
  }

  _cachedClient = createLinearClient(apiKey);
  return _cachedClient;
}

// ============================================================================
// Entity Lookups
// ============================================================================

/**
 * Find a project by name with exact-match preference
 *
 * Searches for projects with case-insensitive partial matching.
 * If multiple matches are found, prefers exact match (case-insensitive).
 *
 * @param client LinearClient instance
 * @param name Project name to search for
 * @returns ProjectInfo or null if not found
 */
export async function findProjectByName(
  client: LinearClient,
  name: string
): Promise<ProjectInfo | null> {
  const projects = await client.projects({
    filter: {
      name: { containsIgnoreCase: name }
    },
    first: 10
  });

  if (projects.nodes.length === 0) {
    return null;
  }

  // Prefer exact match (case-insensitive)
  const exactMatch = projects.nodes.find(
    p => p.name.toLowerCase() === name.toLowerCase()
  );

  const project = exactMatch || projects.nodes[0];
  return {
    id: project.id,
    name: project.name,
    slugId: project.slugId
  };
}

/**
 * Find an initiative by name with exact-match preference
 *
 * Searches for initiatives with case-insensitive partial matching.
 * If multiple matches are found, prefers exact match (case-insensitive).
 *
 * @param client LinearClient instance
 * @param name Initiative name to search for
 * @returns InitiativeInfo or null if not found
 */
export async function findInitiativeByName(
  client: LinearClient,
  name: string
): Promise<InitiativeInfo | null> {
  const query = `
    query FindInitiative($filter: InitiativeFilter!) {
      initiatives(filter: $filter, first: 10) {
        nodes {
          id
          name
          description
        }
      }
    }
  `;

  const result = await client.client.rawRequest(query, {
    filter: {
      name: { containsIgnoreCase: name }
    }
  });

  const data = result.data as { initiatives: { nodes: InitiativeInfo[] } };
  const initiatives = data.initiatives.nodes;

  if (initiatives.length === 0) {
    return null;
  }

  // Prefer exact match (case-insensitive)
  const exactMatch = initiatives.find(
    i => i.name.toLowerCase() === name.toLowerCase()
  );

  return exactMatch || initiatives[0];
}

/**
 * Find a team by its key (e.g., "ENG", "PRODUCT")
 *
 * @param client LinearClient instance
 * @param key Team key to search for (case-insensitive)
 * @returns TeamInfo or null if not found
 */
export async function findTeamByKey(
  client: LinearClient,
  key: string
): Promise<TeamInfo | null> {
  const query = `
    query TeamByKey($filter: TeamFilter!) {
      teams(filter: $filter, first: 1) {
        nodes {
          id
          key
          name
        }
      }
    }
  `;

  const result = await client.client.rawRequest(query, {
    filter: {
      key: { eq: key.toUpperCase() }
    }
  });

  const data = result.data as {
    teams: {
      nodes: TeamInfo[];
    };
  };

  return data.teams.nodes[0] || null;
}

/**
 * Find a team by name with case-insensitive matching
 *
 * Searches for teams with case-insensitive partial matching.
 * If multiple matches are found, prefers exact match (case-insensitive).
 *
 * @param client LinearClient instance
 * @param name Team name to search for
 * @returns TeamInfo or null if not found
 */
export async function findTeamByName(
  client: LinearClient,
  name: string
): Promise<TeamInfo | null> {
  const query = `
    query TeamByName($filter: TeamFilter!) {
      teams(filter: $filter, first: 10) {
        nodes {
          id
          key
          name
        }
      }
    }
  `;

  const result = await client.client.rawRequest(query, {
    filter: {
      name: { containsIgnoreCase: name }
    }
  });

  const data = result.data as {
    teams: {
      nodes: TeamInfo[];
    };
  };

  const teams = data.teams.nodes;

  if (teams.length === 0) {
    return null;
  }

  // Prefer exact match (case-insensitive)
  const exactMatch = teams.find(
    t => t.name.toLowerCase() === name.toLowerCase()
  );

  return exactMatch || teams[0];
}

/**
 * Find a workflow state ID by exact name within a team.
 *
 * @param client LinearClient instance
 * @param teamId Linear team UUID
 * @param stateName Workflow state name to resolve
 * @returns Workflow state ID or null if not found
 */
export async function findWorkflowStateIdByName(
  client: LinearClient,
  teamId: string,
  stateName: string
): Promise<string | null> {
  const query = `
    query WorkflowStates($filter: WorkflowStateFilter!) {
      workflowStates(filter: $filter, first: 1) {
        nodes {
          id
          name
        }
      }
    }
  `;

  const result = await withRetry(
    () => client.client.rawRequest(query, {
      filter: {
        team: { id: { eq: teamId } },
        name: { eq: stateName },
      },
    }),
    { label: 'linear-utils:workflow-state' }
  );

  const data = result.data as {
    workflowStates: {
      nodes: Array<{ id: string; name: string }>;
    };
  };

  return data.workflowStates.nodes[0]?.id || null;
}

/**
 * Resolve label names to IDs within a team, matching names case-insensitively.
 *
 * @param client LinearClient instance
 * @param teamId Linear team UUID
 * @param labelNames Label names requested by the caller
 * @returns Found label IDs plus missing label names
 */
export async function findLabelIdsByName(
  client: LinearClient,
  teamId: string,
  labelNames: string[]
): Promise<LabelLookupResult> {
  if (labelNames.length === 0) {
    return { ids: [], found: [], missing: [] };
  }

  const requested = labelNames
    .map(name => name.trim())
    .filter(name => name.length > 0);

  if (requested.length === 0) {
    return { ids: [], found: [], missing: [] };
  }

  const query = `
    query Labels($filter: IssueLabelFilter!) {
      issueLabels(filter: $filter, first: 250) {
        nodes {
          id
          name
        }
      }
    }
  `;

  const result = await withRetry(
    () => client.client.rawRequest(query, {
      filter: {
        team: { id: { eq: teamId } },
      },
    }),
    { label: 'linear-utils:labels' }
  );

  const data = result.data as {
    issueLabels: {
      nodes: Array<{ id: string; name: string }>;
    };
  };

  const teamLabels = data.issueLabels.nodes;
  const found: Array<{ id: string; name: string }> = [];
  const missing: string[] = [];

  for (const requestedName of requested) {
    const label = teamLabels.find(
      candidate => candidate.name.toLowerCase() === requestedName.toLowerCase()
    );
    if (label) {
      found.push(label);
    } else {
      missing.push(requestedName);
    }
  }

  return {
    ids: found.map(label => label.id),
    found,
    missing,
  };
}
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall