Project Health Check

Run the scheduled health checks for this project, in order. Each check is independent — if one can't complete (a tool is missing, a command fails, access is denied), report what went wrong and continue to the next check. Never let one failed check abort the rest. Post a short summary at the end covering every check.

Inputs

These are provided when the skill is invoked — don't hardcode them:

Linear team (required for Check 3) — the name or key of the team whose backlog to triage (e.g. a team key like
```
PXL
```
). If it wasn't provided and can't be inferred unambiguously from the project, ask once.
Ticket date cutoff (optional) — ignore tickets created before this date. If not provided, apply no cutoff.

Check 1 — Sync main branch with remote

In the main worktree (not any feature worktree), bring the local

main

branch in sync with

origin/main

via a fast-forward only. Do this regardless of which branch the worktree is currently on or whether it's dirty — a worktree sitting on a feature branch with uncommitted changes is the normal case, not a reason to skip. The mechanism for not disturbing in-progress work is to stash it, sync, and put everything back exactly as it was — not to bail out. A worktree that ends on the same branch it started on, with the same changes restored, has not been disturbed.

The shape of the work, which is safe and reversible throughout:

Remember where the worktree started — its current branch and whether it has uncommitted work — so you can put it back there afterward.
Set the in-progress work aside if the tree is dirty, so
```
main
```
can be checked out cleanly. Use a reversible mechanism (stashing, including untracked files); nothing should be lost.
Get onto
main
and fast-forward it to
```
origin/main
```
. If
```
main
```
has diverged so a fast-forward isn't possible, leave it untouched and note the divergence — then still finish the restore steps so the worktree ends where it started.
Put the worktree back the way you found it — return to the starting branch and reapply the set-aside work.

Restoring the work usually reapplies cleanly. In the case where the worktree started on

main

itself, the changes now reapply on top of the freshly fast-forwarded

main

, which can conflict if upstream touched the same files. Resolve only very simple, unambiguous conflicts automatically. For anything non-trivial or where you're not certain of the right resolution, stop and consult the user — keep their set-aside work preserved and intact, surface the conflict, and don't make risky edits to their uncommitted changes.

Guardrails:

Fast-forward only — never force, reset, or rebase
```
main
```
. If it has diverged, report and move on.
The worktree must end on the same branch it started on, with the same changes present — returning to the branch and reapplying the work are mandatory, not optional. Never discard set-aside work you couldn't cleanly restore.
On success, note whether
```
main
```
moved (and to what SHA), and whether you set work aside / restored it or returned to a non-
```
main
```
branch, so the final summary is concrete.

Check 2 — Refresh installed skills

Update all installed project skills to their latest versions, non-interactively:
```
npx skills update --project --yes
```
. This resolves each skill's source automatically and updates the skill files under
```
.agents/skills
```
(and the skills lock file) in place.
Check whether the refresh changed any skill files or the lock file (e.g. via the version-control status of those paths).
- If nothing changed: note "skills already up to date" and move on.
- If anything changed: create a standalone PR with just those changes — title
```
chore: refresh installed skills
```
  , body listing the updated skills. This is a plain PR — do not run it through the
```
ship
```
  stacked-PR flow. Then surface the list of updated skills and the PR link in the final summary.
Keep this PR completely separate from any feature work in Check 3 — separate branch, separate PR, no shared commits.

Check 3 — Ticket triage and ship

Look at the open tickets in the provided Linear team and pick a good next ticket to work on, then hand it to the

ship

skill.

Filter conflicts before settling on a ticket — exclude any candidate that has:

A dependency /
```
Blocked by
```
relation pointing at unfinished work.
Scope overlap with another Linear issue currently
```
In Progress
```
/
```
In Review
```
.
Overlap with any non-stale open PR — stale = no commits in ~14 days; treat stale PRs as abandoned and therefore not a conflict.
A creation date before the date cutoff, if one was provided.

Always present your proposal and wait for the user's explicit approval before any work begins — never hand a ticket to

ship

on your own initiative, even when the choice seems obvious. Present a recommended next ticket with a one-line rationale, plus 3–5 other candidates with one-line summaries as alternatives, and stop. If there's no suitable actionable ticket at all, say so and skip the ship — don't force one.

Only once the user has explicitly picked or confirmed a ticket, hand it to the

ship

skill and follow that skill's workflow for the rest (worktree, stack, review, merge).

ship

owns all its own approval gates from there.

Summary

End with a brief report covering every check:

Check 1 — main synced (note new SHA if it moved) or "already up to date"; if the worktree was on a feature branch or dirty, note that work was stashed, main synced, and the branch + changes restored; flag any stash-restore conflict left for the user; or report a divergence / what otherwise blocked it.
Check 2 — skills refreshed (list updated skills + PR link) or "already up to date"; or what blocked it.
Check 3 — ticket picked + current ship status; or candidates awaiting a pick; or "no actionable ticket"; or what blocked it.
Anything that needs the user's attention.

project-health-check

NPX Install

Tags

SKILL.md Content