Linear Skill for OpenClaw

Turn rough ideas into production-ready Linear tickets — with duplicate search, multi-platform research, AI plan-review loops, and human approval before anything ships.

🏪 For the SMB Buyer

"I need my AI to handle project management so I can focus on running my business."

What this does for you

You describe what you want built — in plain English, in Discord, in a voice note, whatever — and your OpenClaw agent turns it into a fully-scoped ticket in Linear. Not a vague one-liner. A real ticket with user stories, acceptance criteria, cost estimates, risk assessment, and a testing plan.

Before anything gets created, your agent shows you a draft and asks for approval. You hit ✅ or ask for changes. That's it.

Why you care

Stop paying for half-baked tickets. Every ticket your contractors or devs pick up is complete on the first pass. No more "what did you actually mean by this?" back-and-forth.
Duplicate detection built in. Before creating anything, it searches your existing Linear backlog. No more accidentally filing the same request three times.
Research happens automatically. It checks GitHub, Reddit, and your own codebase (via Greptile) for prior art. Your tickets arrive with context your team would've spent 15 minutes Googling.
You stay in control. Nothing hits Linear without your explicit approval. Edit, approve, or cancel — your call every time.

What it costs to run

The skill itself uses your existing OpenClaw setup. It calls the Linear API (free tier supports 400 requests/hour — more than enough for any SMB). The optional Codex↔Opus review loop adds ~30–90 seconds per ticket for quality refinement — worth it for anything beyond a quick task.

Bottom line

You get a project manager that never sleeps, never forgets context, and produces consistently high-quality tickets. Your devs spend time building, not deciphering requirements.

🚀 For the Tech Startup

"We move fast and our tickets are a mess. We need consistency without slowing down."

The problem you know too well

Your backlog is a graveyard of one-line tickets nobody can action. "Fix the thing" sits next to a 2000-word epic nobody reads. Half your sprint planning is spent clarifying what tickets actually mean. Your engineers context-switch between writing code and writing requirements, and they resent the latter.

What this changes

The Linear Skill enforces a consistent ticket structure across every ticket type — features, bugs, tasks, OSS contributions — without anyone having to think about templates. Every ticket gets:

User stories with clear personas and goals
Testable acceptance criteria (Given/When/Then)
A mini-PRD (problem, solution, scope, non-goals)
Cost estimate with T-shirt sizing
Risk assessment and dependencies
Research summary from across platforms

For standard and complex work, it runs a Codex↔Opus plan-review loop — Codex (GPT-5.3) generates an implementation plan, Opus (Claude) scores it on a 7-dimension rubric, and they iterate until quality hits 9/10. Your tickets arrive with battle-tested implementation plans.

How it fits your stack

Linear — native GraphQL integration, not a hack on top of the API
GitHub — searches your repos for related issues and PRs
Greptile — semantic code search across your indexed repos (finds relevant code patterns, existing implementations)
Discord — draft approval flow with buttons (approve/edit/cancel)
CI — ships with tests, ShellCheck, gitleaks secret scanning

The multiplier effect

This skill gets better the more you use it. Your agent learns your codebase through Greptile, knows your existing tickets through Linear search, and cross-references community discussions. Ticket #50 is dramatically better than ticket #1 because the context compounds.

What you're not getting (yet)

Sprint planning or backlog prioritization
Ticket updates after creation (create-only for now)
Jira/GitHub Issues support (Linear-only, adapters planned if demand exists)

🏢 For the Enterprise CTO

"I need to understand the governance, security posture, and integration model before I put this anywhere near my team."

Architecture

The skill is a stateless state machine — no running server, no persistent process, no database. It's a set of bash scripts and reference documents read by an OpenClaw agent at runtime. The agent orchestrates the flow; the scripts handle API transport.

