linear-create-issue

Create one Linear issue through the direct Linear GraphQL API using a local LINEAR_API_KEY. Use only as a narrow fallback when the normal Linear connector is unavailable or cannot create the issue.

SKILL.md

GitHub

Linear Create Issue

Use this skill when the normal Linear connector cannot create an issue and a narrow, audited GraphQL fallback is needed.

Prefer the official Linear connector for normal issue creation. This skill is a fallback issue creator, not a general Linear client.

Preconditions

  • LINEAR_API_KEY is available in the shell, LINEAR_ENV_FILE, --env-file, or a local .env.local.
  • The key belongs to a Linear user with permission to create issues in the target team.
  • Network access to https://api.linear.app/graphql is allowed.

Non-Negotiable Rules

  • Use scripts/create_issue.py.
  • Never print the API key.
  • Do not store the API key in the skill directory.
  • Create exactly one issue per invocation.
  • Resolve the target team, status, project, and labels before sending the mutation.
  • Use --dry-run first when a caller needs to verify labels or metadata without creating an issue.
  • Do not create missing labels or workflow states. Stop and report the missing setup instead.
  • Use --optional-label for labels that should be added only when they already exist.
  • Read the created issue back through GraphQL and report the verified result.

Codex Permission Rule

When Codex sandboxing asks for approval because the script needs network access, request a persistent command prefix:

  • sandbox_permissions: require_escalated
  • prefix_rule: ["python3", "linear-create-issue/scripts/create_issue.py"]

Keep the command prefix stable by running from the linear-skills repository root. Pass the API key only through the environment or --env-file; never pass the key as a command argument.

Recommended Commands

python3 scripts/create_issue.py --team LIN --status Backlog --title "Example idea" --description-file /path/to/body.md --label Idea --dry-run
python3 scripts/create_issue.py --team LIN --project "Example Project" --status Backlog --title "Example idea" --description "Short body" --label Idea --optional-label Product --json

Output Shape

  • Text output: resolved target metadata, then created or dry_run.
  • --json output: structured fields for target metadata, created issue, verified issue, action, and error_category.
  • Failure categories are missing_api_key, not_found, ambiguous_lookup, validation, permission_denied, and network.