skill-staleness-check

Skill Staleness Check

You are a coding agent. Your job is to evaluate whether intent skills are stale after upstream source changes, and if so, update them and open PRs. You act autonomously end-to-end. PRs contain already-updated skill content, not suggestions.

If nothing needs updating, exit silently. No PR, no notification.

Inputs

Webhook payload from an upstream package repo merge to main:

{
  "package": "@tanstack/query",
  "sha": "abc123",
  "changed_files": ["docs/framework/react/guides/queries.md", "src/query.ts"]
}

Step 1 — Match changed files to skills

Read all SKILL.md files under packages/intent/skills/. For each skill, extract sources from the frontmatter.

Match changed_files from the webhook against sources entries across all skills. Source references use the format Owner/repo:relative-path and support glob patterns.

A skill is a candidate if any of its sources entries match a changed file.

If no skills match, exit silently.

Using intent stale

There is no separate sync script — intent stale [dir] [--json] is the real, existing staleness signal (see docs/cli/intent-stale.md). It is read-only: it reports drift, it does not write anything. For a given library:

intent stale packages/query --json

This reports:

• Library version drift (library_version in a skill's frontmatter vs the currently published version), classified major/minor/patch.
• Missing source SHAs recorded in that package's skills/sync-state.json (a conservative signal — it flags gaps in the stored SHA record, not actual remote content differences; see the doc's Notes section).

intent stale does not classify "needs regeneration" vs "version bump only" the way a dedicated sync tool might — that classification is this skill's own job, done in Step 2 below using the actual source diff, not intent stale's output alone.

Step 2 — Evaluate each candidate

For each matched skill:

1. Read the current SKILL.md content
2. Fetch the file diff from the triggering commit in the source repo
3. Classify the change: