[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6EZ16Y74CDC2EXBYBTJATJB":3,"skill-same:01M6EZ16Y74CDC2EXBYBTJATJB":73},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":35,"linkOnly":36,"markdownContent":37,"markdownBody":38,"frontMatter":39,"refName":44,"commitSha":45,"skillDirectory":46,"forksCount":47,"repositoryHtmlUrl":48,"repositoryHomepageUrl":49,"ownerHtmlUrl":50,"ownerBlogUrl":6,"ownerDescription":51,"updatedAt":52,"install":53,"resources":66},"01M6EZ16Y74CDC2EXBYBTJATJB","linear-claude-skill",null,"Manage Linear issues, projects, and teams","ComeOnOliver\u002Fskillshub","ComeOnOliver","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F43215937?v=4","01M6E5JNFECJAAVFE0W7SMWWD2","Haoran Shu","01M6E5JNNDQS7AJZDYFQ8TPZCK",66,"MIT","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Faiskillstore\u002Fmarketplace\u002Fsickn33\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],"linear","claude skill","linear claude skill","safe","github","teams","issues","https","projects","manage","app","2026-11-10 10:12:30",false,"---\nname: linear-claude-skill\ndescription: \"Manage Linear issues, projects, and teams\"\nallowed-tools: \n- WebFetch(domain: linear.app)\nsource: \"https:\u002F\u002Fgithub.com\u002Fwrsmith108\u002Flinear-claude-skill\"\nrisk: safe\n---\n\n## When to Use This Skill\n\nManage Linear issues, projects, and teams\n\nUse this skill when working with manage linear issues, projects, and teams.\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 ENG-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 ENG-123 -s \"STATE_ID\"\n\n# Add a comment\nlinear issues comment add ENG-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\n## When to Use This Skill\n\nManage Linear issues, projects, and teams\n\nUse this skill when working with manage linear issues, projects, and teams.\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\n```bash\n# Create issue in a project\nnpx tsx scripts\u002Flinear-ops.ts create-issue \"Project\" \"Title\" \"Description\"\n\n# Update issue status\nnpx tsx scripts\u002Flinear-ops.ts status Done ENG-123 ENG-124\n\n# Create sub-issue\nnpx tsx scripts\u002Flinear-ops.ts create-sub-issue ENG-100 \"Sub-task\" \"Details\"\n\n# Update project status\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase 1\" completed\n\n# Show all commands\nnpx tsx scripts\u002Flinear-ops.ts help\n```\n\nSee [Project Management Commands](#project-management-commands) for full reference.\n\n---\n\n\n## When to Use This Skill\n\nManage Linear issues, projects, and teams\n\nUse this skill when working with manage linear issues, projects, and teams.\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\" \"My Initiative\"\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 ENG-XXX \"Sub-task 1\" \"Description\"\n   npx tsx scripts\u002Flinear-ops.ts create-sub-issue ENG-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 a project to an initiative\nnpx tsx scripts\u002Flinear-ops.ts link-initiative \"Phase 8: MCP Decision Engine\" \"Q1 Goals\"\n\n# Partial matching works\nnpx tsx scripts\u002Flinear-ops.ts link-initiative \"Phase 8\" \"Q1 Goals\"\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\" \"Q1 Goals\"\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 ENG-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 ENG-XXX ENG-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\n## When to Use This Skill\n\nManage Linear issues, projects, and teams\n\nUse this skill when working with manage linear issues, projects, and teams.\n## Tool Selection\n\nChoose the right tool for the task:\n\n| Tool | When to Use |\n|------|-------------|\n| **MCP (Official Server)** | Most operations - PREFERRED |\n| **Helper Scripts** | Bulk operations, when MCP unavailable |\n| **SDK scripts** | Complex operations (loops, conditionals) |\n| **GraphQL API** | Operations not supported by MCP\u002FSDK |\n\n### MCP Server Configuration\n\n**Use the official Linear MCP server** at `mcp.linear.app`:\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. See [troubleshooting.md](troubleshooting.md) for details.\n\n### MCP Reliability (Official Server)\n\n| Operation | Reliability | Notes |\n|-----------|-------------|-------|\n| Create issue | ✅ High | Full support |\n| Update status | ✅ High | Use `state: \"Done\"` directly |\n| List\u002FSearch issues | ✅ High | Supports filters, queries |\n| Add comment | ✅ High | Works with issue IDs |\n\n### Quick Status Update\n\n```bash\n# Via MCP - use human-readable state names\nupdate_issue with id=\"issue-uuid\", state=\"Done\"\n\n# Via helper script (bulk operations)\nnode scripts\u002Flinear-helpers.mjs update-status Done 123 124 125\n```\n\n### Helper Script Reference\n\nFor detailed helper script usage, see **[troubleshooting.md](troubleshooting.md)**.\n\n### Parallel Agent Execution\n\nFor bulk operations or background execution, use the `Linear-specialist` subagent:\n\n```javascript\nTask({\n  description: \"Update Linear issues\",\n  prompt: \"Mark ENG-101, ENG-102, ENG-103 as Done\",\n  subagent_type: \"Linear-specialist\"\n})\n```\n\n**When to use `Linear-specialist` (parallel):**\n- Bulk status updates (3+ issues)\n- Project status changes\n- Creating multiple issues\n- Sync operations after code changes\n\n**When to use direct execution:**\n- Single issue queries\n- Viewing issue details\n- Quick status checks\n- Operations needing immediate results\n\nSee **[sync.md](sync.md)** for parallel execution patterns.\n\n## Critical Requirements\n\n### Issues → Projects → Initiatives\n\n**Every issue MUST be attached to a project. Every project MUST be linked to an initiative.**\n\n| Entity | Must Link To | If Missing |\n|--------|--------------|------------|\n| Issue | Project | Not visible in project board |\n| Project | Initiative | Not visible in roadmap |\n\nSee **[projects.md](projects.md)** for complete project creation checklist.\n\n---\n\n## Conventions\n\n### Issue Status\n\n- **Assigned to me**: Set `state: \"Todo\"`\n- **Unassigned**: Set `state: \"Backlog\"`\n\n### Labels\n\nUses **domain-based label taxonomy**. See [docs\u002Flabels.md](docs\u002Flabels.md).\n\n**Key rules:**\n- ONE Type label: `feature`, `bug`, `refactor`, `chore`, `spike`\n- 1-2 Domain labels: `security`, `backend`, `frontend`, etc.\n- Scope labels when applicable: `blocked`, `breaking-change`, `tech-debt`\n\n```bash\n# Validate labels\nnpx tsx scripts\u002Flinear-ops.ts labels validate \"feature,security\"\n\n# Suggest labels for issue\nnpx tsx scripts\u002Flinear-ops.ts labels suggest \"Fix XSS vulnerability\"\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.\n\nSee **[api.md](api.md)** for complete documentation including:\n- Authentication and setup\n- Example queries and mutations\n- Timeout handling patterns\n- MCP timeout workarounds\n- Shell script compatibility\n\n**Quick ad-hoc query:**\n\n```bash\nnpx tsx ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Fquery.ts \"query { viewer { name } }\"\n```\n\n## Projects & Initiatives\n\nFor advanced project and initiative management patterns, see **[projects.md](projects.md)**.\n\n**Quick reference** - common project commands:\n\n```bash\n# Create project linked to initiative\nnpx tsx scripts\u002Flinear-ops.ts create-project \"Phase X: Name\" \"My Initiative\"\n\n# Update project status\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase X\" in-progress\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase X\" completed\n\n# Link\u002Funlink projects to initiatives\nnpx tsx scripts\u002Flinear-ops.ts link-initiative \"Phase X\" \"My Initiative\"\nnpx tsx scripts\u002Flinear-ops.ts unlink-initiative \"Phase X\" \"Old Initiative\"\n```\n\n**Key topics in projects.md:**\n- Project creation checklist (mandatory steps)\n- Content vs Description fields\n- Discovery before creation\n- Codebase verification before work\n- Sub-issue management\n- Project status updates\n- Project updates (status reports)\n\n---\n\n\n## When to Use This Skill\n\nManage Linear issues, projects, and teams\n\nUse this skill when working with manage linear issues, projects, and teams.\n## Sync Patterns (Bulk Operations)\n\nFor bulk synchronization of code changes to Linear, see **[sync.md](sync.md)**.\n\n**Quick sync commands:**\n\n```bash\n# Bulk update issues to Done\nnpx tsx scripts\u002Flinear-ops.ts status Done ENG-101 ENG-102 ENG-103\n\n# Update project status\nnpx tsx scripts\u002Flinear-ops.ts project-status \"My Project\" completed\n```\n\n---\n\n## Reference\n\n| Document | Purpose |\n|----------|---------|\n| [api.md](api.md) | GraphQL API reference, timeout handling |\n| [sdk.md](sdk.md) | SDK automation patterns |\n| [sync.md](sync.md) | Bulk sync patterns |\n| [projects.md](projects.md) | Project & initiative management |\n| [troubleshooting.md](troubleshooting.md) | Common issues, MCP debugging |\n| [docs\u002Flabels.md](docs\u002Flabels.md) | Label taxonomy |\n\n**External:** [Linear MCP Documentation](https:\u002F\u002Flinear.app\u002Fdocs\u002Fmcp.md)\n","## When to Use This Skill\n\nManage Linear issues, projects, and teams\n\nUse this skill when working with manage linear issues, projects, and teams.\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 ENG-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 ENG-123 -s \"STATE_ID\"\n\n# Add a comment\nlinear issues comment add ENG-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\n## When to Use This Skill\n\nManage Linear issues, projects, and teams\n\nUse this skill when working with manage linear issues, projects, and teams.\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\n```bash\n# Create issue in a project\nnpx tsx scripts\u002Flinear-ops.ts create-issue \"Project\" \"Title\" \"Description\"\n\n# Update issue status\nnpx tsx scripts\u002Flinear-ops.ts status Done ENG-123 ENG-124\n\n# Create sub-issue\nnpx tsx scripts\u002Flinear-ops.ts create-sub-issue ENG-100 \"Sub-task\" \"Details\"\n\n# Update project status\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase 1\" completed\n\n# Show all commands\nnpx tsx scripts\u002Flinear-ops.ts help\n```\n\nSee [Project Management Commands](#project-management-commands) for full reference.\n\n---\n\n\n## When to Use This Skill\n\nManage Linear issues, projects, and teams\n\nUse this skill when working with manage linear issues, projects, and teams.\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\" \"My Initiative\"\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 ENG-XXX \"Sub-task 1\" \"Description\"\n   npx tsx scripts\u002Flinear-ops.ts create-sub-issue ENG-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 a project to an initiative\nnpx tsx scripts\u002Flinear-ops.ts link-initiative \"Phase 8: MCP Decision Engine\" \"Q1 Goals\"\n\n# Partial matching works\nnpx tsx scripts\u002Flinear-ops.ts link-initiative \"Phase 8\" \"Q1 Goals\"\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\" \"Q1 Goals\"\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 ENG-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 ENG-XXX ENG-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\n## When to Use This Skill\n\nManage Linear issues, projects, and teams\n\nUse this skill when working with manage linear issues, projects, and teams.\n## Tool Selection\n\nChoose the right tool for the task:\n\n| Tool | When to Use |\n|------|-------------|\n| **MCP (Official Server)** | Most operations - PREFERRED |\n| **Helper Scripts** | Bulk operations, when MCP unavailable |\n| **SDK scripts** | Complex operations (loops, conditionals) |\n| **GraphQL API** | Operations not supported by MCP\u002FSDK |\n\n### MCP Server Configuration\n\n**Use the official Linear MCP server** at `mcp.linear.app`:\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. See [troubleshooting.md](troubleshooting.md) for details.\n\n### MCP Reliability (Official Server)\n\n| Operation | Reliability | Notes |\n|-----------|-------------|-------|\n| Create issue | ✅ High | Full support |\n| Update status | ✅ High | Use `state: \"Done\"` directly |\n| List\u002FSearch issues | ✅ High | Supports filters, queries |\n| Add comment | ✅ High | Works with issue IDs |\n\n### Quick Status Update\n\n```bash\n# Via MCP - use human-readable state names\nupdate_issue with id=\"issue-uuid\", state=\"Done\"\n\n# Via helper script (bulk operations)\nnode scripts\u002Flinear-helpers.mjs update-status Done 123 124 125\n```\n\n### Helper Script Reference\n\nFor detailed helper script usage, see **[troubleshooting.md](troubleshooting.md)**.\n\n### Parallel Agent Execution\n\nFor bulk operations or background execution, use the `Linear-specialist` subagent:\n\n```javascript\nTask({\n  description: \"Update Linear issues\",\n  prompt: \"Mark ENG-101, ENG-102, ENG-103 as Done\",\n  subagent_type: \"Linear-specialist\"\n})\n```\n\n**When to use `Linear-specialist` (parallel):**\n- Bulk status updates (3+ issues)\n- Project status changes\n- Creating multiple issues\n- Sync operations after code changes\n\n**When to use direct execution:**\n- Single issue queries\n- Viewing issue details\n- Quick status checks\n- Operations needing immediate results\n\nSee **[sync.md](sync.md)** for parallel execution patterns.\n\n## Critical Requirements\n\n### Issues → Projects → Initiatives\n\n**Every issue MUST be attached to a project. Every project MUST be linked to an initiative.**\n\n| Entity | Must Link To | If Missing |\n|--------|--------------|------------|\n| Issue | Project | Not visible in project board |\n| Project | Initiative | Not visible in roadmap |\n\nSee **[projects.md](projects.md)** for complete project creation checklist.\n\n---\n\n## Conventions\n\n### Issue Status\n\n- **Assigned to me**: Set `state: \"Todo\"`\n- **Unassigned**: Set `state: \"Backlog\"`\n\n### Labels\n\nUses **domain-based label taxonomy**. See [docs\u002Flabels.md](docs\u002Flabels.md).\n\n**Key rules:**\n- ONE Type label: `feature`, `bug`, `refactor`, `chore`, `spike`\n- 1-2 Domain labels: `security`, `backend`, `frontend`, etc.\n- Scope labels when applicable: `blocked`, `breaking-change`, `tech-debt`\n\n```bash\n# Validate labels\nnpx tsx scripts\u002Flinear-ops.ts labels validate \"feature,security\"\n\n# Suggest labels for issue\nnpx tsx scripts\u002Flinear-ops.ts labels suggest \"Fix XSS vulnerability\"\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.\n\nSee **[api.md](api.md)** for complete documentation including:\n- Authentication and setup\n- Example queries and mutations\n- Timeout handling patterns\n- MCP timeout workarounds\n- Shell script compatibility\n\n**Quick ad-hoc query:**\n\n```bash\nnpx tsx ~\u002F.claude\u002Fskills\u002Flinear\u002Fscripts\u002Fquery.ts \"query { viewer { name } }\"\n```\n\n## Projects & Initiatives\n\nFor advanced project and initiative management patterns, see **[projects.md](projects.md)**.\n\n**Quick reference** - common project commands:\n\n```bash\n# Create project linked to initiative\nnpx tsx scripts\u002Flinear-ops.ts create-project \"Phase X: Name\" \"My Initiative\"\n\n# Update project status\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase X\" in-progress\nnpx tsx scripts\u002Flinear-ops.ts project-status \"Phase X\" completed\n\n# Link\u002Funlink projects to initiatives\nnpx tsx scripts\u002Flinear-ops.ts link-initiative \"Phase X\" \"My Initiative\"\nnpx tsx scripts\u002Flinear-ops.ts unlink-initiative \"Phase X\" \"Old Initiative\"\n```\n\n**Key topics in projects.md:**\n- Project creation checklist (mandatory steps)\n- Content vs Description fields\n- Discovery before creation\n- Codebase verification before work\n- Sub-issue management\n- Project status updates\n- Project updates (status reports)\n\n---\n\n\n## When to Use This Skill\n\nManage Linear issues, projects, and teams\n\nUse this skill when working with manage linear issues, projects, and teams.\n## Sync Patterns (Bulk Operations)\n\nFor bulk synchronization of code changes to Linear, see **[sync.md](sync.md)**.\n\n**Quick sync commands:**\n\n```bash\n# Bulk update issues to Done\nnpx tsx scripts\u002Flinear-ops.ts status Done ENG-101 ENG-102 ENG-103\n\n# Update project status\nnpx tsx scripts\u002Flinear-ops.ts project-status \"My Project\" completed\n```\n\n---\n\n## Reference\n\n| Document | Purpose |\n|----------|---------|\n| [api.md](api.md) | GraphQL API reference, timeout handling |\n| [sdk.md](sdk.md) | SDK automation patterns |\n| [sync.md](sync.md) | Bulk sync patterns |\n| [projects.md](projects.md) | Project & initiative management |\n| [troubleshooting.md](troubleshooting.md) | Common issues, MCP debugging |\n| [docs\u002Flabels.md](docs\u002Flabels.md) | Label taxonomy |\n\n**External:** [Linear MCP Documentation](https:\u002F\u002Flinear.app\u002Fdocs\u002Fmcp.md)\n",{"name":5,"risk":27,"source":40,"description":7,"allowed-tools":41},"https:\u002F\u002Fgithub.com\u002Fwrsmith108\u002Flinear-claude-skill",[42],{"WebFetch(domain":43},"linear.app)","main","def8531e65114c0fca8fb8551c1871ee0eed705c","skills\u002Faiskillstore\u002Fmarketplace\u002Fsickn33\u002Flinear-claude-skill",24,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub","https:\u002F\u002Fskillshub.wtf","https:\u002F\u002Fgithub.com\u002FComeOnOliver","AI & Blockchain Engineer\r\n","2026-06-24 22:07:19",{"source":8,"skillName":5,"commands":54,"prompt":64,"zipAvailable":65},[55,58,61],{"tool":56,"command":57},"npx","npx skills add ComeOnOliver\u002Fskillshub --skill linear-claude-skill",{"tool":59,"command":60},"bunx","bunx skills add ComeOnOliver\u002Fskillshub --skill linear-claude-skill",{"tool":62,"command":63},"pnpm","pnpm dlx skills add ComeOnOliver\u002Fskillshub --skill linear-claude-skill","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Faiskillstore\u002Fmarketplace\u002Fsickn33\u002Flinear-claude-skill\u002FSKILL.md",true,[67],{"path":68,"resourceType":69,"resourceTypeDesc":70,"sizeBytes":71,"sourceHtmlUrl":72},"skill-report.json","REFERENCE","参考文档",9329,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Faiskillstore\u002Fmarketplace\u002Fsickn33\u002Flinear-claude-skill\u002Fskill-report.json",[74,84,94,103,109,116],{"skillNo":75,"name":76,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":80,"publishedAt":35},"01M6FKJN13GMG4KY57J3QD8GY5","model-hierarchy-skill","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzscole\u002Fmodel-hierarchy-skill\u002Fmodel-hierarchy-skill\u002FSKILL.md",[79],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[81,82,83],"model","model hierarchy","model hierarchy skill",{"skillNo":85,"name":86,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":90,"publishedAt":35},"01M6FKJJJ6GCAMR4PPPRD12M5X","zoom-mcp","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fzoom-mcp\u002FSKILL.md",[89],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[91,92,93],"MCP","zoom","zoom mcp",{"skillNo":95,"name":96,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":97,"categories":98,"keywords":99,"publishedAt":35},"01M6FKJE3KYT3KPEZMEEHYKA6K","zoom-apps-sdk","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fzoom-apps-sdk\u002FSKILL.md",[],[100,101,102,92],"sdk","zoom apps sdk","apps",{"skillNo":104,"name":105,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":106,"categories":107,"keywords":108,"publishedAt":35},"01M6FKJ9EDH9Q5VWDF8HAJRSP0","windows","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwindows\u002FSKILL.md",[],[105],{"skillNo":110,"name":111,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":112,"categories":113,"keywords":115,"publishedAt":35},"01M6FKJ666BEEFC3AE9GJ72Q93","whiteboard","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwhiteboard\u002FSKILL.md",[114],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[111],{"skillNo":117,"name":118,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":119,"categories":120,"keywords":121,"publishedAt":35},"01M6FKJ21WFCDGTJQ2Q91T9DVW","websockets","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwebsockets\u002FSKILL.md",[],[118]]