{"id":34913376,"url":"https://github.com/wrsmith108/linear-claude-skill","last_synced_at":"2026-04-19T22:17:31.972Z","repository":{"id":328726491,"uuid":"1116480304","full_name":"wrsmith108/linear-claude-skill","owner":"wrsmith108","description":"Agent skill for managing Linear issues, projects, and teams. MCP tools, SDK automation, GraphQL API patterns.","archived":false,"fork":false,"pushed_at":"2026-03-21T01:24:41.000Z","size":567,"stargazers_count":76,"open_issues_count":1,"forks_count":10,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-02T06:26:28.786Z","etag":null,"topics":["claude-code","claude-code-skills","claude-skills","linear","project-management"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wrsmith108.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-14T23:42:51.000Z","updated_at":"2026-04-02T05:40:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"16af4cb9-1c93-41cc-9352-18f237308cef","html_url":"https://github.com/wrsmith108/linear-claude-skill","commit_stats":null,"previous_names":["wrsmith108/linear-claude-skill"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/wrsmith108/linear-claude-skill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wrsmith108%2Flinear-claude-skill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wrsmith108%2Flinear-claude-skill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wrsmith108%2Flinear-claude-skill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wrsmith108%2Flinear-claude-skill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wrsmith108","download_url":"https://codeload.github.com/wrsmith108/linear-claude-skill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wrsmith108%2Flinear-claude-skill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31536473,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","claude-code-skills","claude-skills","linear","project-management"],"created_at":"2025-12-26T12:00:31.238Z","updated_at":"2026-04-19T22:17:31.948Z","avatar_url":"https://github.com/wrsmith108.png","language":"TypeScript","funding_links":[],"categories":["🤝 Collaboration \u0026 Project Management","TypeScript","Sponsors ❤️","Productivity \u0026 Workflow"],"sub_categories":["Community Skills"],"readme":"# Linear Skill for Claude Code\n\nA comprehensive [Claude Code](https://claude.ai/code) skill for managing Linear issues, projects, and teams. Provides patterns for MCP tools, SDK automation, and GraphQL API access.\n\n## Features\n\n- **esbuild Pre-compilation** — 18x faster CLI startup (~50ms vs ~1s) with transparent tsx fallback via shared `scripts/run.sh`\n- **Label Taxonomy System** — Domain-based labels for consistent categorization and agent routing\n- **First-Time Setup Check** — Automatic configuration validation with actionable guidance\n- **High-Level Operations** — Simple commands for initiatives, projects, and status updates\n- **Sub-Issue Management** — Create and manage parent-child issue relationships\n- **Discovery Before Creation** — Mandatory checks to prevent duplicate projects/issues\n- **MCP Tool Integration** — Simple operations via Linear MCP server\n- **SDK Automation** — Complex operations with TypeScript scripts\n- **GraphQL API** — Direct API access for advanced queries\n- **Project Management** — Content, descriptions, milestones, resource links\n- **Bulk Sync** — Synchronize code changes with Linear via CLI, agents, or hooks\n- **Image Uploads** — Upload images to Linear's S3 storage and attach to issues\n- **Smoke Tests** — Automated verification of build output and CLI behavior\n- **`lin` CLI Integration** — Optional fast-path via [aaronkwhite/linear-cli](https://github.com/aaronkwhite/linear-cli) Rust binary with silent SDK fallback\n\n## Quick Start (New Users)\n\n### 1. Install the Skill\n\n```bash\ngit clone https://github.com/wrsmith108/linear-claude-skill ~/.claude/skills/linear\ncd ~/.claude/skills/linear \u0026\u0026 npm install\n```\n\n### 2. Run Setup Check\n\n```bash\nnpm run setup\n```\n\nThis checks your configuration and tells you exactly what's missing.\n\n### 3. Get Your API Key (If Needed)\n\n1. Open [Linear](https://linear.app) in your browser\n2. Go to **Settings** → **Security \u0026 access** → **Personal API keys**\n3. Click **Create key** and copy it (starts with `lin_api_`)\n4. Add to your environment:\n\n```bash\n# Add to shell profile\necho 'export LINEAR_API_KEY=\"lin_api_your_key_here\"' \u003e\u003e ~/.zshrc\nsource ~/.zshrc\n```\n\n### 4. Verify It Works\n\n```bash\nnpm run ops -- whoami\n```\n\nYou should see your name and organization.\n\n### 5. Build for Faster Startup (Optional)\n\n```bash\nnpm run build\n```\n\nPre-compiles TypeScript to JavaScript for ~18x faster CLI cold starts. Without building, commands still work via tsx (slower but functional).\n\n### 6. Start Using It\n\n```bash\n# Create an initiative\nnpm run ops -- create-initiative \"My Project\"\n\n# Create a project\nnpm run ops -- create-project \"Phase 1\" \"My Project\"\n\n# Create a sub-issue under a parent\nnpm run ops -- create-sub-issue ENG-100 \"Add tests\" \"Unit tests for feature\"\n\n# Set parent-child relationships for existing issues\nnpm run ops -- set-parent ENG-100 ENG-101 ENG-102\n\n# Update issue status\nnpm run ops -- status Done ENG-123 ENG-124\n\n# See all commands\nnpm run ops -- help\n```\n\n---\n\n## Installation\n\n```bash\n# Clone directly to your skills directory\ngit clone https://github.com/wrsmith108/linear-claude-skill ~/.claude/skills/linear\ncd ~/.claude/skills/linear \u0026\u0026 npm install\n```\n\n## Prerequisites\n\n- **Linear API Key** — Generate at Linear → Settings → Security \u0026 access → Personal API keys\n- **`lin` CLI** (Optional) — Faster execution for status updates, search, and listings:\n  ```bash\n  brew install aaronkwhite/tap/lin    # macOS (Homebrew)\n  cargo install lincli                # Any platform with Rust\n  ```\n  Set `LINEAR_USE_LIN=0` to disable even when installed.\n- **Linear MCP Server** (Recommended) — Use the **official Linear MCP server** for best reliability:\n\n```json\n{\n  \"mcpServers\": {\n    \"linear\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-remote\", \"https://mcp.linear.app/sse\"],\n      \"env\": {\n        \"LINEAR_API_KEY\": \"your_api_key\"\n      }\n    }\n  }\n}\n```\n\n\u003e **Important**: Always use Linear's official MCP server at `mcp.linear.app`. Do NOT use deprecated community servers like `linear-mcp-server` (npm) or `jerhadf/linear-mcp-server` (GitHub).\n\n## Directory Structure\n\n```\nlinear-claude-skill/\n├── SKILL.md              # Main skill instructions (Claude Code discovers this)\n├── api.md                # GraphQL API reference\n├── sdk.md                # SDK automation patterns\n├── sync.md               # Bulk sync patterns\n├── docs/\n│   └── labels.md         # Label taxonomy documentation\n├── scripts/\n│   ├── run.sh            # Shared runner (dist/ with tsx fallback)\n│   ├── build.mjs         # esbuild pre-compilation script\n│   ├── linear-ops.ts     # High-level operations (issues, projects, labels)\n│   ├── query.ts          # GraphQL query runner\n│   ├── setup.ts          # Configuration checker\n│   ├── sync.ts           # Bulk sync CLI tool\n│   ├── upload-image.ts   # Upload images to Linear S3\n│   ├── extract-image.ts  # Extract images from session JSONL\n│   ├── linear-api.mjs    # Direct API wrapper\n│   ├── __tests__/        # Smoke tests (Node built-in test runner)\n│   └── lib/              # Shared utilities (taxonomy, labels, verification)\n├── dist/                 # Pre-compiled JS output (gitignored, in npm package)\n└── hooks/\n    └── post-edit.sh      # Auto-sync hook\n```\n\n## Key Patterns\n\n### Discovery Before Creation (Critical!)\n\n**ALWAYS check Linear before creating projects or issues.** This prevents duplicates:\n\n```bash\n# Check for existing projects\nlinear projects list | grep -i \"phase\\|feature-name\"\n\n# Check for existing issues\nlinear issues list --filter \"title:keyword\"\n```\n\nSee `SKILL.md` → \"Discovery Before Creation\" for the full checklist.\n\n### Codebase Verification Before Work (Critical!)\n\n**ALWAYS verify codebase state before accepting issue scope at face value.**\n\nIssue descriptions may be outdated or speculative. APIs or features may already be implemented!\n\n```bash\n# Before starting \"implement API\" issues:\nls src/pages/api/admin/members/     # Check if files exist\ngrep -r \"test.skip\" tests/          # Check if tests are just skipped\n```\n\n**Key Lesson**: Issues describing \"missing\" features may already be implemented. The real work is often un-skipping tests and fixing assertions, not reimplementing.\n\nSee `SKILL.md` → \"Codebase Verification Before Work\" for the full checklist.\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 |\n|-------|-------|----------|\n| `description` | 255 chars | List views, tooltips |\n| `content` | Unlimited | **Main detail panel** |\n\nAlways set BOTH when creating projects.\n\n### Project Status UUIDs\n\nStatus UUIDs are **workspace-specific**. Query your workspace:\n\n```graphql\nquery { projectStatuses { nodes { id name } } }\n```\n\nCommon statuses: `Backlog`, `Planned`, `In Progress`, `Completed`, `Canceled`\n\n### Sub-Issue Management\n\nOrganize issues into parent-child hierarchies for better tracking:\n\n```bash\n# Create a sub-issue under a parent issue\n# Inherits team and project from parent automatically\nnpm run ops -- create-sub-issue \u003cparent\u003e \u003ctitle\u003e [description] [--priority 1-4] [--labels label1,label2]\n\n# Set existing issues as children of a parent\nnpm run ops -- set-parent \u003cparent\u003e \u003cchild1\u003e \u003cchild2\u003e ...\n\n# List all sub-issues of a parent\nnpm run ops -- list-sub-issues \u003cparent\u003e\n```\n\n**When to use sub-issues:**\n- Breaking down features into trackable subtasks\n- Organizing TDD/E2E test issues under a feature issue\n- Sequential phases within a larger initiative\n\n### Label Taxonomy\n\nA standardized label system for consistent issue categorization across projects:\n\n```bash\n# Show full taxonomy (25 labels across 3 categories)\nnpm run ops -- labels taxonomy\n\n# Validate label combinations\nnpm run ops -- labels validate \"feature,security,breaking-change\"\n\n# Suggest labels based on issue title\nnpm run ops -- labels suggest \"Fix XSS vulnerability in login form\"\n\n# Show agent recommendations for labels\nnpm run ops -- labels agents \"security,performance\"\n```\n\n**Label Categories:**\n- **Type** (exactly one required): `feature`, `bug`, `refactor`, `chore`, `spike`\n- **Domain** (1-2 recommended): `security`, `backend`, `frontend`, `testing`, `infrastructure`, `mcp`, `cli`, etc.\n- **Scope** (0-2 optional): `blocked`, `breaking-change`, `tech-debt`, `needs-split`, `good-first-issue`\n\nSee `docs/labels.md` for the complete taxonomy guide.\n\n### Resource Links\n\nAdd clickable links to projects/initiatives:\n\n```graphql\nmutation {\n  entityExternalLinkCreate(input: {\n    url: \"https://github.com/wrsmith108/linear-claude-skill/blob/main/docs/phase-1.md\",\n    label: \"Implementation Doc\",\n    projectId: \"\u003cuuid\u003e\"\n  }) { success }\n}\n```\n\n### Project Milestones\n\nTrack Definition of Done:\n\n```graphql\nmutation {\n  projectMilestoneCreate(input: {\n    projectId: \"\u003cuuid\u003e\",\n    name: \"DoD: Testing\",\n    description: \"Unit tests, E2E tests, 100% coverage\"\n  }) { success }\n}\n```\n\n### Project Updates (Status Reports)\n\nPost status updates to a project's Updates tab:\n\n```bash\nnpm run ops -- create-project-update \"Project Name\" \"## Update\\n\\nBody\" --health onTrack\n```\n\nHealth options: `onTrack`, `atRisk`, `offTrack`\n\nSee `SKILL.md` for full documentation and GraphQL examples.\n\n## Usage Examples\n\n### Create Issue (MCP)\n```\nCreate a high priority issue titled \"Fix authentication bug\" in the ENG team\n```\n\n### Update Project Status (GraphQL)\n```graphql\nmutation {\n  projectUpdate(id: \"\u003cproject-uuid\u003e\", input: {\n    statusId: \"\u003cstatus-uuid\u003e\"  # Get from projectStatuses query\n  }) { success }\n}\n```\n\n### Bulk Operations (SDK)\nSee `sdk.md` for TypeScript patterns for loops, filtering, and batch updates.\n\n### Bulk Sync (NEW)\n\nSynchronize code changes with Linear issues in bulk:\n\n```bash\n# Update multiple issues to Done\nnpm run sync -- --issues ENG-432,ENG-433,ENG-434 --state Done\n\n# Update project status after phase completion\nnpm run sync -- --project \"Phase 11\" --state completed\n\n# Verify sync completed\nnpm run sync -- --verify ENG-432,ENG-433 --expected-state Done\n```\n\n#### Agent-Spawned Sync\n\nSpawn a parallel agent for autonomous sync via Task tool:\n\n```javascript\nTask({\n  description: \"Sync Phase 11 to Linear\",\n  prompt: \"Update ENG-432,433,434 to Done. Update project to completed.\",\n  subagent_type: \"Linear-specialist\"\n})\n```\n\n#### Hook-Triggered Sync\n\nAuto-suggest sync after code edits. Add to `.claude/settings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"PostToolUse\": [{\n      \"matcher\": \"Write|Edit\",\n      \"hooks\": [{\n        \"type\": \"command\",\n        \"command\": \"bash ~/.claude/skills/linear/hooks/post-edit.sh\"\n      }]\n    }]\n  }\n}\n```\n\nSee `sync.md` for complete patterns including AgentDB integration.\n\n## Changelog\n\n### 2.6.3 (2026-04-08)\n\n- Extracted shared `scripts/run.sh` — all 7 npm scripts now use a single runner instead of duplicated shell wrappers\n- Replaced `2\u003e/dev/null` with `[ -f dist/X.js ]` file-existence checks so runtime errors surface properly\n- Added `f() { ...; }; f` argument forwarding to all npm scripts (community fix from PR #17 by @aphexcx)\n- Added smoke test for npm script argument forwarding\n- Consistent `[WARN]` fallback messages across all scripts including `sync`\n\n### 2.5.0 (2026-03-17)\n\n- Consolidated `requireClient()` to delegate to `getLinearClient()` — single client singleton\n- Added smoke tests for build output, CLI behavior, and lazy client initialization\n- Documented `__BUNDLED__` build-time define pattern\n- Extended esbuild fallback pattern to `upload-image` and `extract-image` scripts\n- Bumped SKILL.md version to match package.json\n\n### 2.4.0 (2026-03-04)\n\n- Added esbuild pre-compilation for **18x faster CLI startup** (~50ms vs ~1s)\n- Lazy `getLinearClient()` — SDK initialization deferred to first API call\n- Transparent fallback via shared `scripts/run.sh`\n- Removed `import.meta.url` CLI guards from lib files\n- `npm run` as canonical invocation form in all documentation\n- CI workflow with build verification and smoke tests\n\n### 2.3.0 (2026-02-27)\n\n- Added `scripts/upload-image.ts` and `scripts/extract-image.ts` for image management\n\nSee [CHANGELOG.md](CHANGELOG.md) for full version history.\n\n## Development\n\n### Prerequisites\n\n- Node.js \u003e= 20.11.0 (see `.nvmrc`)\n- npm\n\n### Quick Start\n\n```bash\ngit clone https://github.com/wrsmith108/linear-claude-skill.git\ncd linear-claude-skill\nnpm ci\nnpm test        # builds and runs smoke tests (no API key needed)\nnpm run build   # compile TypeScript to dist/\n```\n\n## Contributing\n\nContributions welcome! Please submit issues and PRs to improve the skill.\n\n## License\n\nMIT License — See [LICENSE](LICENSE)\n\n## Credits\n\nCreated for the Claude Code community. Patterns developed through real-world project management workflows.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwrsmith108%2Flinear-claude-skill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwrsmith108%2Flinear-claude-skill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwrsmith108%2Flinear-claude-skill/lists"}