[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6FJTP2ARVA39ESPTBN149ZF":3,"skill-same:01M6FJTP2ARVA39ESPTBN149ZF":197},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":15,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":40,"linkOnly":41,"markdownContent":42,"markdownBody":43,"frontMatter":44,"refName":48,"commitSha":49,"skillDirectory":50,"forksCount":51,"repositoryHtmlUrl":52,"repositoryHomepageUrl":6,"ownerHtmlUrl":53,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":54,"install":55,"resources":68},"01M6FJTP2ARVA39ESPTBN149ZF","Linear",null,"Managing Linear issues, projects, and teams. Use when working with Linear tasks, creating issues, updating status, querying projects, or managing team workflows.","boisenoise\u002Fskills-collections","boisenoise","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F193180?v=4","01M6CDBDQK6BDN55ZMA6B6PKBM","01M6CDBDVSJ3JPTBYN26FZ7TZK",13,"MIT","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39],"linear","MCP","workflows","status","tasks","teams","issues","team","Bash","projects","creating issues","webfetch","use","domain","app","with","2026-11-11 15:11:14",false,"---\nname: Linear\ndescription: Managing Linear issues, projects, and teams. Use when working with Linear tasks, creating issues, updating status, querying projects, or managing team workflows.\nallowed-tools:\n  - mcp__linear\n  - WebFetch(domain:linear.app)\n  - Bash\n---\n\n# Linear\n\nTools and workflows for managing issues, projects, and teams in Linear.\n\n---\n\n## ⚠️ Tool Availability (READ FIRST)\n\n**This skill supports multiple tool backends. Use whichever is available:**\n\n1. **MCP Tools (mcp__linear)** - Use if available in your tool set\n2. **Linear CLI (`linear` command)** - Always available via Bash\n3. **Helper Scripts** - For complex operations\n\n**If MCP tools are NOT available**, use the Linear CLI via Bash:\n\n```bash\n# View an issue\nlinear issues view SMI-123\n\n# Create an issue\nlinear issues create --title \"Issue title\" --description \"Description\"\n\n# Update issue status (get state IDs first)\nlinear issues update SMI-123 -s \"STATE_ID\"\n\n# Add a comment\nlinear issues comment add SMI-123 -m \"Comment text\"\n\n# List issues\nlinear issues list\n```\n\n**Do NOT report \"MCP tools not available\" as a blocker** - use CLI instead.\n\n---\n\n## ? Security: Varlock Integration\n\n**CRITICAL**: Never expose API keys in terminal output or Claude's context.\n\n### Safe Commands (Always Use)\n\n```bash\n# Validate LINEAR_API_KEY is set (masked output)\nvarlock load 2>&1 | grep LINEAR\n\n# Run commands with secrets injected\nvarlock run -- npx tsx scripts\u002Fquery.ts \"query { viewer { name } }\"\n\n# Check schema (safe - no values)\ncat .env.schema | grep LINEAR\n```\n\n### Unsafe Commands (NEVER Use)\n\n```bash\n# ❌ NEVER - exposes key to Claude's context\nlinear config show\necho $LINEAR_API_KEY\nprintenv | grep LINEAR\ncat .env\n```\n\n### Setup for New Projects\n\n1. Create `.env.schema` with `@sensitive` annotation:\n   ```bash\n   # @type=string(startsWith=lin_api_) @required @sensitive\n   LINEAR_API_KEY=\n   ```\n\n2. Add `LINEAR_API_KEY` to `.env` (never commit this file)\n\n3. Configure MCP to use environment variable:\n   ```json\n   {\n     \"mcpServers\": {\n       \"linear\": {\n         \"env\": { \"LINEAR_API_KEY\": \"${LINEAR_API_KEY}\" }\n       }\n     }\n   }\n   ```\n\n4. Use `varlock load` to validate before operations\n\n---\n\n## Quick Start (First-Time Users)\n\n### 1. Check Your Setup\n\nRun the setup check to verify your configuration:\n\n```bash\nnpx tsx ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Fsetup.ts\n```\n\nThis will check:\n- LINEAR_API_KEY is set and valid\n- @linear\u002Fsdk is installed\n- Linear CLI availability (optional)\n- MCP configuration (optional)\n\n### 2. Get API Key (If Needed)\n\nIf setup reports a missing API key:\n\n1. Open [Linear](https:\u002F\u002Flinear.app) in your browser\n2. Go to **Settings** (gear icon) -> **Security & access** -> **Personal API keys**\n3. Click **Create key** and copy the key (starts with `lin_api_`)\n4. Add to your environment:\n\n```bash\n# Option A: Add to shell profile (~\u002F.zshrc or ~\u002F.bashrc)\nexport LINEAR_API_KEY=\"lin_api_your_key_here\"\n\n# Option B: Add to Claude Code environment\necho 'LINEAR_API_KEY=lin_api_your_key_here' >> ~\u002F.claude\u002F.env\n\n# Then reload your shell or restart Claude Code\n```\n\n### 3. Test Connection\n\nVerify everything works:\n\n```bash\nnpx tsx ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Fquery.ts \"query { viewer { name } }\"\n```\n\nYou should see your name from Linear.\n\n### 4. Common Operations\n\nUse the high-level operations script for simple commands:\n\n```bash\n# Create an issue in a project\nnpx tsx scripts\u002Flinear-ops.ts create-issue \"My Project\" \"Fix login bug\" \"Users cannot log in\" --priority 2\n\n# Create a sub-issue under an existing issue\nnpx tsx scripts\u002Flinear-ops.ts create-sub-issue ENG-100 \"Add unit tests\" \"Unit tests for this feature\" --priority 2\n\n# Set parent-child relationships for existing issues\nnpx tsx scripts\u002Flinear-ops.ts set-parent ENG-100 ENG-101 ENG-102\n\n# List sub-issues of a parent\nnpx tsx scripts\u002Flinear-ops.ts list-sub-issues ENG-100\n\n# Create an initiative\nnpx tsx scripts\u002Flinear-ops.ts create-initiative \"Q1 Goals\" \"Key initiatives for Q1\"\n\n# Create a project linked to an initiative\nnpx tsx scripts\u002Flinear-ops.ts create-project \"Phase 1\" \"Q1 Goals\"\n\n# Update project state (backlog, planned, in-progress, paused, completed, canceled)\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase 1\" in-progress\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase 1\" completed\n\n# Link\u002Funlink projects to initiatives\nnpx tsx scripts\u002Flinear-ops.ts link-initiative \"Phase 1\" \"Q1 Goals\"\nnpx tsx scripts\u002Flinear-ops.ts unlink-initiative \"Phase 1\" \"Q1 Goals\"\n\n# Update issue status (PREFERRED over MCP)\nnode scripts\u002Flinear-helpers.mjs update-status Done 123 124 125\n\n# List initiatives\nnpx tsx scripts\u002Flinear-ops.ts list-initiatives\n\n# Show current user\nnpx tsx scripts\u002Flinear-ops.ts whoami\n```\n\n### 5. Getting Help\n\n```bash\n# Show all available commands\nnpx tsx scripts\u002Flinear-ops.ts help\n\n# Re-run setup check anytime\nnpx tsx scripts\u002Fsetup.ts\n```\n\n---\n\n## Project Planning Workflow\n\n### Create Issues in the Correct Project from the Start\n\n**Best Practice**: When planning a new phase or initiative, create the project and its issues together in a single planning session. Avoid creating issues in a catch-all project and moving them later.\n\n#### Recommended Workflow\n\n1. **Create the project first**:\n   ```bash\n   npx tsx scripts\u002Flinear-ops.ts create-project \"Phase X: Feature Name\" \"Skillsmith\"\n   ```\n\n2. **Set project state to Planned**:\n   ```bash\n   npx tsx scripts\u002Flinear-ops.ts project-status \"Phase X: Feature Name\" planned\n   ```\n\n3. **Create issues directly in the project**:\n   ```bash\n   npx tsx scripts\u002Flinear-ops.ts create-issue \"Phase X: Feature Name\" \"Parent task\" \"Description\"\n   npx tsx scripts\u002Flinear-ops.ts create-sub-issue SMI-XXX \"Sub-task 1\" \"Description\"\n   npx tsx scripts\u002Flinear-ops.ts create-sub-issue SMI-XXX \"Sub-task 2\" \"Description\"\n   ```\n\n4. **Update project state when work begins**:\n   ```bash\n   npx tsx scripts\u002Flinear-ops.ts project-status \"Phase X: Feature Name\" in-progress\n   ```\n\n#### Why This Matters\n\n- **Traceability**: Issues are linked to their project from creation\n- **Metrics**: Project progress tracking is accurate from day one\n- **Workflow**: No time wasted moving issues between projects\n- **Organization**: Linear views and filters work correctly\n\n#### Anti-Pattern to Avoid\n\n❌ Creating issues in a \"holding\" project and moving them later:\n```bash\n# Don't do this\ncreate-issue \"Phase 6A\" \"New feature\"  # Wrong project\n# Later: manually move to Phase X      # Extra work\n```\n\n---\n\n## Project Management Commands\n\n### project-status\n\nUpdate a project's state in Linear. Accepts user-friendly terminology that maps to Linear's API.\n\n```bash\nnpx tsx scripts\u002Flinear-ops.ts project-status \u003Cproject-name> \u003Cstate>\n```\n\n**Valid States:**\n| Input | Description | API Value |\n|-------|-------------|-----------|\n| `backlog` | Not yet started | backlog |\n| `planned` | Scheduled for future | planned |\n| `in-progress` | Currently active | started |\n| `paused` | Temporarily on hold | paused |\n| `completed` | Successfully finished | completed |\n| `canceled` | Will not be done | canceled |\n\n**Examples:**\n```bash\n# Start working on a project\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase 8: MCP Decision Engine\" in-progress\n\n# Mark project complete\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase 8\" completed\n\n# Partial name matching works\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase 8\" paused\n```\n\n### link-initiative\n\nLink an existing project to an initiative.\n\n```bash\nnpx tsx scripts\u002Flinear-ops.ts link-initiative \u003Cproject-name> \u003Cinitiative-name>\n```\n\n**Examples:**\n```bash\n# Link Phase 8 to Skillsmith initiative\nnpx tsx scripts\u002Flinear-ops.ts link-initiative \"Phase 8: MCP Decision Engine\" \"Skillsmith\"\n\n# Partial matching works\nnpx tsx scripts\u002Flinear-ops.ts link-initiative \"Phase 8\" \"Skillsmith\"\n```\n\n### unlink-initiative\n\nRemove a project from an initiative.\n\n```bash\nnpx tsx scripts\u002Flinear-ops.ts unlink-initiative \u003Cproject-name> \u003Cinitiative-name>\n```\n\n**Examples:**\n```bash\n# Remove incorrect link\nnpx tsx scripts\u002Flinear-ops.ts unlink-initiative \"Phase 8\" \"Linear Skill\"\n\n# Clean up test links\nnpx tsx scripts\u002Flinear-ops.ts unlink-initiative \"Test Project\" \"Q1 Goals\"\n```\n\n**Error Handling:**\n- Returns error if project is not linked to the specified initiative\n- Returns error if project or initiative not found\n\n### Complete Project Lifecycle Example\n\n```bash\n# 1. Create project linked to initiative\nnpx tsx scripts\u002Flinear-ops.ts create-project \"Phase 11: New Feature\" \"Skillsmith\"\n\n# 2. Set state to planned\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase 11\" planned\n\n# 3. Create issues in the project\nnpx tsx scripts\u002Flinear-ops.ts create-issue \"Phase 11\" \"Parent task\" \"Description\"\nnpx tsx scripts\u002Flinear-ops.ts create-sub-issue SMI-XXX \"Sub-task 1\" \"Details\"\n\n# 4. Start work - update to in-progress\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase 11\" in-progress\n\n# 5. Mark issues done\nnpx tsx scripts\u002Flinear-ops.ts status Done SMI-XXX SMI-YYY\n\n# 6. Complete project\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase 11\" completed\n\n# 7. (Optional) Link to additional initiative\nnpx tsx scripts\u002Flinear-ops.ts link-initiative \"Phase 11\" \"Q2 Goals\"\n```\n\n---\n\n## Tool Selection\n\nChoose the right tool for the task:\n\n1. **MCP tools (Official Server)** - **PREFERRED** for most operations when using `mcp.linear.app`\n2. **Helper Scripts \u002F GraphQL API** - Use for bulk operations or when MCP unavailable\n3. **SDK scripts** - Use for complex operations (loops, bulk updates, conditional logic, data transformations)\n\n### MCP Server Selection (CRITICAL)\n\n**Always use the official Linear MCP server** at `mcp.linear.app`. Configure in your MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"linear\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-remote\", \"https:\u002F\u002Fmcp.linear.app\u002Fsse\"],\n      \"env\": { \"LINEAR_API_KEY\": \"your_api_key\" }\n    }\n  }\n}\n```\n\n> **WARNING**: Do NOT use deprecated community servers (`linear-mcp-server` npm package, `jerhadf\u002Flinear-mcp-server`). They have critical bugs including a schema mismatch where `status` parameter fails because it's passed directly as `stateId` (requires UUID, not name).\n\n### MCP Reliability Matrix (Official Server)\n\nThe **official Linear MCP server** (`mcp.linear.app`) is significantly more reliable than community alternatives:\n\n| Operation | MCP Tool | Reliability | Notes |\n|-----------|----------|-------------|-------|\n| Create issue | `create_issue` | ✅ High | Full support |\n| **Update issue status** | `update_issue` | ✅ **Works with names!** | Use `state: \"Done\"` directly |\n| List issues | `list_issues` | ✅ High | Supports filters |\n| Search issues | `list_issues` with `query` | ✅ High | Use query parameter |\n| Get user issues | `list_issues` with `assignee: \"me\"` | ✅ High | Reliable |\n| Add comment | `create_comment` | ✅ High | Works with issue IDs |\n\n**Key Improvement**: The official server accepts human-readable state names (e.g., `state: \"Done\"`, `state: \"In Progress\"`) and resolves them to UUIDs internally. No need for manual UUID lookups!\n\n### Quick Status Update\n\n**With the official MCP server**, you can now update status directly using human-readable names:\n\n```\n# Via MCP (official server) - NOW WORKS!\nupdate_issue with id=\"issue-uuid\", state=\"Done\"\nupdate_issue with id=\"issue-uuid\", state=\"In Progress\"\n```\n\n**Alternative: API wrapper** (for bulk operations or when MCP unavailable):\n\n```bash\n# Update single issue (use issue identifier like PROJ-123)\nnode ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Flinear-api.mjs update-status --issue \u003CTEAM>-123 --status Done\n\n# Available states: Backlog, Todo, In Progress, In Review, Done, Canceled\n```\n\n### Linear API Wrapper (scripts\u002Flinear-api.mjs)\n\nA complete API wrapper with proper JSON escaping and error handling:\n\n```bash\n# Create issue (replace \u003CTEAM> with your team key, e.g., ENG, PROJ)\nnode ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Flinear-api.mjs create-issue \\\n  --team \u003CTEAM> --title \"New feature\" --description \"Details here\" --priority 2\n\n# Update status (replace \u003CTEAM>-123 with your issue identifier)\nnode ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Flinear-api.mjs update-status \\\n  --issue \u003CTEAM>-123 --status done\n\n# Add comment\nnode ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Flinear-api.mjs add-comment \\\n  --issue \u003CTEAM>-123 --body \"Fixed in PR #25\"\n\n# Add project update\nnode ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Flinear-api.mjs add-project-update \\\n  --project \u003CPROJECT_UUID> --body \"## Status Update\\n\\nProgress details...\" --health onTrack\n\n# List issues\nnode ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Flinear-api.mjs list-issues \\\n  --team \u003CTEAM> --status \"In Progress\" --limit 20\n\n# List labels\nnode ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Flinear-api.mjs list-labels --team \u003CTEAM>\n\n# Help\nnode ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Flinear-api.mjs help\n```\n\n**Benefits over MCP:**\n- Proper JSON escaping (no shell parsing issues)\n- Reliable status updates (uses correct GraphQL types)\n- Batch-friendly for scripting\n- Can be imported as ES module for programmatic use\n\n**Why not MCP?** The `linear_update_issue` MCP tool frequently fails with schema validation errors and timeouts. The helper script uses direct GraphQL which is 100% reliable.\n\n### Quick Comment by Issue Number\n\nAdd comments without needing to look up UUIDs:\n\n```bash\n# Simple comment (use the issue number, e.g., 123 for PROJ-123)\nnode scripts\u002Flinear-helpers.mjs add-comment 123 \"Fixed in PR #25\"\n\n# Multi-line comment (use quotes)\nnode scripts\u002Flinear-helpers.mjs add-comment 123 \"## Resolved\n\nImplementation complete. All tests passing.\"\n```\n\n**Pattern**: Use MCP for issue creation, helper scripts for status updates and comments, and direct GraphQL for searches and complex queries.\n\n### Historical: Why Community MCP Servers Failed\n\n> **Note**: These issues are **resolved** with the official Linear MCP server at `mcp.linear.app`. This section is preserved for reference when troubleshooting deprecated community server configurations.\n\n#### Issue 1: Status Update Schema Mismatch (FIXED in Official Server)\n\nThe deprecated `linear-mcp-server` (npm) had a critical bug:\n\n| Community Server | Official Server |\n|------------------|-----------------|\n| `status: \"Done\"` → passed as `stateId` (UUID required) → ❌ Fails | `state: \"Done\"` → resolved internally → ✅ Works |\n\n**The official server correctly resolves state names to UUIDs internally.**\n\n#### Issue 2: SSE Connection Timeouts\n\nBoth servers can experience SSE connection drops after extended idle periods. The official server has improved keep-alive handling, but for very long operations, helper scripts remain a reliable fallback.\n\n**Best Practice**: Use the official MCP server for most operations. Fall back to helper scripts for bulk operations or timeout-prone scenarios.\n\n## Critical Requirements\n\n### ⚠️ MANDATORY: Issues → Projects → Initiatives\n\n**Every issue MUST be attached to a project. Every project MUST be linked to an initiative.**\n\nOrphaned issues and projects are invisible in roadmap views and break tracking.\n\n| Entity | Must Link To | Consequence if Missing |\n|--------|--------------|------------------------|\n| Issue | Project | Not visible in project board |\n| Project | Initiative | Not visible in initiative roadmap |\n\n**Anti-Pattern (NEVER DO):**\n```bash\n# ❌ Creating orphaned issues\nmcp__linear__linear_create_issue with title=\"My task\"\n# Issue exists but is not part of any project!\n```\n\n**Correct Pattern (ALWAYS DO):**\n```bash\n# ✅ Create issue AND add to project in same workflow\nmcp__linear__linear_create_issue with title=\"My task\" ...\nnode scripts\u002Flinear-helpers.mjs add-issues-to-project \u003CprojectId> \u003CissueNumber>\n\n# ✅ Create project AND link to initiative\nlinear projects create --name \"Phase N: Name\"\nnode scripts\u002Flinear-helpers.mjs link-project \u003CprojectId>\n```\n\n### Helper Script: Update Issue Status\n\n**⚡ PRIMARY METHOD** - Always use the helper script for status updates (API-first for reliability):\n\n```bash\n# Update multiple issues to Done (use issue numbers without prefix)\nnode scripts\u002Flinear-helpers.mjs update-status Done 101 102 103\n\n# Available states: Backlog, Todo, In Progress, In Review, Done, Canceled\n```\n\n**Never use MCP's `linear_update_issue`** - it fails ~50% of the time with schema validation errors. The helper script uses direct GraphQL API calls which are 100% reliable.\n\n---\n\n## Conventions\n\n### Issue Status\n\nWhen creating issues, set the appropriate status based on assignment:\n\n- **Assigned to me** (`assignee: \"me\"`): Set `state: \"Todo\"`\n- **Unassigned**: Set `state: \"Backlog\"`\n\nExample:\n```typescript\n\u002F\u002F Issue for myself (replace \"TEAM\" with your team key)\nawait linear.create_issue({\n  team: \"TEAM\",\n  title: \"Fix authentication bug\",\n  assignee: \"me\",\n  state: \"Todo\"\n})\n\n\u002F\u002F Unassigned issue\nawait linear.create_issue({\n  team: \"TEAM\",\n  title: \"Research API performance\",\n  state: \"Backlog\"\n})\n```\n\n### Querying Issues\n\nUse `assignee: \"me\"` to filter issues assigned to the authenticated user:\n\n```typescript\n\u002F\u002F My issues\nawait linear.list_issues({ assignee: \"me\" })\n\n\u002F\u002F Team backlog (replace \"TEAM\" with your team key)\nawait linear.list_issues({ team: \"TEAM\", state: \"Backlog\" })\n```\n\n### Labels\n\nThis skill uses a **domain-based label taxonomy** for consistent categorization. See [docs\u002Flabels.md](docs\u002Flabels.md) for the complete guide.\n\n**Key rules:**\n- Always apply exactly ONE Type label: `feature`, `bug`, `refactor`, `chore`, or `spike`\n- Apply 1-2 Domain labels for agent routing: `security`, `backend`, `frontend`, etc.\n- Add Scope labels only when applicable: `blocked`, `breaking-change`, `tech-debt`, etc.\n\n**Taxonomy commands:**\n```bash\n# Show full taxonomy\nnpx tsx scripts\u002Flinear-ops.ts labels taxonomy\n\n# Validate labels before creating issues\nnpx tsx scripts\u002Flinear-ops.ts labels validate \"feature,security,breaking-change\"\n\n# Suggest labels based on issue title\nnpx tsx scripts\u002Flinear-ops.ts labels suggest \"Fix XSS vulnerability in login form\"\n\n# Show agent recommendations for labels\nnpx tsx scripts\u002Flinear-ops.ts labels agents \"security,performance\"\n```\n\nYou can use label names directly in `create_issue` and `update_issue` - no need to look up IDs:\n\n```typescript\nawait linear.create_issue({\n  team: \"TEAM\",\n  title: \"Update documentation\",\n  labels: [\"documentation\", \"chore\"]  \u002F\u002F Use taxonomy labels\n})\n```\n\n## SDK Automation Scripts\n\n**Use only when MCP tools are insufficient.** For complex operations involving loops, mapping, or bulk updates, write TypeScript scripts using `@linear\u002Fsdk`. See `sdk.md` for:\n\n- Complete script patterns and templates\n- Common automation examples (bulk updates, filtering, reporting)\n- Tool selection criteria\n\nScripts provide full type hints and are easier to debug than raw GraphQL for multi-step operations.\n\n## GraphQL API\n\n**Fallback only.** Use when operations aren't supported by MCP or SDK. See `api.md` for documentation on using the Linear GraphQL API directly.\n\n### Timeout Handling Patterns\n\nWhen operations take longer than expected, use these patterns to maintain reliability:\n\n**1. Progress Notifications**\nFor bulk operations, notify the user of progress:\n\n```javascript\nconst issues = ['PROJ-101', 'PROJ-102', 'PROJ-103'];\nfor (let i = 0; i \u003C issues.length; i++) {\n  console.log(`Processing ${i + 1}\u002F${issues.length}: ${issues[i]}`);\n  \u002F\u002F ... operation\n}\n```\n\n**2. Chunked Batch Operations**\nBreak large batches into smaller chunks to avoid timeouts:\n\n```javascript\nconst BATCH_SIZE = 10;\nconst DELAY_MS = 150; \u002F\u002F Avoid rate limiting\n\nfor (let i = 0; i \u003C issues.length; i += BATCH_SIZE) {\n  const batch = issues.slice(i, i + BATCH_SIZE);\n  console.log(`Batch ${Math.floor(i \u002F BATCH_SIZE) + 1}: Processing ${batch.length} issues`);\n\n  for (const issue of batch) {\n    await processIssue(issue);\n    await new Promise(r => setTimeout(r, DELAY_MS));\n  }\n}\n```\n\n**3. Fallback on Timeout**\nDetect timeouts and fall back to GraphQL:\n\n```javascript\ntry {\n  \u002F\u002F Try MCP first (faster when it works)\n  await mcp__linear__linear_search_issues({ query: \"keyword\" });\n} catch (error) {\n  if (error.message.includes('timeout') || error.message.includes('ETIMEDOUT')) {\n    console.log('MCP timed out, falling back to GraphQL...');\n    \u002F\u002F Use GraphQL workaround (see below)\n  }\n}\n```\n\n**4. Bulk Sync Script**\nUse `scripts\u002Fsync.ts` for reliable bulk state updates:\n\n```bash\n# Update multiple issues to Done state (replace PROJ with your team prefix)\nLINEAR_API_KEY=lin_api_xxx npx tsx scripts\u002Fsync.ts --issues PROJ-101,PROJ-102,PROJ-103 --state Done\n\n# Preview changes without applying\nLINEAR_API_KEY=lin_api_xxx npx tsx scripts\u002Fsync.ts --issues PROJ-101,PROJ-102 --state Done --dry-run\n\n# Add comment with state change\nLINEAR_API_KEY=lin_api_xxx npx tsx scripts\u002Fsync.ts --issues PROJ-101 --state Done --comment \"Completed in PR #42\"\n```\n\n### MCP Timeout Workarounds\n\nWhen MCP times out or fails, use these direct GraphQL patterns:\n\n#### ⚠️ Shell Script Compatibility\n\n**IMPORTANT**: When writing inline Node.js scripts in bash, avoid JavaScript features that confuse shell parsing:\n\n| Feature | Problem | Solution |\n|---------|---------|----------|\n| Optional chaining `?.` | Shell sees `?` as glob | Use explicit null checks |\n| Nullish coalescing `??` | Double `?` confuses parser | Use ternary `? :` |\n| Heredocs with `${}` | Shell interpolation | Use `\u003C\u003C 'EOF'` (quoted) |\n\n**Anti-Pattern (breaks in bash):**\n```javascript\n\u002F\u002F ❌ Optional chaining breaks shell parsing\nconst name = project.status?.name;\n```\n\n**Correct Pattern:**\n```javascript\n\u002F\u002F ✅ Explicit null check works everywhere\nconst name = project.status ? project.status.name : 'No status';\n```\n\n**Heredoc Pattern:**\n```bash\n# ✅ Use quoted EOF to prevent shell interpolation\nnode --input-type=module \u003C\u003C 'ENDSCRIPT'\nconst value = obj.prop ? obj.prop.nested : 'default';\nENDSCRIPT\n```\n\n#### Search Issues (when MCP times out)\n\n```javascript\n\u002F\u002F Inline GraphQL via node --experimental-fetch\nnode --experimental-fetch -e \"\nasync function searchIssues() {\n  const query = \\`\n    query {\n      issues(filter: {\n        team: { key: { eq: \\\"TEAM\\\" } }\n        state: { type: { nin: [\\\"completed\\\", \\\"canceled\\\"] } }\n      }, first: 25) {\n        nodes {\n          id identifier title state { name } priority\n        }\n      }\n    }\n  \\`;\n\n  const res = await fetch('https:\u002F\u002Fapi.linear.app\u002Fgraphql', {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application\u002Fjson',\n      'Authorization': process.env.LINEAR_API_KEY\n    },\n    body: JSON.stringify({ query })\n  });\n\n  const data = await res.json();\n  data.data.issues.nodes.forEach(i => {\n    console.log(\\`\\${i.identifier}: \\${i.title} [\\${i.state.name}]\\`);\n  });\n}\nsearchIssues();\n\"\n```\n\n#### Update Issue Status (when MCP is unreliable)\n\n```javascript\n\u002F\u002F First get the workflow state ID for \"Done\"\nconst stateQuery = \\`\n  query {\n    workflowStates(filter: { team: { key: { eq: \\\"TEAM\\\" } }, name: { eq: \\\"Done\\\" } }) {\n      nodes { id name }\n    }\n  }\n\\`;\n\n\u002F\u002F Then update the issue\nconst mutation = \\`\n  mutation {\n    issueUpdate(id: \"\\${issueUuid}\", input: { stateId: \"\\${doneStateId}\" }) {\n      success\n      issue { identifier state { name } }\n    }\n  }\n\\`;\n```\n\n#### Add Comment (MCP fails with UUIDs)\n\n```javascript\n\u002F\u002F Get issue UUID from identifier\nconst issueQuery = \\`\n  query {\n    issues(filter: { number: { in: [123, 124, 125] } }) {\n      nodes { id identifier }\n    }\n  }\n\\`;\n\n\u002F\u002F Add comment using UUID\nconst mutation = \\`\n  mutation {\n    commentCreate(input: {\n      issueId: \"\\${issueUuid}\",\n      body: \"Implementation complete. See PR #42.\"\n    }) { success }\n  }\n\\`;\n```\n\n**Pro Tip**: Store frequently-used IDs (team UUID, common state UUIDs) in your project's CLAUDE.md to avoid repeated lookups.\n\n### Ad-Hoc Queries\n\nUse `scripts\u002Fquery.ts` to execute GraphQL queries:\n\n```bash\nLINEAR_API_KEY=lin_api_xxx node scripts\u002Fquery.ts \"query { viewer { id name } }\"\n```\n\nIf `LINEAR_API_KEY` is not provided to the Claude process, inform the user that GraphQL queries cannot be executed without an API key.\n\n## Projects & Initiatives\n\n### MANDATORY: Project Content & Updates\n\n**Every project operation MUST include these steps. Never skip them.**\n\nWhen **creating** a project:\n1. ✅ Set `content` (full markdown for main panel)\n2. ✅ Set `description` (255 char summary for lists)\n3. ✅ Link to parent initiative\n4. ✅ Add resource links (docs, repos)\n5. ✅ Create initial project update with scope\n\nWhen **updating** project status:\n1. ✅ Update `statusId` to new status\n2. ✅ Create project update documenting the change\n3. ✅ Include progress metrics (X\u002FY issues complete)\n\nWhen **completing** work:\n1. ✅ Update issue statuses to Done\n2. ✅ Update project status to match\n3. ✅ Create final project update with summary\n\n**Example: Mandatory Project Update**\n\n```javascript\n\u002F\u002F ALWAYS create an update when project status changes\nnode --experimental-fetch -e \"\nconst PROJECT_ID = '\u003Cuuid>';\n\nconst update = \\`## Status: In Progress ?\n\n**Date:** $(date '+%Y-%m-%d')\n\n### Completed\n- ✅ Task 1 done\n- ✅ Task 2 done\n\n### In Progress\n- ? Task 3 in progress\n\n### Up Next\n- ? Task 4 pending\n\\`;\n\nconst mutation = \\`mutation {\n  projectUpdateCreate(input: {\n    projectId: \\\\\\\"\\${PROJECT_ID}\\\\\\\",\n    body: \\${JSON.stringify(update)},\n    health: onTrack\n  }) { success projectUpdate { url } }\n}\\`;\n\nfetch('https:\u002F\u002Fapi.linear.app\u002Fgraphql', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application\u002Fjson', 'Authorization': process.env.LINEAR_API_KEY },\n  body: JSON.stringify({ query: mutation })\n}).then(r => r.json()).then(d => console.log('Update created:', d.data?.projectUpdateCreate?.projectUpdate?.url));\n\"\n```\n\n---\n\n### Content vs Description (CRITICAL)\n\nLinear has **two text fields** - using the wrong one causes blank displays:\n\n| Field | Limit | Shows In | Use For |\n|-------|-------|----------|---------|\n| `description` | 255 chars | List views, tooltips | Short summary |\n| `content` | Unlimited | **Main detail panel** | Full markdown documentation |\n\n**Always set BOTH when creating\u002Fupdating projects:**\n\n```graphql\n# Content is what users see in the main panel!\nmutation {\n  projectUpdate(id: \"\u003Cuuid>\", input: {\n    content: \"# Project Title\\n\\nFull markdown description...\",\n    description: \"Short 255 char summary for list views\"\n  }) { success }\n}\n```\n\n### Discovery Before Creation (MANDATORY)\n\n**ALWAYS check Linear before creating ANY project or issue.** Skipping this step causes duplicate projects and wasted effort.\n\n```bash\n# Check for existing projects\nlinear projects list | grep -i \"phase\\|\u003Cfeature-name>\"\n\n# Check for existing issues (MCP may timeout - use CLI as fallback)\nlinear issues list --filter \"title:Phase N\"\n# Or: mcp__linear__linear_search_issues with query=\"Phase N feature\"\n```\n\n**Checklist before ANY create operation:**\n\n| Check | Command | Action if Found |\n|-------|---------|-----------------|\n| Project exists? | `linear projects list \\| grep -i \"name\"` | Use existing UUID, skip creation |\n| Issues exist? | `linear issues list --filter \"title:keyword\"` | Review existing, update if needed |\n| Initiative linked? | Check project in Linear UI | Skip link-project step |\n\n**NEVER skip discovery. Duplicate projects waste time and create confusion.**\n\n---\n\n### Codebase Verification Before Work (MANDATORY)\n\n**ALWAYS verify codebase state before accepting Linear issue scope at face value.**\n\nIssue descriptions may be **outdated** or **speculative** — written before code exploration. This is especially common when:\n- Issues were created during planning, not after code review\n- The codebase evolved since the issue was created\n- API endpoints or features were implemented but not documented in Linear\n\n**Key Lesson**: Issues describing \"missing\" APIs or features may already be implemented.\n\n```bash\n# Before starting any API\u002Ffeature implementation issue:\n\n# 1. Search for existing implementations\ngrep -r \"apiEndpoint\\|functionName\" src\u002F\n\n# 2. Check if files already exist\nls src\u002Fpages\u002Fapi\u002Fadmin\u002Fmembers\u002F  # If issue says \"implement members API\"\n\n# 3. Read existing code\ncat src\u002Fpages\u002Fapi\u002Fadmin\u002Fmembers\u002Findex.ts  # May already be complete!\n\n# 4. Run tests to see what's actually failing\nnpx playwright test tests\u002Fe2e\u002Fjourneys\u002Fadmin\u002F\n```\n\n**Checklist before accepting issue scope:**\n\n| Check | Method | If Found |\n|-------|--------|----------|\n| API exists? | `ls src\u002Fpages\u002Fapi\u002F**\u002F*.ts` | Update issue scope to \"verify\u002Ftest\" |\n| Feature implemented? | `grep -r \"featureName\" src\u002F` | Mark implementation subtasks as done |\n| Tests passing? | Run test suite | Focus on fixing failures, not reimplementing |\n| Only tests skipped? | Check for `test.skip` | Real work is un-skipping + fixing assertions |\n\n**Example: Scope Discovery**\n\nIssue says: \"Implement \u002Fapi\u002Fadmin\u002Fmembers CRUD endpoints\"\n\n**BEFORE starting:**\n```bash\n# Check if files exist\nls src\u002Fpages\u002Fapi\u002Fadmin\u002Fmembers\u002F\n# Output: index.ts  [id].ts  ← Files exist!\n\n# Read the implementation\ncat src\u002Fpages\u002Fapi\u002Fadmin\u002Fmembers\u002Findex.ts | head -50\n# Output: Full implementation with GET, POST, auth checks\n\n# Check why tests fail\ngrep -r \"test.describe.skip\" tests\u002Fe2e\u002Fjourneys\u002Fadmin\u002F\n# Output: member-management.spec.ts uses test.describe.skip\n```\n\n**CORRECTED scope**: \"Un-skip E2E tests and fix any assertion failures\" (not \"implement API\")\n\n**Update Linear immediately when scope changes:**\n```bash\nnode scripts\u002Flinear-helpers.mjs add-comment 123 \"## Scope Update\n\n**Discovery:** API endpoints are ALREADY COMPLETE!\n\n### Actual Remaining Work\n1. Un-skip journey tests\n2. Fix any test assertion failures\n3. Verify tests pass\"\n```\n\n**NEVER assume issue descriptions are accurate. Verify codebase state first.**\n\n---\n\n## Sub-Issue Management (Parent-Child Relationships)\n\nLinear supports hierarchical issue organization through parent-child relationships. Sub-issues (children) appear nested under their parent issue in the UI and inherit certain properties.\n\n### When to Use Sub-Issues\n\n| Scenario | Use Sub-Issues | Example |\n|----------|----------------|---------|\n| Feature breakdown | ✅ Yes | ENG-100 \"Auth System\" → ENG-101 \"TDD tests\", ENG-102 \"E2E tests\" |\n| Related but independent | ❌ No | Two bugs in different areas (use labels instead) |\n| Sequential phases | ✅ Yes | ENG-200 \"Phase 1\" → ENG-201 \"Setup\", ENG-202 \"Implementation\" |\n| Tracking subtasks | ✅ Yes | Break down a large issue into trackable pieces |\n\n### Commands\n\n```bash\n# Create a sub-issue (child) under a parent issue\n# Inherits team and project from parent automatically\nnpx tsx scripts\u002Flinear-ops.ts create-sub-issue \u003Cparent-issue> \u003Ctitle> [description] [--priority 1-4] [--labels label1,label2]\n\n# Set existing issues as children of a parent\nnpx tsx scripts\u002Flinear-ops.ts set-parent \u003Cparent-issue> \u003Cchild-issues...>\n\n# List all sub-issues of a parent\nnpx tsx scripts\u002Flinear-ops.ts list-sub-issues \u003Cparent-issue>\n```\n\n### Examples\n\n```bash\n# Create a sub-issue for unit tests under a parent feature issue\nnpx tsx scripts\u002Flinear-ops.ts create-sub-issue ENG-100 \"Add unit tests\" \"Unit tests for new feature\" --priority 2 --labels testing\n\n# Link existing issues as children of a parent\nnpx tsx scripts\u002Flinear-ops.ts set-parent ENG-100 ENG-101 ENG-102\n\n# List all sub-issues of a parent\nnpx tsx scripts\u002Flinear-ops.ts list-sub-issues ENG-100\n```\n\n### Notes\n\n- **Inheritance**: Sub-issues automatically inherit the team from the parent\n- **Project linking**: If the parent is in a project, sub-issues can also be added\n- **Status independence**: Each issue maintains its own status (completing a sub-issue doesn't auto-complete the parent)\n- **UI display**: Sub-issues appear indented under their parent in list views\n\n---\n\n### Linking Projects to Initiatives\n\n**Use `initiativeToProjectCreate` to link an existing project to an initiative:**\n\n```graphql\nmutation {\n  initiativeToProjectCreate(input: {\n    initiativeId: \"\u003Cinitiative-uuid>\",\n    projectId: \"\u003Cproject-uuid>\"\n  }) {\n    success\n    initiativeToProject { id }\n  }\n}\n```\n\n**Example using query.ts:**\n\n```bash\nnpx tsx ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Fquery.ts 'mutation {\n  initiativeToProjectCreate(input: {\n    initiativeId: \"\u003Cinitiative-uuid>\",\n    projectId: \"\u003Cproject-uuid>\"\n  }) {\n    success\n  }\n}'\n```\n\n**Note:** This is different from setting `initiativeId` at project creation time. Use this mutation when:\n- A project was created without an initiative link\n- You need to add a project to an additional initiative\n- Reorganizing projects between initiatives\n\n---\n\n### New Phase Project Pattern\n\n**Step 0: Run Discovery Checks (see above)**\n\nWhen creating a new phase, follow this complete workflow:\n\n```bash\n# 0. DISCOVERY - Check for existing project\u002Fissues first!\nlinear projects list | grep -i \"phase N\"\n\n# 1. Create project via CLI (ONLY if Step 0 found nothing)\nlinear projects create --name \"Phase N: Name\" --description \"Short summary\"\n\n# 2. Link to initiative (use initiativeToProjectCreate mutation - see above)\nnpx tsx scripts\u002Fquery.ts 'mutation { initiativeToProjectCreate(input: { initiativeId: \"\u003Cuuid>\", projectId: \"\u003Cuuid>\" }) { success } }'\n\n# 3. Set content (main UI panel)\n# Use GraphQL to set full markdown content\n\n# 4. Add resource link to implementation doc\n# Use entityExternalLinkCreate mutation\n\n# 5. Create milestone for Definition of Done\n# Use projectMilestoneCreate mutation\n\n# 6. Create issues via MCP (check for existing first!)\n# 7. Add issues to project\n```\n\n---\n\n## ⚠️ MANDATORY: Project Creation Checklist\n\n> **CRITICAL**: Every script that creates projects MUST follow this checklist.\n> Skipping steps causes recurring issues with orphaned projects and missing links.\n\n### Required Steps\n\n| # | Step | How | Verify |\n|---|------|-----|--------|\n| 1 | **Link to initiative** | `initiativeToProjectCreate` mutation | Check initiative.projects |\n| 2 | **Set description** | `description` field (255 char limit) | View in sidebar |\n| 3 | **Set content** | `content` field via `projectUpdate` | View main panel |\n| 4 | **Add resource links** | `entityExternalLinkCreate` mutation | Check Resources section |\n| 5 | **Create milestones** | `projectMilestoneCreate` mutation | Check Milestones tab |\n| 6 | **Ensure labels exist** | Use `lib\u002Flabels.ts` utilities | Query labels before\u002Fafter |\n| 7 | **Create issues with labels** | Include `labelIds` in `createIssue` | View issue labels |\n| 8 | **Verify issue count** | Compare expected vs actual | Log counts |\n| 9 | **Run verification** | Use `lib\u002Fverify.ts` | Check output |\n| 10 | **Report failures** | Log all errors, don't fail silently | Review logs |\n\n### Using Shared Utilities\n\n**Always use the lib\u002F utilities** to avoid common mistakes:\n\n```typescript\nimport {\n  linkProjectToInitiative,\n  ensureLabelsExist,\n  verifyProjectCreation,\n  createProject,\n  createProjectWithDefaults,\n  DEFAULT_INITIATIVE_ID\n} from '.\u002Flib'\n\n\u002F\u002F Option 1: Full template with explicit initiative\nconst result = await createProject(teamId, {\n  name: 'My Project Phase X: Name',\n  shortDescription: 'Short 255 char description',\n  content: '# Full markdown content...',\n  state: 'planned',\n  initiative: '\u003Cyour-initiative-uuid>',\n  issues: [\n    { title: 'Issue', description: 'Desc', labels: ['label1'] }\n  ]\n})\n\n\u002F\u002F Option 2: Use environment variable for initiative\n\u002F\u002F Requires: LINEAR_DEFAULT_INITIATIVE_ID=\u003Cuuid>\nconst result2 = await createProjectWithDefaults({\n  name: 'My Project Phase X: Name',\n  shortDescription: 'Short description',\n  content: '# Full content...',\n  state: 'planned',\n  issues: []\n})\n\n\u002F\u002F Option 3: Manual with utilities\nconst linkResult = await linkProjectToInitiative(projectId, initiativeId)\nconst labelResult = await ensureLabelsExist(teamId, ['label1', 'label2'])\nconst verification = await verifyProjectCreation('Phase X', expectedCount, undefined, initiativeId)\n```\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `LINEAR_API_KEY` | Yes | Your Linear API key |\n| `LINEAR_DEFAULT_INITIATIVE_ID` | No | Default initiative for `createProjectWithDefaults()` |\n\n### Common Mistakes\n\n| Mistake | Symptom | Fix |\n|---------|---------|-----|\n| Using `initiativeIds` on `projectUpdate` | Silent failure | Use `initiativeToProjectCreate` mutation |\n| Long description | Truncated in UI | Use `content` for full text, `description` for summary |\n| Case-sensitive label lookup | Labels not applied | Use case-insensitive map (`name.toLowerCase()`) |\n| Silent failures | Missing issues\u002Flabels | Always check result, log errors |\n| No post-verification | Issues discovered later | Run `lib\u002Fverify.ts` after creation |\n\n### Resource Links\n\nAdd clickable links to projects\u002Finitiatives (shows in Resources section):\n\n```graphql\nmutation {\n  entityExternalLinkCreate(input: {\n    url: \"https:\u002F\u002Fgithub.com\u002Forg\u002Frepo\u002Fblob\u002Fmain\u002Fdocs\u002Fimplementation\u002Fphase-N.md\",\n    label: \"Implementation Doc\",\n    projectId: \"\u003Cproject-uuid>\"\n  }) { success }\n}\n```\n\n**Standard resource links for phases:**\n- `Implementation Doc` → docs\u002Fimplementation\u002Fphase-N-*.md\n- `Production Site` → deployment URL (for initiative)\n- `Repository` → GitHub repo link (for initiative)\n\n### Project Milestones (Definition of Done)\n\nTrack completion criteria with milestones:\n\n```graphql\nmutation {\n  projectMilestoneCreate(input: {\n    projectId: \"\u003Cuuid>\",\n    name: \"DoD: Testing\",\n    description: \"Unit tests, E2E tests, 100% coverage\"\n  }) { success }\n}\n```\n\n**Standard DoD milestones:**\n- `DoD: Core Feature` - Main functionality complete\n- `DoD: Testing` - All tests pass, coverage met\n- `DoD: Security` - Security requirements verified\n- `DoD: Accessibility` - A11y requirements met\n\n### Project Status (IMPORTANT)\n\n**Project status is NOT auto-updated when issues move.** You must explicitly update project status.\n\n#### Project Status vs Issue Status\n\n| Concept | Applies To | Field | Auto-Updates? |\n|---------|------------|-------|---------------|\n| **Issue Status** | Individual issues | `stateId` | Yes (via workflow) |\n| **Project Status** | Entire project | `statusId` | ❌ No - manual only |\n\n#### Status Types and UUIDs\n\nQuery your workspace's status UUIDs (workspace-specific):\n\n```graphql\nquery { projectStatuses { nodes { id name type } } }\n```\n\n**Standard Status Types:**\n\n| Status | Type | When to Use |\n|--------|------|-------------|\n| `Backlog` | `backlog` | Project created but not started |\n| `Planned` | `planned` | Project scheduled, issues created |\n| `In Progress` | `started` | **Issues actively being worked** |\n| `Completed` | `completed` | All issues done |\n| `Canceled` | `canceled` | Project abandoned |\n\n#### When to Update Project Status\n\nUpdate project status at these transition points:\n\n| Trigger | New Status | Check |\n|---------|------------|-------|\n| First issue moves to \"In Progress\" | `In Progress` | Any issue has `started` state |\n| All issues complete | `Completed` | No issues in backlog\u002Fprogress |\n| Work begins on phase | `In Progress` | Manual or first issue started |\n| Phase fully implemented | `Completed` | All tests pass, PR merged |\n\n#### Update Project Status\n\n```graphql\nmutation {\n  projectUpdate(id: \"\u003Cproject-uuid>\", input: {\n    statusId: \"\u003Cstatus-uuid>\"\n  }) {\n    success\n    project { name status { name } }\n  }\n}\n```\n\n#### Check Project Issue Progress\n\nBefore updating status, check issue states:\n\n```graphql\nquery {\n  project(id: \"\u003Cproject-uuid>\") {\n    name\n    status { name }\n    issues {\n      nodes {\n        identifier\n        state { name type }\n      }\n    }\n  }\n}\n```\n\n**Logic for auto-determining status:**\n- If ANY issue has `state.type = \"started\"` → Project is `In Progress`\n- If ALL issues have `state.type = \"completed\"` → Project is `Completed`\n- If NO issues started → Project is `Planned` or `Backlog`\n\n#### Helper: Update Project Status Script\n\n```javascript\n\u002F\u002F Check project issues and update status accordingly\nnode -e \"\nconst PROJECT_ID = '\u003Cproject-uuid>';\n\n\u002F\u002F Status UUIDs (query your workspace for these)\nconst STATUS = {\n  backlog: '1ed7da89-db44-4339-b0d7-ce37d8ff9604',\n  planned: '33ebbb84-53ea-4dd8-a8db-49a8b3b9c502',\n  inProgress: '71d18c8f-53de-4752-be37-a6d529cb9c97',\n  completed: '54294a72-010d-4ae7-9829-bed76232fb66'\n};\n\nasync function updateProjectStatus() {\n  \u002F\u002F Get project issues\n  const issueQuery = \\`query {\n    project(id: \\\"${PROJECT_ID}\\\") {\n      name\n      issues { nodes { state { type } } }\n    }\n  }\\`;\n\n  const res = await fetch('https:\u002F\u002Fapi.linear.app\u002Fgraphql', {\n    method: 'POST',\n    headers: { 'Content-Type': 'application\u002Fjson', 'Authorization': process.env.LINEAR_API_KEY },\n    body: JSON.stringify({ query: issueQuery })\n  });\n  const { data } = await res.json();\n\n  const issues = data.project.issues.nodes;\n  const states = issues.map(i => i.state.type);\n\n  \u002F\u002F Determine appropriate status\n  let newStatus;\n  if (states.every(s => s === 'completed')) {\n    newStatus = STATUS.completed;\n  } else if (states.some(s => s === 'started')) {\n    newStatus = STATUS.inProgress;\n  } else {\n    newStatus = STATUS.planned;\n  }\n\n  \u002F\u002F Update project\n  const mutation = \\`mutation {\n    projectUpdate(id: \\\"${PROJECT_ID}\\\", input: { statusId: \\\"${newStatus}\\\" }) {\n      success\n      project { name status { name } }\n    }\n  }\\`;\n\n  const updateRes = await fetch('https:\u002F\u002Fapi.linear.app\u002Fgraphql', {\n    method: 'POST',\n    headers: { 'Content-Type': 'application\u002Fjson', 'Authorization': process.env.LINEAR_API_KEY },\n    body: JSON.stringify({ query: mutation })\n  });\n  const result = await updateRes.json();\n  console.log('Updated:', result.data.projectUpdate.project);\n}\n\nupdateProjectStatus();\n\"\n```\n\n### Project Updates (Status Reports)\n\nPost status updates to a project's Updates tab. These are visible at `\u002Fproject\u002F{slug}\u002Fupdates`.\n\n#### Create Project Update\n\n```graphql\nmutation {\n  projectUpdateCreate(input: {\n    projectId: \"\u003Cproject-uuid>\",\n    body: \"## Status Update\\n\\nMarkdown content here...\",\n    health: onTrack\n  }) {\n    success\n    projectUpdate {\n      id\n      url\n      createdAt\n    }\n  }\n}\n```\n\n**Health Options:**\n- `onTrack` - ? Project proceeding as planned\n- `atRisk` - ? Issues that may cause delays\n- `offTrack` - ? Project is behind schedule\n\n#### Example: Post Progress Update\n\n```javascript\nnode -e \"\nconst projectId = '\u003Cproject-uuid>';\n\nconst updateBody = \\`## Status: In Progress ?\n\n**Swarm execution started** — agents actively implementing features.\n\n### Progress\n- **32% complete** (9\u002F28 issues done)\n- Project status updated to **In Progress**\n\n### Completed\n- ✅ Foundation setup\n- ✅ Core configuration\n\n### In Progress\n- ? Main feature implementation\n- ? UI components\n\n### Up Next\n- Testing suite\n- Documentation\n\\`;\n\nconst mutation = \\`mutation {\n  projectUpdateCreate(input: {\n    projectId: \\\\\\\"\\${projectId}\\\\\\\",\n    body: \\${JSON.stringify(updateBody)},\n    health: onTrack\n  }) {\n    success\n    projectUpdate { id }\n  }\n}\\`;\n\nfetch('https:\u002F\u002Fapi.linear.app\u002Fgraphql', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application\u002Fjson', 'Authorization': process.env.LINEAR_API_KEY },\n  body: JSON.stringify({ query: mutation })\n}).then(r => r.json()).then(d => console.log(JSON.stringify(d, null, 2)));\n\"\n```\n\n#### When to Post Updates\n\n| Trigger | Health | Content |\n|---------|--------|---------|\n| Work starts (swarm launched) | `onTrack` | Progress %, what's in progress |\n| Milestone reached | `onTrack` | Completed items, next steps |\n| Blockers encountered | `atRisk` | Issue description, mitigation plan |\n| Deadline at risk | `offTrack` | Root cause, revised timeline |\n| Phase complete | `onTrack` | Summary, metrics, lessons learned |\n\n---\n\n## Sync Patterns (Bulk Operations)\n\nFor bulk synchronization of code changes to Linear, see `sync.md`.\n\n### Quick Sync Commands\n\n```bash\n# Bulk update issues to Done (replace PROJ with your team prefix)\nnpx ts-node scripts\u002Fsync.ts --issues PROJ-101,PROJ-102,PROJ-103 --state Done\n\n# Update project status\nnpx ts-node scripts\u002Fsync.ts --project \"My Project\" --state completed\n\n# Verify sync completed\nnpx ts-node scripts\u002Fsync.ts --verify PROJ-101,PROJ-102 --expected-state Done\n```\n\n### Agent-Spawned Sync\n\nSpawn a parallel agent for autonomous sync:\n\n```javascript\nTask({\n  description: \"Sync project issues to Linear\",\n  prompt: \"Update PROJ-101,102,103 to Done. Then update project 'My Project' to completed.\",\n  subagent_type: \"general-purpose\"\n})\n```\n\n### Hook-Triggered Sync\n\nAuto-suggest sync after code edits. Add to `.claude\u002Fsettings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"PostToolUse\": [{\n      \"matcher\": \"Write|Edit\",\n      \"hooks\": [{\n        \"type\": \"command\",\n        \"command\": \"bash ~\u002F.claude\u002Fskills\u002Flinear\u002Fhooks\u002Fpost-edit.sh\"\n      }]\n    }]\n  }\n}\n```\n\nSee `sync.md` for complete patterns including AgentDB integration and swarm coordination.\n\n---\n\n## Reference\n\n- Linear MCP: https:\u002F\u002Flinear.app\u002Fdocs\u002Fmcp.md\n- GraphQL API: See `api.md`\n- SDK Automation: See `sdk.md`\n- Bulk Sync: See `sync.md`\n","# Linear\n\nTools and workflows for managing issues, projects, and teams in Linear.\n\n---\n\n## ⚠️ Tool Availability (READ FIRST)\n\n**This skill supports multiple tool backends. Use whichever is available:**\n\n1. **MCP Tools (mcp__linear)** - Use if available in your tool set\n2. **Linear CLI (`linear` command)** - Always available via Bash\n3. **Helper Scripts** - For complex operations\n\n**If MCP tools are NOT available**, use the Linear CLI via Bash:\n\n```bash\n# View an issue\nlinear issues view SMI-123\n\n# Create an issue\nlinear issues create --title \"Issue title\" --description \"Description\"\n\n# Update issue status (get state IDs first)\nlinear issues update SMI-123 -s \"STATE_ID\"\n\n# Add a comment\nlinear issues comment add SMI-123 -m \"Comment text\"\n\n# List issues\nlinear issues list\n```\n\n**Do NOT report \"MCP tools not available\" as a blocker** - use CLI instead.\n\n---\n\n## ? Security: Varlock Integration\n\n**CRITICAL**: Never expose API keys in terminal output or Claude's context.\n\n### Safe Commands (Always Use)\n\n```bash\n# Validate LINEAR_API_KEY is set (masked output)\nvarlock load 2>&1 | grep LINEAR\n\n# Run commands with secrets injected\nvarlock run -- npx tsx scripts\u002Fquery.ts \"query { viewer { name } }\"\n\n# Check schema (safe - no values)\ncat .env.schema | grep LINEAR\n```\n\n### Unsafe Commands (NEVER Use)\n\n```bash\n# ❌ NEVER - exposes key to Claude's context\nlinear config show\necho $LINEAR_API_KEY\nprintenv | grep LINEAR\ncat .env\n```\n\n### Setup for New Projects\n\n1. Create `.env.schema` with `@sensitive` annotation:\n   ```bash\n   # @type=string(startsWith=lin_api_) @required @sensitive\n   LINEAR_API_KEY=\n   ```\n\n2. Add `LINEAR_API_KEY` to `.env` (never commit this file)\n\n3. Configure MCP to use environment variable:\n   ```json\n   {\n     \"mcpServers\": {\n       \"linear\": {\n         \"env\": { \"LINEAR_API_KEY\": \"${LINEAR_API_KEY}\" }\n       }\n     }\n   }\n   ```\n\n4. Use `varlock load` to validate before operations\n\n---\n\n## Quick Start (First-Time Users)\n\n### 1. Check Your Setup\n\nRun the setup check to verify your configuration:\n\n```bash\nnpx tsx ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Fsetup.ts\n```\n\nThis will check:\n- LINEAR_API_KEY is set and valid\n- @linear\u002Fsdk is installed\n- Linear CLI availability (optional)\n- MCP configuration (optional)\n\n### 2. Get API Key (If Needed)\n\nIf setup reports a missing API key:\n\n1. Open [Linear](https:\u002F\u002Flinear.app) in your browser\n2. Go to **Settings** (gear icon) -> **Security & access** -> **Personal API keys**\n3. Click **Create key** and copy the key (starts with `lin_api_`)\n4. Add to your environment:\n\n```bash\n# Option A: Add to shell profile (~\u002F.zshrc or ~\u002F.bashrc)\nexport LINEAR_API_KEY=\"lin_api_your_key_here\"\n\n# Option B: Add to Claude Code environment\necho 'LINEAR_API_KEY=lin_api_your_key_here' >> ~\u002F.claude\u002F.env\n\n# Then reload your shell or restart Claude Code\n```\n\n### 3. Test Connection\n\nVerify everything works:\n\n```bash\nnpx tsx ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Fquery.ts \"query { viewer { name } }\"\n```\n\nYou should see your name from Linear.\n\n### 4. Common Operations\n\nUse the high-level operations script for simple commands:\n\n```bash\n# Create an issue in a project\nnpx tsx scripts\u002Flinear-ops.ts create-issue \"My Project\" \"Fix login bug\" \"Users cannot log in\" --priority 2\n\n# Create a sub-issue under an existing issue\nnpx tsx scripts\u002Flinear-ops.ts create-sub-issue ENG-100 \"Add unit tests\" \"Unit tests for this feature\" --priority 2\n\n# Set parent-child relationships for existing issues\nnpx tsx scripts\u002Flinear-ops.ts set-parent ENG-100 ENG-101 ENG-102\n\n# List sub-issues of a parent\nnpx tsx scripts\u002Flinear-ops.ts list-sub-issues ENG-100\n\n# Create an initiative\nnpx tsx scripts\u002Flinear-ops.ts create-initiative \"Q1 Goals\" \"Key initiatives for Q1\"\n\n# Create a project linked to an initiative\nnpx tsx scripts\u002Flinear-ops.ts create-project \"Phase 1\" \"Q1 Goals\"\n\n# Update project state (backlog, planned, in-progress, paused, completed, canceled)\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase 1\" in-progress\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase 1\" completed\n\n# Link\u002Funlink projects to initiatives\nnpx tsx scripts\u002Flinear-ops.ts link-initiative \"Phase 1\" \"Q1 Goals\"\nnpx tsx scripts\u002Flinear-ops.ts unlink-initiative \"Phase 1\" \"Q1 Goals\"\n\n# Update issue status (PREFERRED over MCP)\nnode scripts\u002Flinear-helpers.mjs update-status Done 123 124 125\n\n# List initiatives\nnpx tsx scripts\u002Flinear-ops.ts list-initiatives\n\n# Show current user\nnpx tsx scripts\u002Flinear-ops.ts whoami\n```\n\n### 5. Getting Help\n\n```bash\n# Show all available commands\nnpx tsx scripts\u002Flinear-ops.ts help\n\n# Re-run setup check anytime\nnpx tsx scripts\u002Fsetup.ts\n```\n\n---\n\n## Project Planning Workflow\n\n### Create Issues in the Correct Project from the Start\n\n**Best Practice**: When planning a new phase or initiative, create the project and its issues together in a single planning session. Avoid creating issues in a catch-all project and moving them later.\n\n#### Recommended Workflow\n\n1. **Create the project first**:\n   ```bash\n   npx tsx scripts\u002Flinear-ops.ts create-project \"Phase X: Feature Name\" \"Skillsmith\"\n   ```\n\n2. **Set project state to Planned**:\n   ```bash\n   npx tsx scripts\u002Flinear-ops.ts project-status \"Phase X: Feature Name\" planned\n   ```\n\n3. **Create issues directly in the project**:\n   ```bash\n   npx tsx scripts\u002Flinear-ops.ts create-issue \"Phase X: Feature Name\" \"Parent task\" \"Description\"\n   npx tsx scripts\u002Flinear-ops.ts create-sub-issue SMI-XXX \"Sub-task 1\" \"Description\"\n   npx tsx scripts\u002Flinear-ops.ts create-sub-issue SMI-XXX \"Sub-task 2\" \"Description\"\n   ```\n\n4. **Update project state when work begins**:\n   ```bash\n   npx tsx scripts\u002Flinear-ops.ts project-status \"Phase X: Feature Name\" in-progress\n   ```\n\n#### Why This Matters\n\n- **Traceability**: Issues are linked to their project from creation\n- **Metrics**: Project progress tracking is accurate from day one\n- **Workflow**: No time wasted moving issues between projects\n- **Organization**: Linear views and filters work correctly\n\n#### Anti-Pattern to Avoid\n\n❌ Creating issues in a \"holding\" project and moving them later:\n```bash\n# Don't do this\ncreate-issue \"Phase 6A\" \"New feature\"  # Wrong project\n# Later: manually move to Phase X      # Extra work\n```\n\n---\n\n## Project Management Commands\n\n### project-status\n\nUpdate a project's state in Linear. Accepts user-friendly terminology that maps to Linear's API.\n\n```bash\nnpx tsx scripts\u002Flinear-ops.ts project-status \u003Cproject-name> \u003Cstate>\n```\n\n**Valid States:**\n| Input | Description | API Value |\n|-------|-------------|-----------|\n| `backlog` | Not yet started | backlog |\n| `planned` | Scheduled for future | planned |\n| `in-progress` | Currently active | started |\n| `paused` | Temporarily on hold | paused |\n| `completed` | Successfully finished | completed |\n| `canceled` | Will not be done | canceled |\n\n**Examples:**\n```bash\n# Start working on a project\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase 8: MCP Decision Engine\" in-progress\n\n# Mark project complete\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase 8\" completed\n\n# Partial name matching works\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase 8\" paused\n```\n\n### link-initiative\n\nLink an existing project to an initiative.\n\n```bash\nnpx tsx scripts\u002Flinear-ops.ts link-initiative \u003Cproject-name> \u003Cinitiative-name>\n```\n\n**Examples:**\n```bash\n# Link Phase 8 to Skillsmith initiative\nnpx tsx scripts\u002Flinear-ops.ts link-initiative \"Phase 8: MCP Decision Engine\" \"Skillsmith\"\n\n# Partial matching works\nnpx tsx scripts\u002Flinear-ops.ts link-initiative \"Phase 8\" \"Skillsmith\"\n```\n\n### unlink-initiative\n\nRemove a project from an initiative.\n\n```bash\nnpx tsx scripts\u002Flinear-ops.ts unlink-initiative \u003Cproject-name> \u003Cinitiative-name>\n```\n\n**Examples:**\n```bash\n# Remove incorrect link\nnpx tsx scripts\u002Flinear-ops.ts unlink-initiative \"Phase 8\" \"Linear Skill\"\n\n# Clean up test links\nnpx tsx scripts\u002Flinear-ops.ts unlink-initiative \"Test Project\" \"Q1 Goals\"\n```\n\n**Error Handling:**\n- Returns error if project is not linked to the specified initiative\n- Returns error if project or initiative not found\n\n### Complete Project Lifecycle Example\n\n```bash\n# 1. Create project linked to initiative\nnpx tsx scripts\u002Flinear-ops.ts create-project \"Phase 11: New Feature\" \"Skillsmith\"\n\n# 2. Set state to planned\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase 11\" planned\n\n# 3. Create issues in the project\nnpx tsx scripts\u002Flinear-ops.ts create-issue \"Phase 11\" \"Parent task\" \"Description\"\nnpx tsx scripts\u002Flinear-ops.ts create-sub-issue SMI-XXX \"Sub-task 1\" \"Details\"\n\n# 4. Start work - update to in-progress\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase 11\" in-progress\n\n# 5. Mark issues done\nnpx tsx scripts\u002Flinear-ops.ts status Done SMI-XXX SMI-YYY\n\n# 6. Complete project\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase 11\" completed\n\n# 7. (Optional) Link to additional initiative\nnpx tsx scripts\u002Flinear-ops.ts link-initiative \"Phase 11\" \"Q2 Goals\"\n```\n\n---\n\n## Tool Selection\n\nChoose the right tool for the task:\n\n1. **MCP tools (Official Server)** - **PREFERRED** for most operations when using `mcp.linear.app`\n2. **Helper Scripts \u002F GraphQL API** - Use for bulk operations or when MCP unavailable\n3. **SDK scripts** - Use for complex operations (loops, bulk updates, conditional logic, data transformations)\n\n### MCP Server Selection (CRITICAL)\n\n**Always use the official Linear MCP server** at `mcp.linear.app`. Configure in your MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"linear\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-remote\", \"https:\u002F\u002Fmcp.linear.app\u002Fsse\"],\n      \"env\": { \"LINEAR_API_KEY\": \"your_api_key\" }\n    }\n  }\n}\n```\n\n> **WARNING**: Do NOT use deprecated community servers (`linear-mcp-server` npm package, `jerhadf\u002Flinear-mcp-server`). They have critical bugs including a schema mismatch where `status` parameter fails because it's passed directly as `stateId` (requires UUID, not name).\n\n### MCP Reliability Matrix (Official Server)\n\nThe **official Linear MCP server** (`mcp.linear.app`) is significantly more reliable than community alternatives:\n\n| Operation | MCP Tool | Reliability | Notes |\n|-----------|----------|-------------|-------|\n| Create issue | `create_issue` | ✅ High | Full support |\n| **Update issue status** | `update_issue` | ✅ **Works with names!** | Use `state: \"Done\"` directly |\n| List issues | `list_issues` | ✅ High | Supports filters |\n| Search issues | `list_issues` with `query` | ✅ High | Use query parameter |\n| Get user issues | `list_issues` with `assignee: \"me\"` | ✅ High | Reliable |\n| Add comment | `create_comment` | ✅ High | Works with issue IDs |\n\n**Key Improvement**: The official server accepts human-readable state names (e.g., `state: \"Done\"`, `state: \"In Progress\"`) and resolves them to UUIDs internally. No need for manual UUID lookups!\n\n### Quick Status Update\n\n**With the official MCP server**, you can now update status directly using human-readable names:\n\n```\n# Via MCP (official server) - NOW WORKS!\nupdate_issue with id=\"issue-uuid\", state=\"Done\"\nupdate_issue with id=\"issue-uuid\", state=\"In Progress\"\n```\n\n**Alternative: API wrapper** (for bulk operations or when MCP unavailable):\n\n```bash\n# Update single issue (use issue identifier like PROJ-123)\nnode ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Flinear-api.mjs update-status --issue \u003CTEAM>-123 --status Done\n\n# Available states: Backlog, Todo, In Progress, In Review, Done, Canceled\n```\n\n### Linear API Wrapper (scripts\u002Flinear-api.mjs)\n\nA complete API wrapper with proper JSON escaping and error handling:\n\n```bash\n# Create issue (replace \u003CTEAM> with your team key, e.g., ENG, PROJ)\nnode ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Flinear-api.mjs create-issue \\\n  --team \u003CTEAM> --title \"New feature\" --description \"Details here\" --priority 2\n\n# Update status (replace \u003CTEAM>-123 with your issue identifier)\nnode ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Flinear-api.mjs update-status \\\n  --issue \u003CTEAM>-123 --status done\n\n# Add comment\nnode ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Flinear-api.mjs add-comment \\\n  --issue \u003CTEAM>-123 --body \"Fixed in PR #25\"\n\n# Add project update\nnode ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Flinear-api.mjs add-project-update \\\n  --project \u003CPROJECT_UUID> --body \"## Status Update\\n\\nProgress details...\" --health onTrack\n\n# List issues\nnode ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Flinear-api.mjs list-issues \\\n  --team \u003CTEAM> --status \"In Progress\" --limit 20\n\n# List labels\nnode ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Flinear-api.mjs list-labels --team \u003CTEAM>\n\n# Help\nnode ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Flinear-api.mjs help\n```\n\n**Benefits over MCP:**\n- Proper JSON escaping (no shell parsing issues)\n- Reliable status updates (uses correct GraphQL types)\n- Batch-friendly for scripting\n- Can be imported as ES module for programmatic use\n\n**Why not MCP?** The `linear_update_issue` MCP tool frequently fails with schema validation errors and timeouts. The helper script uses direct GraphQL which is 100% reliable.\n\n### Quick Comment by Issue Number\n\nAdd comments without needing to look up UUIDs:\n\n```bash\n# Simple comment (use the issue number, e.g., 123 for PROJ-123)\nnode scripts\u002Flinear-helpers.mjs add-comment 123 \"Fixed in PR #25\"\n\n# Multi-line comment (use quotes)\nnode scripts\u002Flinear-helpers.mjs add-comment 123 \"## Resolved\n\nImplementation complete. All tests passing.\"\n```\n\n**Pattern**: Use MCP for issue creation, helper scripts for status updates and comments, and direct GraphQL for searches and complex queries.\n\n### Historical: Why Community MCP Servers Failed\n\n> **Note**: These issues are **resolved** with the official Linear MCP server at `mcp.linear.app`. This section is preserved for reference when troubleshooting deprecated community server configurations.\n\n#### Issue 1: Status Update Schema Mismatch (FIXED in Official Server)\n\nThe deprecated `linear-mcp-server` (npm) had a critical bug:\n\n| Community Server | Official Server |\n|------------------|-----------------|\n| `status: \"Done\"` → passed as `stateId` (UUID required) → ❌ Fails | `state: \"Done\"` → resolved internally → ✅ Works |\n\n**The official server correctly resolves state names to UUIDs internally.**\n\n#### Issue 2: SSE Connection Timeouts\n\nBoth servers can experience SSE connection drops after extended idle periods. The official server has improved keep-alive handling, but for very long operations, helper scripts remain a reliable fallback.\n\n**Best Practice**: Use the official MCP server for most operations. Fall back to helper scripts for bulk operations or timeout-prone scenarios.\n\n## Critical Requirements\n\n### ⚠️ MANDATORY: Issues → Projects → Initiatives\n\n**Every issue MUST be attached to a project. Every project MUST be linked to an initiative.**\n\nOrphaned issues and projects are invisible in roadmap views and break tracking.\n\n| Entity | Must Link To | Consequence if Missing |\n|--------|--------------|------------------------|\n| Issue | Project | Not visible in project board |\n| Project | Initiative | Not visible in initiative roadmap |\n\n**Anti-Pattern (NEVER DO):**\n```bash\n# ❌ Creating orphaned issues\nmcp__linear__linear_create_issue with title=\"My task\"\n# Issue exists but is not part of any project!\n```\n\n**Correct Pattern (ALWAYS DO):**\n```bash\n# ✅ Create issue AND add to project in same workflow\nmcp__linear__linear_create_issue with title=\"My task\" ...\nnode scripts\u002Flinear-helpers.mjs add-issues-to-project \u003CprojectId> \u003CissueNumber>\n\n# ✅ Create project AND link to initiative\nlinear projects create --name \"Phase N: Name\"\nnode scripts\u002Flinear-helpers.mjs link-project \u003CprojectId>\n```\n\n### Helper Script: Update Issue Status\n\n**⚡ PRIMARY METHOD** - Always use the helper script for status updates (API-first for reliability):\n\n```bash\n# Update multiple issues to Done (use issue numbers without prefix)\nnode scripts\u002Flinear-helpers.mjs update-status Done 101 102 103\n\n# Available states: Backlog, Todo, In Progress, In Review, Done, Canceled\n```\n\n**Never use MCP's `linear_update_issue`** - it fails ~50% of the time with schema validation errors. The helper script uses direct GraphQL API calls which are 100% reliable.\n\n---\n\n## Conventions\n\n### Issue Status\n\nWhen creating issues, set the appropriate status based on assignment:\n\n- **Assigned to me** (`assignee: \"me\"`): Set `state: \"Todo\"`\n- **Unassigned**: Set `state: \"Backlog\"`\n\nExample:\n```typescript\n\u002F\u002F Issue for myself (replace \"TEAM\" with your team key)\nawait linear.create_issue({\n  team: \"TEAM\",\n  title: \"Fix authentication bug\",\n  assignee: \"me\",\n  state: \"Todo\"\n})\n\n\u002F\u002F Unassigned issue\nawait linear.create_issue({\n  team: \"TEAM\",\n  title: \"Research API performance\",\n  state: \"Backlog\"\n})\n```\n\n### Querying Issues\n\nUse `assignee: \"me\"` to filter issues assigned to the authenticated user:\n\n```typescript\n\u002F\u002F My issues\nawait linear.list_issues({ assignee: \"me\" })\n\n\u002F\u002F Team backlog (replace \"TEAM\" with your team key)\nawait linear.list_issues({ team: \"TEAM\", state: \"Backlog\" })\n```\n\n### Labels\n\nThis skill uses a **domain-based label taxonomy** for consistent categorization. See [docs\u002Flabels.md](docs\u002Flabels.md) for the complete guide.\n\n**Key rules:**\n- Always apply exactly ONE Type label: `feature`, `bug`, `refactor`, `chore`, or `spike`\n- Apply 1-2 Domain labels for agent routing: `security`, `backend`, `frontend`, etc.\n- Add Scope labels only when applicable: `blocked`, `breaking-change`, `tech-debt`, etc.\n\n**Taxonomy commands:**\n```bash\n# Show full taxonomy\nnpx tsx scripts\u002Flinear-ops.ts labels taxonomy\n\n# Validate labels before creating issues\nnpx tsx scripts\u002Flinear-ops.ts labels validate \"feature,security,breaking-change\"\n\n# Suggest labels based on issue title\nnpx tsx scripts\u002Flinear-ops.ts labels suggest \"Fix XSS vulnerability in login form\"\n\n# Show agent recommendations for labels\nnpx tsx scripts\u002Flinear-ops.ts labels agents \"security,performance\"\n```\n\nYou can use label names directly in `create_issue` and `update_issue` - no need to look up IDs:\n\n```typescript\nawait linear.create_issue({\n  team: \"TEAM\",\n  title: \"Update documentation\",\n  labels: [\"documentation\", \"chore\"]  \u002F\u002F Use taxonomy labels\n})\n```\n\n## SDK Automation Scripts\n\n**Use only when MCP tools are insufficient.** For complex operations involving loops, mapping, or bulk updates, write TypeScript scripts using `@linear\u002Fsdk`. See `sdk.md` for:\n\n- Complete script patterns and templates\n- Common automation examples (bulk updates, filtering, reporting)\n- Tool selection criteria\n\nScripts provide full type hints and are easier to debug than raw GraphQL for multi-step operations.\n\n## GraphQL API\n\n**Fallback only.** Use when operations aren't supported by MCP or SDK. See `api.md` for documentation on using the Linear GraphQL API directly.\n\n### Timeout Handling Patterns\n\nWhen operations take longer than expected, use these patterns to maintain reliability:\n\n**1. Progress Notifications**\nFor bulk operations, notify the user of progress:\n\n```javascript\nconst issues = ['PROJ-101', 'PROJ-102', 'PROJ-103'];\nfor (let i = 0; i \u003C issues.length; i++) {\n  console.log(`Processing ${i + 1}\u002F${issues.length}: ${issues[i]}`);\n  \u002F\u002F ... operation\n}\n```\n\n**2. Chunked Batch Operations**\nBreak large batches into smaller chunks to avoid timeouts:\n\n```javascript\nconst BATCH_SIZE = 10;\nconst DELAY_MS = 150; \u002F\u002F Avoid rate limiting\n\nfor (let i = 0; i \u003C issues.length; i += BATCH_SIZE) {\n  const batch = issues.slice(i, i + BATCH_SIZE);\n  console.log(`Batch ${Math.floor(i \u002F BATCH_SIZE) + 1}: Processing ${batch.length} issues`);\n\n  for (const issue of batch) {\n    await processIssue(issue);\n    await new Promise(r => setTimeout(r, DELAY_MS));\n  }\n}\n```\n\n**3. Fallback on Timeout**\nDetect timeouts and fall back to GraphQL:\n\n```javascript\ntry {\n  \u002F\u002F Try MCP first (faster when it works)\n  await mcp__linear__linear_search_issues({ query: \"keyword\" });\n} catch (error) {\n  if (error.message.includes('timeout') || error.message.includes('ETIMEDOUT')) {\n    console.log('MCP timed out, falling back to GraphQL...');\n    \u002F\u002F Use GraphQL workaround (see below)\n  }\n}\n```\n\n**4. Bulk Sync Script**\nUse `scripts\u002Fsync.ts` for reliable bulk state updates:\n\n```bash\n# Update multiple issues to Done state (replace PROJ with your team prefix)\nLINEAR_API_KEY=lin_api_xxx npx tsx scripts\u002Fsync.ts --issues PROJ-101,PROJ-102,PROJ-103 --state Done\n\n# Preview changes without applying\nLINEAR_API_KEY=lin_api_xxx npx tsx scripts\u002Fsync.ts --issues PROJ-101,PROJ-102 --state Done --dry-run\n\n# Add comment with state change\nLINEAR_API_KEY=lin_api_xxx npx tsx scripts\u002Fsync.ts --issues PROJ-101 --state Done --comment \"Completed in PR #42\"\n```\n\n### MCP Timeout Workarounds\n\nWhen MCP times out or fails, use these direct GraphQL patterns:\n\n#### ⚠️ Shell Script Compatibility\n\n**IMPORTANT**: When writing inline Node.js scripts in bash, avoid JavaScript features that confuse shell parsing:\n\n| Feature | Problem | Solution |\n|---------|---------|----------|\n| Optional chaining `?.` | Shell sees `?` as glob | Use explicit null checks |\n| Nullish coalescing `??` | Double `?` confuses parser | Use ternary `? :` |\n| Heredocs with `${}` | Shell interpolation | Use `\u003C\u003C 'EOF'` (quoted) |\n\n**Anti-Pattern (breaks in bash):**\n```javascript\n\u002F\u002F ❌ Optional chaining breaks shell parsing\nconst name = project.status?.name;\n```\n\n**Correct Pattern:**\n```javascript\n\u002F\u002F ✅ Explicit null check works everywhere\nconst name = project.status ? project.status.name : 'No status';\n```\n\n**Heredoc Pattern:**\n```bash\n# ✅ Use quoted EOF to prevent shell interpolation\nnode --input-type=module \u003C\u003C 'ENDSCRIPT'\nconst value = obj.prop ? obj.prop.nested : 'default';\nENDSCRIPT\n```\n\n#### Search Issues (when MCP times out)\n\n```javascript\n\u002F\u002F Inline GraphQL via node --experimental-fetch\nnode --experimental-fetch -e \"\nasync function searchIssues() {\n  const query = \\`\n    query {\n      issues(filter: {\n        team: { key: { eq: \\\"TEAM\\\" } }\n        state: { type: { nin: [\\\"completed\\\", \\\"canceled\\\"] } }\n      }, first: 25) {\n        nodes {\n          id identifier title state { name } priority\n        }\n      }\n    }\n  \\`;\n\n  const res = await fetch('https:\u002F\u002Fapi.linear.app\u002Fgraphql', {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application\u002Fjson',\n      'Authorization': process.env.LINEAR_API_KEY\n    },\n    body: JSON.stringify({ query })\n  });\n\n  const data = await res.json();\n  data.data.issues.nodes.forEach(i => {\n    console.log(\\`\\${i.identifier}: \\${i.title} [\\${i.state.name}]\\`);\n  });\n}\nsearchIssues();\n\"\n```\n\n#### Update Issue Status (when MCP is unreliable)\n\n```javascript\n\u002F\u002F First get the workflow state ID for \"Done\"\nconst stateQuery = \\`\n  query {\n    workflowStates(filter: { team: { key: { eq: \\\"TEAM\\\" } }, name: { eq: \\\"Done\\\" } }) {\n      nodes { id name }\n    }\n  }\n\\`;\n\n\u002F\u002F Then update the issue\nconst mutation = \\`\n  mutation {\n    issueUpdate(id: \"\\${issueUuid}\", input: { stateId: \"\\${doneStateId}\" }) {\n      success\n      issue { identifier state { name } }\n    }\n  }\n\\`;\n```\n\n#### Add Comment (MCP fails with UUIDs)\n\n```javascript\n\u002F\u002F Get issue UUID from identifier\nconst issueQuery = \\`\n  query {\n    issues(filter: { number: { in: [123, 124, 125] } }) {\n      nodes { id identifier }\n    }\n  }\n\\`;\n\n\u002F\u002F Add comment using UUID\nconst mutation = \\`\n  mutation {\n    commentCreate(input: {\n      issueId: \"\\${issueUuid}\",\n      body: \"Implementation complete. See PR #42.\"\n    }) { success }\n  }\n\\`;\n```\n\n**Pro Tip**: Store frequently-used IDs (team UUID, common state UUIDs) in your project's CLAUDE.md to avoid repeated lookups.\n\n### Ad-Hoc Queries\n\nUse `scripts\u002Fquery.ts` to execute GraphQL queries:\n\n```bash\nLINEAR_API_KEY=lin_api_xxx node scripts\u002Fquery.ts \"query { viewer { id name } }\"\n```\n\nIf `LINEAR_API_KEY` is not provided to the Claude process, inform the user that GraphQL queries cannot be executed without an API key.\n\n## Projects & Initiatives\n\n### MANDATORY: Project Content & Updates\n\n**Every project operation MUST include these steps. Never skip them.**\n\nWhen **creating** a project:\n1. ✅ Set `content` (full markdown for main panel)\n2. ✅ Set `description` (255 char summary for lists)\n3. ✅ Link to parent initiative\n4. ✅ Add resource links (docs, repos)\n5. ✅ Create initial project update with scope\n\nWhen **updating** project status:\n1. ✅ Update `statusId` to new status\n2. ✅ Create project update documenting the change\n3. ✅ Include progress metrics (X\u002FY issues complete)\n\nWhen **completing** work:\n1. ✅ Update issue statuses to Done\n2. ✅ Update project status to match\n3. ✅ Create final project update with summary\n\n**Example: Mandatory Project Update**\n\n```javascript\n\u002F\u002F ALWAYS create an update when project status changes\nnode --experimental-fetch -e \"\nconst PROJECT_ID = '\u003Cuuid>';\n\nconst update = \\`## Status: In Progress ?\n\n**Date:** $(date '+%Y-%m-%d')\n\n### Completed\n- ✅ Task 1 done\n- ✅ Task 2 done\n\n### In Progress\n- ? Task 3 in progress\n\n### Up Next\n- ? Task 4 pending\n\\`;\n\nconst mutation = \\`mutation {\n  projectUpdateCreate(input: {\n    projectId: \\\\\\\"\\${PROJECT_ID}\\\\\\\",\n    body: \\${JSON.stringify(update)},\n    health: onTrack\n  }) { success projectUpdate { url } }\n}\\`;\n\nfetch('https:\u002F\u002Fapi.linear.app\u002Fgraphql', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application\u002Fjson', 'Authorization': process.env.LINEAR_API_KEY },\n  body: JSON.stringify({ query: mutation })\n}).then(r => r.json()).then(d => console.log('Update created:', d.data?.projectUpdateCreate?.projectUpdate?.url));\n\"\n```\n\n---\n\n### Content vs Description (CRITICAL)\n\nLinear has **two text fields** - using the wrong one causes blank displays:\n\n| Field | Limit | Shows In | Use For |\n|-------|-------|----------|---------|\n| `description` | 255 chars | List views, tooltips | Short summary |\n| `content` | Unlimited | **Main detail panel** | Full markdown documentation |\n\n**Always set BOTH when creating\u002Fupdating projects:**\n\n```graphql\n# Content is what users see in the main panel!\nmutation {\n  projectUpdate(id: \"\u003Cuuid>\", input: {\n    content: \"# Project Title\\n\\nFull markdown description...\",\n    description: \"Short 255 char summary for list views\"\n  }) { success }\n}\n```\n\n### Discovery Before Creation (MANDATORY)\n\n**ALWAYS check Linear before creating ANY project or issue.** Skipping this step causes duplicate projects and wasted effort.\n\n```bash\n# Check for existing projects\nlinear projects list | grep -i \"phase\\|\u003Cfeature-name>\"\n\n# Check for existing issues (MCP may timeout - use CLI as fallback)\nlinear issues list --filter \"title:Phase N\"\n# Or: mcp__linear__linear_search_issues with query=\"Phase N feature\"\n```\n\n**Checklist before ANY create operation:**\n\n| Check | Command | Action if Found |\n|-------|---------|-----------------|\n| Project exists? | `linear projects list \\| grep -i \"name\"` | Use existing UUID, skip creation |\n| Issues exist? | `linear issues list --filter \"title:keyword\"` | Review existing, update if needed |\n| Initiative linked? | Check project in Linear UI | Skip link-project step |\n\n**NEVER skip discovery. Duplicate projects waste time and create confusion.**\n\n---\n\n### Codebase Verification Before Work (MANDATORY)\n\n**ALWAYS verify codebase state before accepting Linear issue scope at face value.**\n\nIssue descriptions may be **outdated** or **speculative** — written before code exploration. This is especially common when:\n- Issues were created during planning, not after code review\n- The codebase evolved since the issue was created\n- API endpoints or features were implemented but not documented in Linear\n\n**Key Lesson**: Issues describing \"missing\" APIs or features may already be implemented.\n\n```bash\n# Before starting any API\u002Ffeature implementation issue:\n\n# 1. Search for existing implementations\ngrep -r \"apiEndpoint\\|functionName\" src\u002F\n\n# 2. Check if files already exist\nls src\u002Fpages\u002Fapi\u002Fadmin\u002Fmembers\u002F  # If issue says \"implement members API\"\n\n# 3. Read existing code\ncat src\u002Fpages\u002Fapi\u002Fadmin\u002Fmembers\u002Findex.ts  # May already be complete!\n\n# 4. Run tests to see what's actually failing\nnpx playwright test tests\u002Fe2e\u002Fjourneys\u002Fadmin\u002F\n```\n\n**Checklist before accepting issue scope:**\n\n| Check | Method | If Found |\n|-------|--------|----------|\n| API exists? | `ls src\u002Fpages\u002Fapi\u002F**\u002F*.ts` | Update issue scope to \"verify\u002Ftest\" |\n| Feature implemented? | `grep -r \"featureName\" src\u002F` | Mark implementation subtasks as done |\n| Tests passing? | Run test suite | Focus on fixing failures, not reimplementing |\n| Only tests skipped? | Check for `test.skip` | Real work is un-skipping + fixing assertions |\n\n**Example: Scope Discovery**\n\nIssue says: \"Implement \u002Fapi\u002Fadmin\u002Fmembers CRUD endpoints\"\n\n**BEFORE starting:**\n```bash\n# Check if files exist\nls src\u002Fpages\u002Fapi\u002Fadmin\u002Fmembers\u002F\n# Output: index.ts  [id].ts  ← Files exist!\n\n# Read the implementation\ncat src\u002Fpages\u002Fapi\u002Fadmin\u002Fmembers\u002Findex.ts | head -50\n# Output: Full implementation with GET, POST, auth checks\n\n# Check why tests fail\ngrep -r \"test.describe.skip\" tests\u002Fe2e\u002Fjourneys\u002Fadmin\u002F\n# Output: member-management.spec.ts uses test.describe.skip\n```\n\n**CORRECTED scope**: \"Un-skip E2E tests and fix any assertion failures\" (not \"implement API\")\n\n**Update Linear immediately when scope changes:**\n```bash\nnode scripts\u002Flinear-helpers.mjs add-comment 123 \"## Scope Update\n\n**Discovery:** API endpoints are ALREADY COMPLETE!\n\n### Actual Remaining Work\n1. Un-skip journey tests\n2. Fix any test assertion failures\n3. Verify tests pass\"\n```\n\n**NEVER assume issue descriptions are accurate. Verify codebase state first.**\n\n---\n\n## Sub-Issue Management (Parent-Child Relationships)\n\nLinear supports hierarchical issue organization through parent-child relationships. Sub-issues (children) appear nested under their parent issue in the UI and inherit certain properties.\n\n### When to Use Sub-Issues\n\n| Scenario | Use Sub-Issues | Example |\n|----------|----------------|---------|\n| Feature breakdown | ✅ Yes | ENG-100 \"Auth System\" → ENG-101 \"TDD tests\", ENG-102 \"E2E tests\" |\n| Related but independent | ❌ No | Two bugs in different areas (use labels instead) |\n| Sequential phases | ✅ Yes | ENG-200 \"Phase 1\" → ENG-201 \"Setup\", ENG-202 \"Implementation\" |\n| Tracking subtasks | ✅ Yes | Break down a large issue into trackable pieces |\n\n### Commands\n\n```bash\n# Create a sub-issue (child) under a parent issue\n# Inherits team and project from parent automatically\nnpx tsx scripts\u002Flinear-ops.ts create-sub-issue \u003Cparent-issue> \u003Ctitle> [description] [--priority 1-4] [--labels label1,label2]\n\n# Set existing issues as children of a parent\nnpx tsx scripts\u002Flinear-ops.ts set-parent \u003Cparent-issue> \u003Cchild-issues...>\n\n# List all sub-issues of a parent\nnpx tsx scripts\u002Flinear-ops.ts list-sub-issues \u003Cparent-issue>\n```\n\n### Examples\n\n```bash\n# Create a sub-issue for unit tests under a parent feature issue\nnpx tsx scripts\u002Flinear-ops.ts create-sub-issue ENG-100 \"Add unit tests\" \"Unit tests for new feature\" --priority 2 --labels testing\n\n# Link existing issues as children of a parent\nnpx tsx scripts\u002Flinear-ops.ts set-parent ENG-100 ENG-101 ENG-102\n\n# List all sub-issues of a parent\nnpx tsx scripts\u002Flinear-ops.ts list-sub-issues ENG-100\n```\n\n### Notes\n\n- **Inheritance**: Sub-issues automatically inherit the team from the parent\n- **Project linking**: If the parent is in a project, sub-issues can also be added\n- **Status independence**: Each issue maintains its own status (completing a sub-issue doesn't auto-complete the parent)\n- **UI display**: Sub-issues appear indented under their parent in list views\n\n---\n\n### Linking Projects to Initiatives\n\n**Use `initiativeToProjectCreate` to link an existing project to an initiative:**\n\n```graphql\nmutation {\n  initiativeToProjectCreate(input: {\n    initiativeId: \"\u003Cinitiative-uuid>\",\n    projectId: \"\u003Cproject-uuid>\"\n  }) {\n    success\n    initiativeToProject { id }\n  }\n}\n```\n\n**Example using query.ts:**\n\n```bash\nnpx tsx ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Fquery.ts 'mutation {\n  initiativeToProjectCreate(input: {\n    initiativeId: \"\u003Cinitiative-uuid>\",\n    projectId: \"\u003Cproject-uuid>\"\n  }) {\n    success\n  }\n}'\n```\n\n**Note:** This is different from setting `initiativeId` at project creation time. Use this mutation when:\n- A project was created without an initiative link\n- You need to add a project to an additional initiative\n- Reorganizing projects between initiatives\n\n---\n\n### New Phase Project Pattern\n\n**Step 0: Run Discovery Checks (see above)**\n\nWhen creating a new phase, follow this complete workflow:\n\n```bash\n# 0. DISCOVERY - Check for existing project\u002Fissues first!\nlinear projects list | grep -i \"phase N\"\n\n# 1. Create project via CLI (ONLY if Step 0 found nothing)\nlinear projects create --name \"Phase N: Name\" --description \"Short summary\"\n\n# 2. Link to initiative (use initiativeToProjectCreate mutation - see above)\nnpx tsx scripts\u002Fquery.ts 'mutation { initiativeToProjectCreate(input: { initiativeId: \"\u003Cuuid>\", projectId: \"\u003Cuuid>\" }) { success } }'\n\n# 3. Set content (main UI panel)\n# Use GraphQL to set full markdown content\n\n# 4. Add resource link to implementation doc\n# Use entityExternalLinkCreate mutation\n\n# 5. Create milestone for Definition of Done\n# Use projectMilestoneCreate mutation\n\n# 6. Create issues via MCP (check for existing first!)\n# 7. Add issues to project\n```\n\n---\n\n## ⚠️ MANDATORY: Project Creation Checklist\n\n> **CRITICAL**: Every script that creates projects MUST follow this checklist.\n> Skipping steps causes recurring issues with orphaned projects and missing links.\n\n### Required Steps\n\n| # | Step | How | Verify |\n|---|------|-----|--------|\n| 1 | **Link to initiative** | `initiativeToProjectCreate` mutation | Check initiative.projects |\n| 2 | **Set description** | `description` field (255 char limit) | View in sidebar |\n| 3 | **Set content** | `content` field via `projectUpdate` | View main panel |\n| 4 | **Add resource links** | `entityExternalLinkCreate` mutation | Check Resources section |\n| 5 | **Create milestones** | `projectMilestoneCreate` mutation | Check Milestones tab |\n| 6 | **Ensure labels exist** | Use `lib\u002Flabels.ts` utilities | Query labels before\u002Fafter |\n| 7 | **Create issues with labels** | Include `labelIds` in `createIssue` | View issue labels |\n| 8 | **Verify issue count** | Compare expected vs actual | Log counts |\n| 9 | **Run verification** | Use `lib\u002Fverify.ts` | Check output |\n| 10 | **Report failures** | Log all errors, don't fail silently | Review logs |\n\n### Using Shared Utilities\n\n**Always use the lib\u002F utilities** to avoid common mistakes:\n\n```typescript\nimport {\n  linkProjectToInitiative,\n  ensureLabelsExist,\n  verifyProjectCreation,\n  createProject,\n  createProjectWithDefaults,\n  DEFAULT_INITIATIVE_ID\n} from '.\u002Flib'\n\n\u002F\u002F Option 1: Full template with explicit initiative\nconst result = await createProject(teamId, {\n  name: 'My Project Phase X: Name',\n  shortDescription: 'Short 255 char description',\n  content: '# Full markdown content...',\n  state: 'planned',\n  initiative: '\u003Cyour-initiative-uuid>',\n  issues: [\n    { title: 'Issue', description: 'Desc', labels: ['label1'] }\n  ]\n})\n\n\u002F\u002F Option 2: Use environment variable for initiative\n\u002F\u002F Requires: LINEAR_DEFAULT_INITIATIVE_ID=\u003Cuuid>\nconst result2 = await createProjectWithDefaults({\n  name: 'My Project Phase X: Name',\n  shortDescription: 'Short description',\n  content: '# Full content...',\n  state: 'planned',\n  issues: []\n})\n\n\u002F\u002F Option 3: Manual with utilities\nconst linkResult = await linkProjectToInitiative(projectId, initiativeId)\nconst labelResult = await ensureLabelsExist(teamId, ['label1', 'label2'])\nconst verification = await verifyProjectCreation('Phase X', expectedCount, undefined, initiativeId)\n```\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `LINEAR_API_KEY` | Yes | Your Linear API key |\n| `LINEAR_DEFAULT_INITIATIVE_ID` | No | Default initiative for `createProjectWithDefaults()` |\n\n### Common Mistakes\n\n| Mistake | Symptom | Fix |\n|---------|---------|-----|\n| Using `initiativeIds` on `projectUpdate` | Silent failure | Use `initiativeToProjectCreate` mutation |\n| Long description | Truncated in UI | Use `content` for full text, `description` for summary |\n| Case-sensitive label lookup | Labels not applied | Use case-insensitive map (`name.toLowerCase()`) |\n| Silent failures | Missing issues\u002Flabels | Always check result, log errors |\n| No post-verification | Issues discovered later | Run `lib\u002Fverify.ts` after creation |\n\n### Resource Links\n\nAdd clickable links to projects\u002Finitiatives (shows in Resources section):\n\n```graphql\nmutation {\n  entityExternalLinkCreate(input: {\n    url: \"https:\u002F\u002Fgithub.com\u002Forg\u002Frepo\u002Fblob\u002Fmain\u002Fdocs\u002Fimplementation\u002Fphase-N.md\",\n    label: \"Implementation Doc\",\n    projectId: \"\u003Cproject-uuid>\"\n  }) { success }\n}\n```\n\n**Standard resource links for phases:**\n- `Implementation Doc` → docs\u002Fimplementation\u002Fphase-N-*.md\n- `Production Site` → deployment URL (for initiative)\n- `Repository` → GitHub repo link (for initiative)\n\n### Project Milestones (Definition of Done)\n\nTrack completion criteria with milestones:\n\n```graphql\nmutation {\n  projectMilestoneCreate(input: {\n    projectId: \"\u003Cuuid>\",\n    name: \"DoD: Testing\",\n    description: \"Unit tests, E2E tests, 100% coverage\"\n  }) { success }\n}\n```\n\n**Standard DoD milestones:**\n- `DoD: Core Feature` - Main functionality complete\n- `DoD: Testing` - All tests pass, coverage met\n- `DoD: Security` - Security requirements verified\n- `DoD: Accessibility` - A11y requirements met\n\n### Project Status (IMPORTANT)\n\n**Project status is NOT auto-updated when issues move.** You must explicitly update project status.\n\n#### Project Status vs Issue Status\n\n| Concept | Applies To | Field | Auto-Updates? |\n|---------|------------|-------|---------------|\n| **Issue Status** | Individual issues | `stateId` | Yes (via workflow) |\n| **Project Status** | Entire project | `statusId` | ❌ No - manual only |\n\n#### Status Types and UUIDs\n\nQuery your workspace's status UUIDs (workspace-specific):\n\n```graphql\nquery { projectStatuses { nodes { id name type } } }\n```\n\n**Standard Status Types:**\n\n| Status | Type | When to Use |\n|--------|------|-------------|\n| `Backlog` | `backlog` | Project created but not started |\n| `Planned` | `planned` | Project scheduled, issues created |\n| `In Progress` | `started` | **Issues actively being worked** |\n| `Completed` | `completed` | All issues done |\n| `Canceled` | `canceled` | Project abandoned |\n\n#### When to Update Project Status\n\nUpdate project status at these transition points:\n\n| Trigger | New Status | Check |\n|---------|------------|-------|\n| First issue moves to \"In Progress\" | `In Progress` | Any issue has `started` state |\n| All issues complete | `Completed` | No issues in backlog\u002Fprogress |\n| Work begins on phase | `In Progress` | Manual or first issue started |\n| Phase fully implemented | `Completed` | All tests pass, PR merged |\n\n#### Update Project Status\n\n```graphql\nmutation {\n  projectUpdate(id: \"\u003Cproject-uuid>\", input: {\n    statusId: \"\u003Cstatus-uuid>\"\n  }) {\n    success\n    project { name status { name } }\n  }\n}\n```\n\n#### Check Project Issue Progress\n\nBefore updating status, check issue states:\n\n```graphql\nquery {\n  project(id: \"\u003Cproject-uuid>\") {\n    name\n    status { name }\n    issues {\n      nodes {\n        identifier\n        state { name type }\n      }\n    }\n  }\n}\n```\n\n**Logic for auto-determining status:**\n- If ANY issue has `state.type = \"started\"` → Project is `In Progress`\n- If ALL issues have `state.type = \"completed\"` → Project is `Completed`\n- If NO issues started → Project is `Planned` or `Backlog`\n\n#### Helper: Update Project Status Script\n\n```javascript\n\u002F\u002F Check project issues and update status accordingly\nnode -e \"\nconst PROJECT_ID = '\u003Cproject-uuid>';\n\n\u002F\u002F Status UUIDs (query your workspace for these)\nconst STATUS = {\n  backlog: '1ed7da89-db44-4339-b0d7-ce37d8ff9604',\n  planned: '33ebbb84-53ea-4dd8-a8db-49a8b3b9c502',\n  inProgress: '71d18c8f-53de-4752-be37-a6d529cb9c97',\n  completed: '54294a72-010d-4ae7-9829-bed76232fb66'\n};\n\nasync function updateProjectStatus() {\n  \u002F\u002F Get project issues\n  const issueQuery = \\`query {\n    project(id: \\\"${PROJECT_ID}\\\") {\n      name\n      issues { nodes { state { type } } }\n    }\n  }\\`;\n\n  const res = await fetch('https:\u002F\u002Fapi.linear.app\u002Fgraphql', {\n    method: 'POST',\n    headers: { 'Content-Type': 'application\u002Fjson', 'Authorization': process.env.LINEAR_API_KEY },\n    body: JSON.stringify({ query: issueQuery })\n  });\n  const { data } = await res.json();\n\n  const issues = data.project.issues.nodes;\n  const states = issues.map(i => i.state.type);\n\n  \u002F\u002F Determine appropriate status\n  let newStatus;\n  if (states.every(s => s === 'completed')) {\n    newStatus = STATUS.completed;\n  } else if (states.some(s => s === 'started')) {\n    newStatus = STATUS.inProgress;\n  } else {\n    newStatus = STATUS.planned;\n  }\n\n  \u002F\u002F Update project\n  const mutation = \\`mutation {\n    projectUpdate(id: \\\"${PROJECT_ID}\\\", input: { statusId: \\\"${newStatus}\\\" }) {\n      success\n      project { name status { name } }\n    }\n  }\\`;\n\n  const updateRes = await fetch('https:\u002F\u002Fapi.linear.app\u002Fgraphql', {\n    method: 'POST',\n    headers: { 'Content-Type': 'application\u002Fjson', 'Authorization': process.env.LINEAR_API_KEY },\n    body: JSON.stringify({ query: mutation })\n  });\n  const result = await updateRes.json();\n  console.log('Updated:', result.data.projectUpdate.project);\n}\n\nupdateProjectStatus();\n\"\n```\n\n### Project Updates (Status Reports)\n\nPost status updates to a project's Updates tab. These are visible at `\u002Fproject\u002F{slug}\u002Fupdates`.\n\n#### Create Project Update\n\n```graphql\nmutation {\n  projectUpdateCreate(input: {\n    projectId: \"\u003Cproject-uuid>\",\n    body: \"## Status Update\\n\\nMarkdown content here...\",\n    health: onTrack\n  }) {\n    success\n    projectUpdate {\n      id\n      url\n      createdAt\n    }\n  }\n}\n```\n\n**Health Options:**\n- `onTrack` - ? Project proceeding as planned\n- `atRisk` - ? Issues that may cause delays\n- `offTrack` - ? Project is behind schedule\n\n#### Example: Post Progress Update\n\n```javascript\nnode -e \"\nconst projectId = '\u003Cproject-uuid>';\n\nconst updateBody = \\`## Status: In Progress ?\n\n**Swarm execution started** — agents actively implementing features.\n\n### Progress\n- **32% complete** (9\u002F28 issues done)\n- Project status updated to **In Progress**\n\n### Completed\n- ✅ Foundation setup\n- ✅ Core configuration\n\n### In Progress\n- ? Main feature implementation\n- ? UI components\n\n### Up Next\n- Testing suite\n- Documentation\n\\`;\n\nconst mutation = \\`mutation {\n  projectUpdateCreate(input: {\n    projectId: \\\\\\\"\\${projectId}\\\\\\\",\n    body: \\${JSON.stringify(updateBody)},\n    health: onTrack\n  }) {\n    success\n    projectUpdate { id }\n  }\n}\\`;\n\nfetch('https:\u002F\u002Fapi.linear.app\u002Fgraphql', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application\u002Fjson', 'Authorization': process.env.LINEAR_API_KEY },\n  body: JSON.stringify({ query: mutation })\n}).then(r => r.json()).then(d => console.log(JSON.stringify(d, null, 2)));\n\"\n```\n\n#### When to Post Updates\n\n| Trigger | Health | Content |\n|---------|--------|---------|\n| Work starts (swarm launched) | `onTrack` | Progress %, what's in progress |\n| Milestone reached | `onTrack` | Completed items, next steps |\n| Blockers encountered | `atRisk` | Issue description, mitigation plan |\n| Deadline at risk | `offTrack` | Root cause, revised timeline |\n| Phase complete | `onTrack` | Summary, metrics, lessons learned |\n\n---\n\n## Sync Patterns (Bulk Operations)\n\nFor bulk synchronization of code changes to Linear, see `sync.md`.\n\n### Quick Sync Commands\n\n```bash\n# Bulk update issues to Done (replace PROJ with your team prefix)\nnpx ts-node scripts\u002Fsync.ts --issues PROJ-101,PROJ-102,PROJ-103 --state Done\n\n# Update project status\nnpx ts-node scripts\u002Fsync.ts --project \"My Project\" --state completed\n\n# Verify sync completed\nnpx ts-node scripts\u002Fsync.ts --verify PROJ-101,PROJ-102 --expected-state Done\n```\n\n### Agent-Spawned Sync\n\nSpawn a parallel agent for autonomous sync:\n\n```javascript\nTask({\n  description: \"Sync project issues to Linear\",\n  prompt: \"Update PROJ-101,102,103 to Done. Then update project 'My Project' to completed.\",\n  subagent_type: \"general-purpose\"\n})\n```\n\n### Hook-Triggered Sync\n\nAuto-suggest sync after code edits. Add to `.claude\u002Fsettings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"PostToolUse\": [{\n      \"matcher\": \"Write|Edit\",\n      \"hooks\": [{\n        \"type\": \"command\",\n        \"command\": \"bash ~\u002F.claude\u002Fskills\u002Flinear\u002Fhooks\u002Fpost-edit.sh\"\n      }]\n    }]\n  }\n}\n```\n\nSee `sync.md` for complete patterns including AgentDB integration and swarm coordination.\n\n---\n\n## Reference\n\n- Linear MCP: https:\u002F\u002Flinear.app\u002Fdocs\u002Fmcp.md\n- GraphQL API: See `api.md`\n- SDK Automation: See `sdk.md`\n- Bulk Sync: See `sync.md`\n",{"name":5,"description":7,"allowed-tools":45},[46,47,32],"mcp__linear","WebFetch(domain:linear.app)","main","7bf2279c8a65758319526a721d5c4b75683aec9c","skills\u002Flinear-claude-skill",3,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections","https:\u002F\u002Fgithub.com\u002Fboisenoise","2026-11-14 14:18:11",{"source":8,"skillName":5,"commands":56,"prompt":66,"zipAvailable":67},[57,60,63],{"tool":58,"command":59},"npx","npx skills add boisenoise\u002Fskills-collections --skill Linear",{"tool":61,"command":62},"bunx","bunx skills add boisenoise\u002Fskills-collections --skill Linear",{"tool":64,"command":65},"pnpm","pnpm dlx skills add boisenoise\u002Fskills-collections --skill Linear","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002FSKILL.md",true,[69,75,79,83,89,93,97,101,105,109,113,117,121,125,129,133,137,141,145,149,153,157,161,165,169,173,177,181,185,189,193],{"path":70,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":73,"sourceHtmlUrl":74},"api.md","REFERENCE","参考文档",3603,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fapi.md",{"path":76,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":77,"sourceHtmlUrl":78},"CHANGELOG.md",12084,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002FCHANGELOG.md",{"path":80,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":81,"sourceHtmlUrl":82},"docs\u002Flabels.md",6808,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fdocs\u002Flabels.md",{"path":84,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":87,"sourceHtmlUrl":88},"hooks\u002Fpost-edit.sh","SCRIPT","脚本",2454,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fhooks\u002Fpost-edit.sh",{"path":90,"resourceType":90,"resourceTypeDesc":91,"sizeBytes":92,"sourceHtmlUrl":15},"LICENSE","许可证",1056,{"path":94,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":95,"sourceHtmlUrl":96},"package-lock.json",1611,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fpackage-lock.json",{"path":98,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":99,"sourceHtmlUrl":100},"package.json",1326,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fpackage.json",{"path":102,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":103,"sourceHtmlUrl":104},"README.md",10924,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002FREADME.md",{"path":106,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":107,"sourceHtmlUrl":108},"scripts\u002Fcreate-initiative-update.ts",5906,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Fcreate-initiative-update.ts",{"path":110,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":111,"sourceHtmlUrl":112},"scripts\u002Fcreate-issue-with-project.ts",8409,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Fcreate-issue-with-project.ts",{"path":114,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":115,"sourceHtmlUrl":116},"scripts\u002Fcreate-project-update.ts",5661,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Fcreate-project-update.ts",{"path":118,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":119,"sourceHtmlUrl":120},"scripts\u002Flib\u002Fagent-selection.ts",8958,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Flib\u002Fagent-selection.ts",{"path":122,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":123,"sourceHtmlUrl":124},"scripts\u002Flib\u002Fexit-codes.ts",357,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Flib\u002Fexit-codes.ts",{"path":126,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":127,"sourceHtmlUrl":128},"scripts\u002Flib\u002Findex.ts",2088,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Flib\u002Findex.ts",{"path":130,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":131,"sourceHtmlUrl":132},"scripts\u002Flib\u002Finitiative.ts",7340,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Flib\u002Finitiative.ts",{"path":134,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":135,"sourceHtmlUrl":136},"scripts\u002Flib\u002Flabels.ts",8719,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Flib\u002Flabels.ts",{"path":138,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":139,"sourceHtmlUrl":140},"scripts\u002Flib\u002Flinear-utils.ts",6445,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Flib\u002Flinear-utils.ts",{"path":142,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":143,"sourceHtmlUrl":144},"scripts\u002Flib\u002Fproject-template.ts",9004,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Flib\u002Fproject-template.ts",{"path":146,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":147,"sourceHtmlUrl":148},"scripts\u002Flib\u002Ftaxonomy-data.ts",8281,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Flib\u002Ftaxonomy-data.ts",{"path":150,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":151,"sourceHtmlUrl":152},"scripts\u002Flib\u002Ftaxonomy-validation.ts",10193,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Flib\u002Ftaxonomy-validation.ts",{"path":154,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":155,"sourceHtmlUrl":156},"scripts\u002Flib\u002Ftaxonomy.ts",3685,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Flib\u002Ftaxonomy.ts",{"path":158,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":159,"sourceHtmlUrl":160},"scripts\u002Flib\u002Fverify.ts",8932,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Flib\u002Fverify.ts",{"path":162,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":163,"sourceHtmlUrl":164},"scripts\u002Flinear-api.mjs",12385,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Flinear-api.mjs",{"path":166,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":167,"sourceHtmlUrl":168},"scripts\u002Flinear-ops.ts",42389,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Flinear-ops.ts",{"path":170,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":171,"sourceHtmlUrl":172},"scripts\u002Fphase-complete.ts",12540,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Fphase-complete.ts",{"path":174,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":175,"sourceHtmlUrl":176},"scripts\u002Fquery.sh",498,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Fquery.sh",{"path":178,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":179,"sourceHtmlUrl":180},"scripts\u002Fquery.ts",3565,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Fquery.ts",{"path":182,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":183,"sourceHtmlUrl":184},"scripts\u002Fsetup.ts",7988,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Fsetup.ts",{"path":186,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":187,"sourceHtmlUrl":188},"scripts\u002Fsync.ts",5791,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fscripts\u002Fsync.ts",{"path":190,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":191,"sourceHtmlUrl":192},"sdk.md",6920,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fsdk.md",{"path":194,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":195,"sourceHtmlUrl":196},"sync.md",7229,"https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Flinear-claude-skill\u002Fsync.md",[198,207,215,223,231,239],{"skillNo":199,"name":200,"nameZh":6,"description":201,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":202,"sourceHtmlUrl":203,"categories":204,"keywords":205,"publishedAt":206},"01M7B6HREHB53EHGGVZND7DDXN","scrapely-scrape","Collect web data with ready-made Scrape.ly scrapers: Google Maps places, Amazon products, LinkedIn jobs, reviews, social posts. Use when the user wants structured data from a site.","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-scrapely-scrape\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-scrapely-scrape\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":208,"name":209,"nameZh":6,"description":210,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":211,"sourceHtmlUrl":212,"categories":213,"keywords":214,"publishedAt":206},"01M7B6GDNNN4HE662KA6KPF7GW","lumify-odds","Lumify's hosted sports MCP\u002FREST API for sportsbook odds, line-movement history, public betting splits, and player props across MLB, NFL, NBA, NHL, soccer, tennis, NCAAF, NCAAB. Read-only market data.","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-lumify-odds\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-lumify-odds\u002FSKILL.md",[],[],{"skillNo":216,"name":217,"nameZh":6,"description":218,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":219,"sourceHtmlUrl":220,"categories":221,"keywords":222,"publishedAt":40},"01M743PZMJW2GEKG5J199GPSK7","sync-lipsync","Lip-sync an existing video of a real person to new audio or a typed script with sync. labs through its hosted MCP server, quoting the cost and waiting for approval first.","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-sync-lipsync\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-sync-lipsync\u002FSKILL.md",[],[],{"skillNo":224,"name":225,"nameZh":6,"description":226,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":227,"sourceHtmlUrl":228,"categories":229,"keywords":230,"publishedAt":40},"01M743MMN3CKTJVNRSZMB684E5","music-for-robots","Optional music-inspired creative exercise for multimodal agents. Ingests an unquantized acoustic MP3 composition by Michael Luchtan (Music For Robots) into a private temporary directory, analyzing microtiming and texture to inspire creative writing, brainstorming, or technical tasks.","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-music-for-robots\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-music-for-robots\u002FSKILL.md",[],[],{"skillNo":232,"name":233,"nameZh":6,"description":234,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":235,"sourceHtmlUrl":236,"categories":237,"keywords":238,"publishedAt":40},"01M743KC2GN5WE11BSTWSSWD8B","imagera-media","Generate or edit images, video clips, voiceovers and music through the hosted Imagera MCP server, quoting the credit cost and getting approval before each paid call.","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-imagera-media\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-imagera-media\u002FSKILL.md",[],[],{"skillNo":240,"name":241,"nameZh":6,"description":242,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":243,"sourceHtmlUrl":244,"categories":245,"keywords":246,"publishedAt":40},"01M743HDJNZQA8A4VT68NWGWQJ","deja-history","Search this machine's past AI coding sessions across Claude Code, Codex, Cursor, Gemini CLI and thirty-nine other agents before editing, debugging, or denying something exists.","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-deja-history\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fboisenoise\u002Fskills-collections\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity-deja-history\u002FSKILL.md",[],[]]