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.mdlinear-create-issue/SKILL.md
GitHubLinear 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_KEYis 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/graphqlis 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-runfirst 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-labelfor 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_escalatedprefix_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
createdordry_run. --jsonoutput: structured fields for target metadata, created issue, verified issue, action, anderror_category.- Failure categories are
missing_api_key,not_found,ambiguous_lookup,validation,permission_denied, andnetwork.