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/project-template.ts

View on GitHub
/**
 * Project Creation Template
 *
 * MANDATORY: Every project creation MUST use this template to ensure:
 * 1. Project linked to initiative
 * 2. Description set (short 255 char limit)
 * 3. Content set (full markdown)
 * 4. Labels created/verified
 * 5. Issues created with labels
 * 6. Post-execution verification
 */
import { getLinearClient } from './linear-utils'
import { linkProjectToInitiative, DEFAULT_INITIATIVE_ID } from './initiative'
import { ensureLabelsExist, extractUniqueLabels } from './labels'
import { verifyProjectCreation } from './verify'
import { validateIssueDescription, isStrictMode, formatDescriptionValidationResult } from './issue-description'

export interface IssueConfig {
  title: string
  description: string
  labels: string[]
  priority?: number
  estimate?: number
}

export interface ProjectConfig {
  name: string
  shortDescription: string // 255 char limit
  content: string // Full markdown
  state: 'planned' | 'started' | 'paused' | 'completed' | 'canceled'
  initiative: string // Initiative ID to link to
  issues: IssueConfig[]
}

export interface CreateResult {
  project: {
    id: string
    name: string
    created: boolean
    linkedToInitiative: boolean
    contentSet: boolean
  }
  labels: {
    created: string[]
    existing: string[]
    failed: string[]
  }
  issues: {
    created: Array<{ identifier: string; title: string }>
    failed: Array<{ title: string; error: string }>
  }
  verification: {
    passed: boolean
    issues: string[]
  }
}

/**
 * Create a project with all required components
 *
 * This is the ONLY correct way to create a project. It ensures:
 * 1. Project created with description
 * 2. Project linked to initiative
 * 3. Content set via projectUpdate
 * 4. Labels created/verified
 * 5. Issues created with labels
 * 6. Post-execution verification
 */
