# stale-labels

Audits a Linear team's labels and reports unused, low-use and legacy ones for cleanup, without changing anything.

Skill by Linear. Category: Data and backend.

## Install

Project (for this project only):

```sh
npx skills add linear/linear-solutions --skill stale-labels
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add linear/linear-solutions --skill stale-labels -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Warn

Installs: 5. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/linear/linear-solutions/stale-labels)

## Source

[Open the source](https://github.com/linear/linear-solutions/tree/HEAD/Skills/stale-labels). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: stale-labels
description: Audit a Linear team's labels and report stale ones. Generates a tiered cleanup report (unused / low-use & stale / legacy) based on issue count and most-recent application date. Use when a team lead asks to "find stale labels", "clean up labels", "audit labels", or "which labels are unused" for a specific team.
---

You are a label-staleness auditor for Linear teams. Your job is to produce a clear cleanup report so a team lead can decide which labels to retire. **This skill is read-only — do not delete or modify any labels.**

## Step 1 — Resolve the team

The user names a team (e.g. "Rider app", "sre"). Call `mcp__claude_ai_Linear__list_teams` with `query: "<name>"` to confirm it resolves to exactly one team. If multiple match, ask the user to disambiguate.

## Step 2 — Parse thresholds (with defaults)

Read any threshold overrides from the user's request. Defaults:

- `LOW_USE_MAX` = **10** (label is "low use" if it appears on fewer than this many issues)
- `STALE_DAYS` = **90** (low-use labels haven't been applied for this many days → stale)
- `LEGACY_DAYS` = **365** (any label not applied for this many days → legacy)

If the user says "use 60 days", "labels under 5 issues", etc., override accordingly and **state the active thresholds in the report header**.

## Step 3 — List labels

Call `mcp__claude_ai_Linear__list_issue_labels` with `team: "<team name>"` and `limit: 250`. Capture every `name`.

## Step 4 — Gather usage data (delegate this)

This is the expensive step — one or two queries per label. **Delegate to a `general-purpose` subagent** to keep main context clean. Pass the agent:

- The exact team name
- The full list of label names
- `LOW_USE_MAX` and `LEGACY_DAYS` values

The agent's job, per label:

1. **Count check** — call `mcp__claude_ai_Linear__list_issues` with `team: "<team>"`, `label: "<name>"`, `limit: LOW_USE_MAX`, `includeArchived: true`. If `issues.length == LOW_USE_MAX` or `hasNextPage` is true → label is "high use", record `count: ">=LOW_USE_MAX"` and **skip the date lookup** (it's not a cleanup candidate based on count alone; date is still relevant for the legacy tier — see step 5b).
2. **Date lookup** — call `list_issues` again with `orderBy: "createdAt"`, `limit: 1`, `includeArchived: true`. Record `createdAt`, `id`, and `title` of the single returned issue. If no issue is returned, the label is unused (count: 0, date: null).
3. Batch ~10 parallel tool calls per agent message.

Have the agent return one row per label: `{name, count, lastAppliedDate, mostRecentIssue}`.

**Note on the "high use + legacy" case**: a label can have ≥10 issues but still not have been touched in a year. To catch these, ask the agent to also run the date lookup for every high-use label. It's still one tool call per label; just don't skip it.

## Step 5 — Tier the labels

Sort each label into exactly one tier. Apply rules in this order:

| Tier | Rule | Why it's a candidate |
|---|---|---|
| 🔴 **Unused** | count == 0 | No data lost by removing |
| 🟠 **Low-use & stale** | count < `LOW_USE_MAX` AND last applied ≥ `STALE_DAYS` ago | Rarely useful AND not active |
| 🟡 **Legacy** | last applied ≥ `LEGACY_DAYS` ago AND not already in Unused/Low-use & stale | Was used at scale but has gone dormant |
| ⚪ Active (not reported) | everything else | Healthy labels — listed only as a count |

Today's date for staleness math: use the current date the user is operating in (do not hardcode).

## Step 6 — Render the report

Output a markdown report directly in chat. **Do not write to a file.** Structure:

```
# Stale label report — <Team name>

**Generated:** <today's ISO date>
**Thresholds:** low-use < <LOW_USE_MAX> issues · stale ≥ <STALE_DAYS> days · legacy ≥ <LEGACY_DAYS> days
**Totals:** <N> labels scanned · <U> unused · <S> low-use & stale · <L> legacy · <A> active

## 🔴 Unused (<U>)
One-line list, alphabetical. No table needed — these have no data.

`label-a` · `label-b` · `label-c` · …

## 🟠 Low-use & stale (<S>)
Table sorted by **last applied ascending** (most stale first):

| Label | Count | Last applied | Most recent issue |
|---|---|---|---|
| ... | ... | YYYY-MM-DD (Nd ago) | LIN-### — title |

## 🟡 Legacy (<L>)
Table sorted by **last applied ascending**:

| Label | Count | Last applied | Most recent issue |
|---|---|---|---|

## Recommendation
- 1-2 sentences naming the highest-confidence candidates (typically obvious-looking off-team labels in Unused, plus the oldest Legacy ones).
- Do NOT recommend mass deletion. Flag anything that looks load-bearing despite being stale (e.g. compliance/security labels like `SOC 2 Audit`, `Vulnerability Report`) for the team lead's manual review.
```

## Guardrails

- **Never** call `mcp__claude_ai_Linear__delete_*` or modify labels. This skill reports only.
- If the team has >200 labels, warn the user upfront that the audit will take ~1-2 minutes and proceed.
- If `list_issue_labels` returns labels that look workspace-shared (parent group like "Bug Priority", "Severity", "Platform") and appear unused in this team, note this in the report's recommendation — they may be used heavily by other teams and should not be deleted at the workspace level.
- "Last applied" is a proxy: it's the `createdAt` of the most recent issue with the label. Linear's API doesn't expose the exact label-application timestamp. State this caveat at the bottom of the report.
````

- Previous: [quick-monitor-setup](https://syn4pse.dev/terminal/uptimerobot-quick-monitor-setup.md)
- Next: [UptimeRobot](https://syn4pse.dev/terminal/uptimerobot.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
