nitm-ai-dev-toolkit 3.0.15

package/src/repo/.agents/skills/linear-cli/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: linear-cli
+description: Manage Linear issues from the command line using the linear CLI. This skill allows automating Linear issue management including creating, updating, querying, and commenting on issues.
+---
+
+# Linear CLI
+
+A CLI to manage Linear issues from the command line, with git and jj integration.
+
+## When to Use
+
+- User asks to create, view, edit, or search Linear issues
+- User needs to manage teams, projects, or cycles
+- User wants to transition issue states or add comments
+- MCP tools (`mcp_linear_*`) are unavailable or failing
+- User needs scripted/batch issue operations
+
+## Prerequisites
+
+The `linear` command must be available on PATH. To check:
+
+```bash
+linear --version
+```
+
+If not installed globally, you can run it without installing via npx:
+
+```bash
+npx @schpet/linear-cli --version
+```
+
+All subsequent commands can be prefixed with `npx @schpet/linear-cli` in place of `linear`. Otherwise, follow the install instructions at:
+https://github.com/schpet/linear-cli?tab=readme-ov-file#install
+
+## Best Practices for Markdown Content
+
+When working with issue descriptions or comment bodies that contain markdown, **always prefer using file-based flags** instead of passing content as command-line arguments:
+
+- Use `--description-file` for `issue create` and `issue update` commands
+- Use `--body-file` for `comment add` and `comment update` commands
+
+**Why use file-based flags:**
+
+- Ensures proper formatting in the Linear web UI
+- Avoids shell escaping issues with newlines and special characters
+- Prevents literal `\n` sequences from appearing in markdown
+- Makes it easier to work with multi-line content
+
+**Example workflow:**
+
+```bash
+# Write markdown to a temporary file
+cat > /tmp/description.md <<'EOF'
+## Summary
+
+- First item
+- Second item
+
+## Details
+
+This is a detailed description with proper formatting.
+EOF
+
+# Create issue using the file
+linear issue create --title "My Issue" --description-file /tmp/description.md
+
+# Or for comments
+linear issue comment add ENG-123 --body-file /tmp/comment.md
+```
+
+**Only use inline flags** (`--description`, `--body`) for simple, single-line content.
+
+## Available Commands
+
+Compact command list, generated from `linear --help`:
+
+```bash
+linear auth
+linear auth login
+linear auth logout
+linear auth list
+linear auth default
+linear auth token
+linear auth whoami
+linear auth migrate
+
+linear issue
+linear issue id
+linear issue mine
+linear issue query
+linear issue title
+linear issue start
+linear issue view
+linear issue url
+linear issue describe
+linear issue commits
+linear issue pull-request
+linear issue delete
+linear issue create
+linear issue update
+linear issue comment
+linear issue comment add
+linear issue comment delete
+linear issue comment update
+linear issue comment list
+linear issue attach
+linear issue link
+linear issue relation
+linear issue relation add
+linear issue relation delete
+linear issue relation list
+
+linear team
+linear team create
+linear team delete
+linear team list
+linear team id
+linear team autolinks
+linear team members
+
+linear project
+linear project list
+linear project view
+linear project create
+linear project update
+linear project delete
+
+linear project-update
+linear project-update create
+linear project-update list
+
+linear cycle
+linear cycle list
+linear cycle view
+
+linear milestone
+linear milestone list
+linear milestone view
+linear milestone create
+linear milestone update
+linear milestone delete
+
+linear initiative
+linear initiative list
+linear initiative view
+linear initiative create
+linear initiative archive
+linear initiative update
+linear initiative unarchive
+linear initiative delete
+linear initiative add-project
+linear initiative remove-project
+
+linear initiative-update
+linear initiative-update create
+linear initiative-update list
+
+linear label
+linear label list
+linear label create
+linear label delete
+
+linear document
+linear document list
+linear document view
+linear document create
+linear document update
+linear document delete
+
+linear config
+linear schema
+linear api
+```
+
+## Discovering Options
+
+To see available subcommands and flags, run `--help` on any command:
+
+```bash
+linear --help
+linear issue --help
+linear issue list --help
+linear issue create --help
+```
+
+Each command has detailed help output describing all available flags and options.
+
+Some commands have required flags that aren't obvious. Notable examples:
+
+- `issue list` requires a sort order — provide it via `--sort` (valid values: `manual`, `priority`), the `issue_sort` config option, or the `LINEAR_ISSUE_SORT` env var. Also requires `--team <key>` unless the team can be inferred from the directory — if unknown, run `linear team list` first.
+- `--no-pager` is only supported on `issue list` — passing it to other commands like `project list` will error.
+
+## Using the Linear GraphQL API Directly
+
+**Prefer the CLI for all supported operations.** The `api` command should only be used as a fallback for queries not covered by the CLI.
+
+### Check the schema for available types and fields
+
+Write the schema to a tempfile, then search it:
+
+```bash
+linear schema -o "${TMPDIR:-/tmp}/linear-schema.graphql"
+grep -i "cycle" "${TMPDIR:-/tmp}/linear-schema.graphql"
+grep -A 30 "^type Issue " "${TMPDIR:-/tmp}/linear-schema.graphql"
+```
+
+### Make a GraphQL request
+
+**Important:** GraphQL queries containing non-null type markers (e.g. `String` followed by an exclamation mark) must be passed via heredoc stdin to avoid escaping issues. Simple queries without those markers can be passed inline.
+
+```bash
+# Simple query (no type markers, so inline is fine)
+linear api '{ viewer { id name email } }'
+
+# Query with variables — use heredoc to avoid escaping issues
+linear api --variable teamId=abc123 <<'GRAPHQL'
+query($teamId: String!) { team(id: $teamId) { name } }
+GRAPHQL
+
+# Search issues by text
+linear api --variable term=onboarding <<'GRAPHQL'
+query($term: String!) { searchIssues(term: $term, first: 20) { nodes { identifier title state { name } } } }
+GRAPHQL
+
+# Pipe to jq for filtering
+linear api '{ issues(first: 5) { nodes { identifier title } } }' | jq '.data.issues.nodes[].title'
+```
+
+### Advanced: Using curl directly
+
+For cases where you need full HTTP control, use `linear auth token`:
+
+```bash
+curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $(linear auth token)" \
+  -d '{"query": "{ viewer { id } }"}'
+```
+
+## Common Workflows
+
+### Create and Start an Issue
+
+```bash
+linear issue create --title "Implement feature" --team ENG --description-file /tmp/desc.md
+# Note the returned issue key
+linear issue start ENG-123
+```
+
+### View My Current Issues
+
+```bash
+linear issue mine
+```
+
+### Update Issue State
+
+```bash
+linear issue update ENG-123 --state "In Progress"
+linear issue update ENG-123 --state "Done"
+```
+
+### Comment on an Issue
+
+```bash
+linear issue comment add ENG-123 --body "Working on this"
+linear issue comment add ENG-123 --body-file /tmp/update.md
+```
+
+## Limitations
+
+- Requires `linear auth login` before first use
+- Some commands require `--team` flag unless inferred from directory config
+- `issue list` requires explicit sort order
+- `--no-pager` only works on `issue list`
+- Rate limits apply based on Linear API limits