ams-linear-api-automation
暂无简介
- License 许可
- MIT
- 最近更新
- 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
- Define the automation. What Linear objects, what operations, what trigger? Write the equivalent manual flow first.
- Set up auth. API key for a service account with minimal team access. Secrets manager; never in code.
- Explore the schema. Use the GraphQL playground to shape queries/mutations. Resolve team IDs, state IDs, label IDs dynamically.
- Prototype small. Test mutations on a test team/project with 2-3 issues. Verify states, labels, notifications.
- Build idempotent scripts. Check-before-create, upsert patterns, external ID tracking for synced items.
- Wire triggers. Webhooks for real-time; scheduled scripts for periodic (triage, stale, reports). Log every run.
- Respect limits. Pace bulk operations; exponential backoff on errors; cache team/state metadata.
- 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
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.
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.
test-driven-development
Use when implementing any feature or bugfix, before writing implementation code
systematic-debugging
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
requesting-code-review
Use when completing tasks, implementing major features, or before merging to verify work meets requirements
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).