Agent (OpenClaw) → SKILL.md (instructions) → scripts/*.sh (tools) → Linear API / Greptile API

State transitions are explicit and auditable:

INTAKE → CLASSIFY → RESEARCH → PLAN → ASSEMBLE → DRAFT → APPROVAL → CREATE → DONE

No ticket is created without passing through APPROVAL. The human gate is architectural, not optional.

Security

Secret management: All credentials (Linear API key, Greptile tokens) live in Infisical and are injected at runtime via infisical run. No secrets in code, config, or environment.
Output sanitization: Every external snippet passes through sanitize-snippet.sh which strips <script> tags, redacts 15+ token patterns (API keys, bearer tokens, AWS credentials, etc.), removes code blocks, and truncates output.
Secret scanning: CI pipeline includes gitleaks. PRs are blocked if secrets are detected.
Rate limiting: Respects Linear's 400 req/hr budget with built-in delays and 429 backoff.
No data persistence beyond drafts: Draft JSONs are stored locally in tmp/ and can be cleaned up. No external data store.

Quality Assurance Model

The Codex↔Opus review loop is an adversarial quality gate:

Dimension	Weight	What it checks
Technical Correctness	20%	Valid APIs, sound patterns, no broken queries
Implementability	20%	Zero ambiguity — any engineer can build from the spec
Completeness	15%	All required areas addressed with concrete detail
Security/Privacy	15%	Secrets handled, auth correct, no data exposure
Edge Cases	10%	Failure modes, error handling, boundary conditions
Testability	10%	Acceptance criteria are measurable and verifiable
Operational Readiness	10%	Rollback, monitoring, migration, deployment plan

Mandatory failure conditions cap the score at 6/10: security vulnerabilities, broken API calls, missing core logic, no error handling, ambiguous specs. The gate is 9/10 to pass.

Integration Points

System	Protocol	Auth	Required?
Linear	GraphQL over HTTPS	API key (Infisical)	Yes
Greptile	REST over HTTPS	API key + GitHub token	No (graceful skip)
GitHub	CLI (`gh`)	OAuth	No (graceful skip)
Discord	OpenClaw message tool	Bot token	For approval flow
Infisical	CLI	Machine identity	Yes (secret injection)

Every external dependency except Linear and Infisical degrades gracefully — missing tools produce warnings, not failures.

Compliance Considerations

All ticket content is generated, reviewed, and approved before creation — full audit trail in draft JSON
No PII processing (unless the user puts PII in their ticket request)
Sanitizer actively strips credentials from research snippets before they're persisted or displayed
Runs on your infrastructure (Mac, Linux) — no SaaS dependency beyond Linear itself

👩‍💻 For the Software Developer

"Show me how it actually works so I can hack on it."

The 30-second version

It's 4 bash scripts, 7 reference docs, and a SKILL.md that tells the OpenClaw agent what to do. The agent reads SKILL.md, follows the state machine, calls the scripts as tools, and handles the conversational parts (intake, classification, draft presentation, approval).

Scripts

linear-api.sh — GraphQL transport wrapper

# Search for duplicates
linear-api.sh --op search --vars '{"q": "dark mode", "first": 10}'

# Create with multiline body from file (jq --rawfile preserves markdown)
linear-api.sh --op create \
  --vars '{"input":{"teamId":"...","title":"Add dark mode"}}' \
  --body-file tmp/body.md

# Custom GraphQL
linear-api.sh --query-file my-query.graphql --vars '{"id": "..."}'

Handles retries (3x with backoff), 429 rate limiting, GraphQL error extraction, and jq ≥ 1.6 validation.

search-context.sh — Multi-source research aggregator

search-context.sh --query "auth middleware" --type feature --team THE --out tmp/context.json \
  --skip-x --skip-discord

Returns a unified JSON blob with results from Linear, Greptile, GitHub, and stub queries for Reddit/X/Discord (agent-mediated). Every source is independently skippable and fails gracefully.

greptile-api.sh — Semantic code search

GREPTILE_API_KEY=... GREPTILE_GITHUB_TOKEN=... GREPTILE_REPOSITORY=owner/repo \
  greptile-api.sh --query "rate limiting middleware" --out tmp/greptile.json

Returns [{repository, filepath, linestart, lineend, summary, distance}].

sanitize-snippet.sh — Security sanitizer

echo "Bearer sk-abc123 <script>alert(1)</script>" | sanitize-snippet.sh --max-chars 500
# → [script removed] [REDACTED] [REDACTED]

Perl multiline pass (scripts, HTML, code blocks) → sed token redaction (15+ patterns) → truncation.

State Machine Flow

The SKILL.md defines allowed transitions. The agent can't skip states — it must go INTAKE → CLASSIFY → RESEARCH → ... in order. The only branch point is CLASSIFY: simple tickets skip PLAN and go straight to ASSEMBLE.

Plan-Review Loop (the interesting part)

For non-trivial tickets:

Agent assembles a prompt from codex-plan-prompt.md + the ticket brief + any prior feedback
Codex CLI generates an implementation plan (file paths, function signatures, API contracts, test strategy)
Agent assembles a scoring prompt from opus-review-prompt.md + scoring-rubric.md + the plan
Opus scores it as JSON: {score, critical_findings, must_fix, nice_to_have, strengths}
If score < 9: must_fix items become "Prior Feedback" for step 1. Loop.
Max 5 iterations. In practice, most converge in 2–3.

Tests

bash tests/test_phase1.sh

5 tests with mock curl/scripts:

Sanitizer redacts tokens + strips <script> tags
Sanitizer replaces multiline fenced code blocks
linear-api.sh --body-file preserves exact multiline markdown (mock curl captures payload)
search-context.sh includes + sanitizes Greptile results
search-context.sh reads searchIssues.nodes correctly

Extending It

Add a new research source: Add a section to search-context.sh between the numbered blocks. Follow the pattern: check availability → call API → merge into $RESULT with jq → add warning on failure.
Add a new ticket section: Update references/ticket-sections.md and the tier table.
Change scoring weights: Edit references/scoring-rubric.md.
Add a new Linear operation: Add a case to linear-api.sh with the GraphQL query.
Customize for your workspace: Update references/linear-api-ref.md with your team prefix, project IDs, and preferred states.

Dependencies

jq >= 1.6 (mandatory), curl, perl, bash. Optional: gh CLI, Infisical CLI, Codex CLI.

📖 For the New Owner — Getting Started

"I just got this. How do I set it up and use it?"

Step 1: Install

Copy the skill into your OpenClaw skills directory:

cp -R skill-linear/ ~/.openclaw/skills/linear/
chmod +x ~/.openclaw/skills/linear/scripts/*.sh

Your OpenClaw agent will auto-discover it from the SKILL.md description.

Step 2: Set Up Secrets

You need a Linear API key. Get one from Linear → Settings → API → Personal API keys.

Store it however your OpenClaw instance manages secrets. The scripts expect LINEAR_API_KEY as an environment variable. If you use Infisical:

infisical secrets set LINEAR_API_KEY=lin_api_xxxxx --env=dev --path=/credentials

Then make sure your agent runs scripts with infisical run --env=dev --path=/credentials -- <command>.

Step 3: Verify It Works

Ask your agent:

Create a test ticket: "Add a hello world endpoint"

You should see it:

Classify as simple / task
Search Linear for duplicates
Build a structured draft
Present it to you for approval
Wait for your ✅ before creating

Step 4: Optional — Enable Greptile (Code Search)

If you want your agent to search your codebase when creating tickets:

Get a Greptile API key from https://app.greptile.com
Index your repos in Greptile

Set these env vars:

GREPTILE_API_KEY=...
GREPTILE_GITHUB_TOKEN=...   # GitHub PAT with repo read access
GREPTILE_REPOSITORY=owner/repo

The skill auto-detects Greptile availability. If the vars aren't set, it skips Greptile with a warning — nothing breaks.

Step 5: Optional — Enable Plan-Review Loop

For standard/complex tickets, the skill uses Codex CLI (GPT-5.3) to generate implementation plans and Opus (Claude) to review them. This requires:

Codex CLI installed and authenticated (codex command available)
Opus available via your OpenClaw model config

If either is missing, the skill falls back to a single-pass draft (still good, just not adversarially reviewed).

Step 6: Use It

Just talk to your agent naturally:

"Create a ticket for adding dark mode to the dashboard"
"File a bug — the sidebar crashes on Safari 18"
"I need a ticket for rate limiting on the API, this is high priority"
"Turn this into a ticket: we need to migrate from Postgres 14 to 16"

The agent handles classification, research, planning, and formatting. You just approve or request changes.

Tips

Be specific about priority — say "urgent" or "this blocks X" and it'll map correctly
Mention the team/project if you have multiple — "create this in the Platform project"
For complex work, let the plan-review loop run — the first Codex draft is usually 6–7/10, but by iteration 3 it's consistently 9+
Review the research summary — sometimes it surfaces duplicates or related work you forgot about
Edit freely — hit ✏️ Edit on the draft and tell your agent what to change. It regenerates without starting over

Troubleshooting

Problem	Fix
"LINEAR_API_KEY is required"	Set the env var or configure Infisical
"jq >= 1.6 required"	`brew install jq` or update your system jq
Greptile results empty	Check that your repo is indexed in Greptile's dashboard
Draft buttons don't work	Known issue (DUDE-85) — type "approve", "edit", or "cancel" instead
Ticket body looks garbled	Make sure you're on jq ≥ 1.6 (--rawfile support)

whistlermike/linear-skill-perspectives.md

Select an option

No results found