skill-staleness-check

Name: skill-staleness-check
Author: TanStack

314stars19forks

How to install skill-staleness-check?

tanstack/intent/skill-staleness-check

$npx -y skills add TanStack/intent --skill skill-staleness-check

Installs into the current project.

Summary

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 skill-generate, checks cross-skill references, and ope

Files · 1

View on GitHub

SKILL.md

1	# Skill Staleness Check
2
3	You are a coding agent. Your job is to evaluate whether intent skills are
4	stale after upstream source changes, and if so, update them and open PRs.
5	You act autonomously end-to-end. PRs contain already-updated skill
6	content, not suggestions.
7
8	If nothing needs updating, exit silently. No PR, no notification.
9
10	---
11
12	## Inputs
13
14	Webhook payload from an upstream package repo merge to main:
15
16	```json
17	{
18	"package": "@tanstack/query",
19	"sha": "abc123",
20	"changed_files": ["docs/framework/react/guides/queries.md", "src/query.ts"]
21	}
22	```
23
24	---
25
26	## Step 1 — Match changed files to skills
27
28	Read all SKILL.md files under `packages/intent/skills/`. For each skill,
29	extract `sources` from the frontmatter.
30
31	Match `changed_files` from the webhook against `sources` entries across all
32	skills. Source references use the format `Owner/repo:relative-path` and
33	support glob patterns.
34
35	A skill is a candidate if any of its `sources` entries match a changed
36	file.
37
38	If no skills match, exit silently.
39
40	### Using `intent stale`
41
42	There is no separate sync script — `intent stale [dir] [--json]` is the real,
43	existing staleness signal (see `docs/cli/intent-stale.md`). It is read-only:
44	it reports drift, it does not write anything. For a given library:
45
46	```bash
47	intent stale packages/query --json
48	```
49
50	This reports:
51
52	- Library version drift (`library_version` in a skill's frontmatter vs the
53	currently published version), classified `major`/`minor`/`patch`.
54	- Missing source SHAs recorded in that package's `skills/sync-state.json`
55	(a conservative signal — it flags gaps in the stored SHA record, not
56	actual remote content differences; see the doc's Notes section).
57
58	`intent stale` does not classify "needs regeneration" vs "version bump only"
59	the way a dedicated sync tool might — that classification is this skill's own
60	job, done in Step 2 below using the actual source diff, not `intent stale`'s
61	output alone.
62
63	---
64
65	## Step 2 — Evaluate each candidate
66
67	For each matched skill:
68
69	1. Read the current SKILL.md content
70	2. Fetch the file diff from the triggering commit in the source repo
71	3. Classify the change:
72
73	\| Classification \| Criteria \| Action \|
74	\| --------------------- \| --------------------------------------------------------------------------------------------- \| ------------------------------------------- \|
75	\| No impact \| Diff is typo fix, comment change, test-only, or internal refactor with no API/behavior change \| Skip — no update needed \|
76	\| Version bump only \| Diff changes version numbers, dependency ranges, or metadata but no documented behavior \| Bump `library_version` in frontmatter \|
77	\| Content update \| Diff changes API shape, behavior, defaults, types, or patterns that the skill documents \| Rewrite affected sections \|
78	\| Breaking change \| Diff removes, renames, or fundamentally changes an API the skill documents \| Rewrite + add old pattern as Common Mistake \|
79
80	### Two-pass classification
81
82	Pass 1 — Quick scan: Read the diff summary (files changed, insertions,
83	deletions). Identify which skill sections could be affected.
84
85	Pass 2 — Detail evaluation: For each potentially affected section, read
86	the full diff hunks and compare against the skill content. Determine if the
87	change actually affects what the skill documents.
88
89	This prevents over-updating. A 200-line diff to a source file may only
90	affect one line of one skill, or none at all.
91
92	---
93
94	## Step 3 — Update stale skills
95
96	For skills classified as needing content updates:
97
98	1. Load the skill-generate meta skill
99	2. Provide it with:
100	- The existing SKILL.md content
101	- The source diff
102	- The current source documentation (fetch the updated file)
103	3. Use regeneration mode (surgical update, not full rewrite)
104	4. Validate the updated skill against all checks
105
106	For version bump only:
107
108	There is no write-capable script for this. Edit `library_version` directly
109	in each affected skill's frontmatter, then update the recorded SHA(s) for
110	that library in its `skills/sync-state.json` (see Step 5) to reflect the new
111	synced state.
112
113	---
114
115	## Step 4 — Check cross-skill references
116
117	After updating skills in Step 3, check f

People who liked this also viewed

6 picks

Type

skill-staleness-check

314stars19forks

View on GitHub

How to install skill-staleness-check?

tanstack/intent/skill-staleness-check

$npx -y skills add TanStack/intent --skill skill-staleness-check

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Skill Staleness Check
2
3	You are a coding agent. Your job is to evaluate whether intent skills are
4	stale after upstream source changes, and if so, update them and open PRs.
5	You act autonomously end-to-end. PRs contain already-updated skill
6	content, not suggestions.
7
8	If nothing needs updating, exit silently. No PR, no notification.
9
10	---
11
12	## Inputs
13
14	Webhook payload from an upstream package repo merge to main:
15
16	```json
17	{
18	"package": "@tanstack/query",
19	"sha": "abc123",
20	"changed_files": ["docs/framework/react/guides/queries.md", "src/query.ts"]
21	}
22	```
23
24	---
25
26	## Step 1 — Match changed files to skills
27
28	Read all SKILL.md files under `packages/intent/skills/`. For each skill,
29	extract `sources` from the frontmatter.
30
31	Match `changed_files` from the webhook against `sources` entries across all
32	skills. Source references use the format `Owner/repo:relative-path` and
33	support glob patterns.
34
35	A skill is a candidate if any of its `sources` entries match a changed
36	file.
37
38	If no skills match, exit silently.
39
40	### Using `intent stale`
41
42	There is no separate sync script — `intent stale [dir] [--json]` is the real,
43	existing staleness signal (see `docs/cli/intent-stale.md`). It is read-only:
44	it reports drift, it does not write anything. For a given library:
45
46	```bash
47	intent stale packages/query --json
48	```
49
50	This reports:
51
52	- Library version drift (`library_version` in a skill's frontmatter vs the
53	currently published version), classified `major`/`minor`/`patch`.
54	- Missing source SHAs recorded in that package's `skills/sync-state.json`
55	(a conservative signal — it flags gaps in the stored SHA record, not
56	actual remote content differences; see the doc's Notes section).
57
58	`intent stale` does not classify "needs regeneration" vs "version bump only"
59	the way a dedicated sync tool might — that classification is this skill's own
60	job, done in Step 2 below using the actual source diff, not `intent stale`'s
61	output alone.
62
63	---
64
65	## Step 2 — Evaluate each candidate
66
67	For each matched skill:
68
69	1. Read the current SKILL.md content
70	2. Fetch the file diff from the triggering commit in the source repo
71	3. Classify the change:
72
73	\| Classification \| Criteria \| Action \|
74	\| --------------------- \| --------------------------------------------------------------------------------------------- \| ------------------------------------------- \|
75	\| No impact \| Diff is typo fix, comment change, test-only, or internal refactor with no API/behavior change \| Skip — no update needed \|
76	\| Version bump only \| Diff changes version numbers, dependency ranges, or metadata but no documented behavior \| Bump `library_version` in frontmatter \|
77	\| Content update \| Diff changes API shape, behavior, defaults, types, or patterns that the skill documents \| Rewrite affected sections \|
78	\| Breaking change \| Diff removes, renames, or fundamentally changes an API the skill documents \| Rewrite + add old pattern as Common Mistake \|
79
80	### Two-pass classification
81
82	Pass 1 — Quick scan: Read the diff summary (files changed, insertions,
83	deletions). Identify which skill sections could be affected.
84
85	Pass 2 — Detail evaluation: For each potentially affected section, read
86	the full diff hunks and compare against the skill content. Determine if the
87	change actually affects what the skill documents.
88
89	This prevents over-updating. A 200-line diff to a source file may only
90	affect one line of one skill, or none at all.
91
92	---
93
94	## Step 3 — Update stale skills
95
96	For skills classified as needing content updates:
97
98	1. Load the skill-generate meta skill
99	2. Provide it with:
100	- The existing SKILL.md content
101	- The source diff
102	- The current source documentation (fetch the updated file)
103	3. Use regeneration mode (surgical update, not full rewrite)
104	4. Validate the updated skill against all checks
105
106	For version bump only:
107
108	There is no write-capable script for this. Edit `library_version` directly
109	in each affected skill's frontmatter, then update the recorded SHA(s) for
110	that library in its `skills/sync-state.json` (see Step 5) to reflect the new
111	synced state.
112
113	---
114
115	## Step 4 — Check cross-skill references
116
117	After updating skills in Step 3, check f

People who liked this also viewed

6 picks

Type