AGENT SKILL

ams-linear-api-automation

暂无简介

License 许可
MIT
所属仓库
TanNhatCMS/jarvis
最近更新
2026-11-07
Stars
★ 0
Forks
1

03 SKILL.md 正文

Linear API Automation

Overview

Linear's GraphQL API exposes issues, projects, cycles, teams, users, and comments — everything the UI does, scriptable.

Use cases: bulk issue management, custom triage, syncing with GitHub/Sentry/CRMs, reporting beyond Linear's views, and enforcing conventions.

This skill uses Linear's native GraphQL API directly — scripts you control, no middleware required.

When to use

  • Bulk creating, updating, or triaging Linear issues
  • Custom reports and exports from Linear data
  • Syncing Linear with GitHub, Sentry, or other tools
  • Enforcing labeling and workflow conventions
  • Automating issue lifecycle (stale, assignment, prioritization)

Core concepts

  • GraphQL API. Single endpoint, typed schema, efficient nested queries. Use the playground/docs to explore; generate typed clients where it pays off.
  • API keys. Personal API keys per automation (service account where possible). Scoped by the key owner's permissions — least privilege.
  • Issues core. Create, update, comment, label, assign, set priority/status, link (blocks/related/duplicate). Most automation lives here.
  • Cycles and projects. Query active cycles, move issues between cycles, track project progress programmatically.
  • Webhooks. Real-time events (issue created/updated) to your endpoint. For reactive automation; API polling for periodic jobs.
  • Rate limits. Linear enforces rate limits; batch operations and back off on errors. Bulk work: pace requests, don't hammer.
  • Teams and workflows. Team IDs, workflow states per team — states differ by team, so resolve state IDs dynamically, don't hardcode.
  • Idempotency. Check-before-create for synced issues; dedupe keys in descriptions or external IDs. Re-runs must be safe.

Practical workflow

  1. Define the automation. What Linear objects, what operations, what trigger? Write the equivalent manual flow first.
  2. Set up auth. API key for a service account with minimal team access. Secrets manager; never in code.
  3. Explore the schema. Use the GraphQL playground to shape queries/mutations. Resolve team IDs, state IDs, label IDs dynamically.
  4. Prototype small. Test mutations on a test team/project with 2-3 issues. Verify states, labels, notifications.
  5. Build idempotent scripts. Check-before-create, upsert patterns, external ID tracking for synced items.
  6. Wire triggers. Webhooks for real-time; scheduled scripts for periodic (triage, stale, reports). Log every run.
  7. Respect limits. Pace bulk operations; exponential backoff on errors; cache team/state metadata.
  8. Document. README: purpose, scope, auth, schedule, what it changes, how to disable. Future maintainers need the map.

Common pitfalls

  • Hardcoded state IDs. Workflow states differ per team and change. Resolve dynamically by name; never hardcode IDs.
  • No idempotency. Sync scripts creating duplicate issues on re-run. Check-before-create with external IDs.
  • Rate limit hammering. Bulk updates in tight loops hitting limits and failing halfway. Pace + backoff.
  • Overprivileged keys. Personal key with admin everywhere for a triage script. Service account, minimal teams.
  • Notification storms. Bulk operations pinging everyone. Use quiet options where available; batch during off-hours for big jobs.
  • Polling when webhooks fit. Cron every minute for events webhooks push instantly. Match mechanism to need.
  • Ignoring team differences. One script assuming all teams share workflow states. Linear teams customize — handle per-team.
  • No disable path. Automation misbehaving, nobody knows how to stop it. Document the off switch; keep key access handy.

04 同仓库更多 Skills

TanNhatCMS
TanNhatCMS/jarvis

web-scrape

Turn web pages into LLM-ready markdown via the Firecrawl API (renders JS, anti-bot handling). Use when browser_open/fetch fails on JS-heavy pages, or when you need clean markdown/structured extraction from a site. Requires FIRECRAWL_API_KEY.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

design-taste-frontend

tasteskill v2, the anti-slop frontend skill. Art direction for websites, distilled from a study of 247 curated gallery sites (One Page Love, Awwwards Sites of the Day). Deals researched directions (idea, composition, type, palette, photographs, section blueprints) from a library, enforces a strict no-slop house style with a real-browser inspector, and runs a look-and-fix loop on screenshots. Use this whenever you build, design, redesign, restyle, polish or review a landing page, marketing site, portfolio, product page, one-pager, hero or any public-facing web page, in any stack (HTML/CSS, React, Next.js, Vue, Svelte, Astro, Tailwind) — also when the user says a page looks generic, templated, "AI-made", sloppy, or asks to make it look designed, premium, award-level or less like every other site. Not for dashboards or app screens.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

test-driven-development

Use when implementing any feature or bugfix, before writing implementation code

★ 0
TanNhatCMS
TanNhatCMS/jarvis

systematic-debugging

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

★ 0
TanNhatCMS
TanNhatCMS/jarvis

requesting-code-review

Use when completing tasks, implementing major features, or before merging to verify work meets requirements

★ 0
TanNhatCMS
TanNhatCMS/jarvis

brainstorming

You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).

★ 0