skill-staleness-check
Evaluate intent skills for staleness when source files change in upstream TanStack package repos. Matches changed files against metadata.sources, evaluates whether diffs affect documented behavior, rewrites stale skills using generate-skill, checks cross-skill references, and opens PRs. Silent when nothing needs updating.
TanStack · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add TanStack/intent --skill skill-staleness-check技能说明
name: skill-staleness-check description: > Evaluate intent skills for staleness when source files change in upstream TanStack package repos. Matches changed files against metadata.sources, evaluates whether diffs affect documented behavior, rewrites stale skills using generate-skill, checks cross-skill references, and opens PRs. Silent when nothing needs updating. metadata: version: '1.0' category: meta-tooling input_artifacts: 'webhook payload (package name, commit SHA, changed files)' output_artifacts: 'updated SKILL.md files; pull requests' skills: 'generate-skill; tree-generator'
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_versionin a skill's frontmatter vs the currently published version), classifiedmajor/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:
- Read the current SKILL.md content
- Fetch the file diff from the triggering commit in the source repo
- Classify the change:
| Classification | Criteria | Action |
|---|---|---|
| No impact | Diff is typo fix, comment change, test-only, or internal refactor with no API/behavior change | Skip — no update needed |
| Version bump only | Diff changes version numbers, dependency ranges, or metadata but no documented behavior | Bump library_version in frontmatter |
| Content update | Diff changes API shape, behavior, defaults, types, or patterns that the skill documents | Rewrite affected sections |
| Breaking change | Diff removes, renames, or fundamentally changes an API the skill documents | Rewrite + add old pattern as Common Mistake |
Two-pass classification
Pass 1 — Quick scan: Read the diff summary (files changed, insertions, deletions). Identify which skill sections could be affected.
Pass 2 — Detail evaluation: For each potentially affected section, read the full diff hunks and compare against the skill content. Determine if the change actually affects what the skill documents.
This prevents over-updating. A 200-line diff to a source file may only affect one line of one skill, or none at all.
Step 3 — Update stale skills
For skills classified as needing content updates:
- Load the generate-skill meta skill
- Provide it with:
- The existing SKILL.md content
- The source diff
- The current source documentation (fetch the updated file)
- Use regeneration mode (surgical update, not full rewrite)
- Validate the updated skill against all checks
For version bump only:
There is no write-capable script for this. Edit library_version directly
in each affected skill's frontmatter, then update the recorded SHA(s) for
that library in its skills/sync-state.json (see Step 5) to reflect the new
synced state.
Step 4 — Check cross-skill references
After updating skills in Step 3, check for cross-skill staleness:
- For each skill that was updated, read its
name - Scan all other skills for
requiresentries orsourcesthat reference the updated skill - For each skill that references an updated skill, evaluate whether the update makes the referencing skill stale or inconsistent
- If stale → update using the same process as Step 3
- If not → skip
This cascade is bounded to one level. Skills that reference a second-order dependency are not automatically re-checked.
Step 5 — Mark skills as synced
There is no write-capable script for this either. After updating a skill,
edit that library's skills/sync-state.json directly: update
library_version and the affected skill's skills[skillName].sources_sha
map with the new source file SHA(s) from the commit that triggered this run.
(That is the real current shape read by intent stale — it has no separate
tree-generator SHA or sync-timestamp field, despite what an earlier version
of this doc implied.)