export async function createProject(
  teamId: string,
  config: ProjectConfig
): Promise<CreateResult> {
  const result: CreateResult = {
    project: {
      id: '',
      name: config.name,
      created: false,
      linkedToInitiative: false,
      contentSet: false
    },
    labels: {
      created: [],
      existing: [],
      failed: []
    },
    issues: {
      created: [],
      failed: []
    },
    verification: {
      passed: false,
      issues: []
    }
  }

  console.log(`\n=== Creating Project: ${config.name} ===\n`)

  // Step 0: Validate ALL issue descriptions BEFORE any API call. This is a pure
  // check, so we run it before creating the project, linking to initiative, or
  // creating labels — otherwise a validation failure leaves an empty project and
  // orphaned labels behind.
  if (isStrictMode()) {
    console.log('Step 0: Validating issue descriptions...')
    const descErrors: string[] = []
    for (const [idx, issueConfig] of config.issues.entries()) {
      const descResult = validateIssueDescription(issueConfig.description)
      if (!descResult.valid) {
        descErrors.push(
          `  Issue #${idx + 1} "${issueConfig.title}":\n` +
          formatDescriptionValidationResult(descResult)
            .split('\n')
            .map(line => '    ' + line)
            .join('\n')
        )
      }
    }
    if (descErrors.length > 0) {
      console.error(
        `  ✗ ${descErrors.length} of ${config.issues.length} issue(s) failed description validation. ` +
        `Aborting before any resources are created.`
      )
      for (const err of descErrors) console.error(err)
      result.verification.issues.push(
        `${descErrors.length} issue description(s) failed validation — no project, labels, or issues created.`
      )
      return result
    }
    console.log(`  ✓ All ${config.issues.length} descriptions valid`)
  }

  // Step 1: Create or find project
  console.log('Step 1: Creating project...')
  let projectId: string

  const existingProjects = await getLinearClient().projects({
    filter: { name: { eq: config.name } }
  })

  if (existingProjects.nodes.length > 0) {
    projectId = existingProjects.nodes[0].id
    console.log(`  Found existing project: ${projectId}`)
  } else {
    const createResult = await getLinearClient().createProject({
      teamIds: [teamId],
      name: config.name,
      description: config.shortDescription.substring(0, 255)
    })
    const project = await createResult.project
    if (!project) {
      result.verification.issues.push('Failed to create project')
      return result
    }
    projectId = project.id
    console.log(`  Created project: ${projectId}`)
  }

  result.project.id = projectId
  result.project.created = true

  // Step 2: Link to initiative (MANDATORY)
  console.log('Step 2: Linking to initiative...')
  const linkResult = await linkProjectToInitiative(projectId, config.initiative)
  if (linkResult.success) {
    result.project.linkedToInitiative = true
    console.log('  ✓ Linked to initiative')
  } else {
    console.log(`  ⚠ Initiative link failed: ${linkResult.error}`)
    result.verification.issues.push(`Initiative link failed: ${linkResult.error}`)
  }

  // Step 3: Set content via projectUpdate
  console.log('Step 3: Setting project content...')
  try {
    const mutation = `
      mutation UpdateProjectContent($id: String!, $input: ProjectUpdateInput!) {
        projectUpdate(id: $id, input: $input) {
          success
        }
      }
    `

    const response = await fetch('https://api.linear.app/graphql', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': process.env.LINEAR_API_KEY || ''
      },
      body: JSON.stringify({
        query: mutation,
        variables: {
          id: projectId,
          input: {
            content: config.content,
            description: config.shortDescription.substring(0, 255)
          }
        }
      })
    })

    const mutationResult = await response.json()
    if (mutationResult.data?.projectUpdate?.success) {
      result.project.contentSet = true
      console.log('  ✓ Content set')
    } else {
      console.log(`  ⚠ Content setting failed: ${JSON.stringify(mutationResult.errors)}`)
    }
  } catch (error) {
    console.log(`  ⚠ Content setting error: ${error}`)
  }

  // Step 4: Ensure all labels exist
  console.log('Step 4: Creating labels...')
  const allLabels = extractUniqueLabels(
    Object.fromEntries(config.issues.map((i, idx) => [`issue-${idx}`, i.labels]))
  )

  const labelResult = await ensureLabelsExist(teamId, allLabels)
  result.labels = {
    created: labelResult.created,
    existing: labelResult.existing,
    failed: labelResult.failed
  }
  console.log(`  Created: ${labelResult.created.length}, Existing: ${labelResult.existing.length}`)

  // Step 5: Create issues with labels
  console.log('Step 5: Creating issues...')
  const labelMap = labelResult.labelMap

  for (const issueConfig of config.issues) {
    try {
      // Get label IDs
      const labelIds = issueConfig.labels
        .map(name => labelMap.get(name.toLowerCase()))
        .filter((id): id is string => id !== undefined)

      const issueResult = await getLinearClient().createIssue({
        teamId,
        projectId,
        title: issueConfig.title,
        description: issueConfig.description,
        labelIds,
        priority: issueConfig.priority,
        estimate: issueConfig.estimate
      })

      const issue = await issueResult.issue
      if (issue) {
        result.issues.created.push({
          identifier: issue.identifier,
          title: issue.title
        })
        console.log(`  ✓ ${issue.identifier}: ${issue.title.substring(0, 40)}...`)
      } else {
        result.issues.failed.push({
          title: issueConfig.title,
          error: 'Issue creation returned null'
        })
      }
    } catch (error) {
      result.issues.failed.push({
        title: issueConfig.title,
        error: String(error)
      })
      console.log(`  ✗ ${issueConfig.title}: ${error}`)
    }
  }

  // Step 6: Verification
  console.log('\nStep 6: Verifying...')
  const verification = await verifyProjectCreation(
    config.name,
    config.issues.length,
    undefined,
    config.initiative
  )

  result.verification = verification.overall

  if (verification.overall.passed) {
    console.log('  ✅ All checks passed')
  } else {
    console.log('  ❌ Verification failed:')
    verification.overall.issues.forEach(i => console.log(`    - ${i}`))
  }

  return result
}

/**
 * Create a project using the default initiative from environment
 *
 * Requires LINEAR_DEFAULT_INITIATIVE_ID to be set
 */
export async function createProjectWithDefaults(
  config: Omit<ProjectConfig, 'initiative'>
): Promise<CreateResult> {
  if (!DEFAULT_INITIATIVE_ID) {
    throw new Error('LINEAR_DEFAULT_INITIATIVE_ID environment variable is required')
  }

  // Get team
  const teams = await getLinearClient().teams()
  const team = teams.nodes[0]

  return createProject(team.id, {
    ...config,
    initiative: DEFAULT_INITIATIVE_ID
  })
}

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