skill-staleness-check
- Repo stars 291
- Author updated Live
- Author repo intent
- Domain
- Other
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @TanStack · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Node.js
- Permissions
-
- Read-only
- Write / modify
- Network behavior
- External requests
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools，默认拥有全部工具权限。
---
name: skill-staleness-check
description: > You are a coding agent. Your job is to evaluate whether intent skills are stale after upstream…
category: other
runtime: Node.js
---
# skill-staleness-check output preview
## PART A: Task fit
- Use case: > 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 makes outbound network calls; runs on Node.js. Works with Claude Code, Cursor, Cline and 23 more..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “Inputs / Step 1 — Match changed files to skills / Using sync-skills.mjs” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “> 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 makes outbound network calls; runs on Node.js. Works with Claude Code, Cursor, Cline and 23 more.”.
- **02** When the source has headings, the agent prioritizes “Inputs / Step 1 — Match changed files to skills / Using sync-skills.mjs” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files; may access external network resources; usually needs no extra API key.
## Running Rules
- read files, write/modify files; may access external network resources; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options.The source does not require a stable slash command. After installation, invoke the skill by name and describe the task.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files.
Start with a small task and check whether the result follows “Inputs / Step 1 — Match changed files to skills / Using sync-skills.mjs”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: skill-staleness-check
description: > You are a coding agent. Your job is to evaluate whether intent skills are stale after upstream…
category: other
source: TanStack/intent
---
# skill-staleness-check
## When to use
- > You are a coding agent. Your job is to evaluate whether intent skills are stale after upstream source changes, and i…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “Inputs / Step 1 — Match changed files to skills / Using sync-skills.mjs” and keep inference separate from source facts.
- read files, write/modify files; may access external network resources; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies.The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "skill-staleness-check" {
input -> user goal + target files + boundaries + acceptance criteria
context -> Inputs / Step 1 — Match changed files to skills / Using sync-skills.mjs
rules -> SKILL.md triggers / order / output contract
runtime -> Node.js | read files, write/modify files | may access external network resources
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
}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 sync-skills.mjs
The repo includes scripts/sync-skills.mjs for programmatic staleness
detection. For a given library:
node scripts/sync-skills.mjs <library>This checks:
- Source file SHA drift (compares stored SHAs in
sync-state.jsonagainst current remote SHAs via GitHub API) - Library version drift (frontmatter
library_versionvs current published version) - Tree-generator changes (whether the meta skill has been updated since last sync)
Use --report to write a structured staleness_report.yaml:
node scripts/sync-skills.mjs <library> --reportThe report classifies skills as needing regeneration (source changed) or version bump only.
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 skill-generate 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:
node scripts/sync-skills.mjs <library> --bump-version <new-version>This updates library_version in all frontmatter for the library and
records the new version in sync-state.json.
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
After updating, mark the affected skills as synced so future staleness checks have a clean baseline:
# Mark specific skills
node scripts/sync-skills.mjs <library> --mark-synced <skill1> <skill2>
# Mark all skills for a library
node scripts/sync-skills.mjs <library> --mark-synced --allThis updates sync-state.json with current source file SHAs, the
tree-generator SHA, and the sync timestamp.
Step 6 — Open PRs
For each skill (or group of skills) that was updated:
- Create branch:
skill-update/<skill-name>-<short-sha> - Commit updated SKILL.md file(s)
- Open PR with structured body
PR format
Title: skill: update <skill-name> (<package>@<short-sha>)
Body:
### Triggered by
Changes to: <list of source files that matched>
### What changed in the source
<summary of the diff — 2–3 sentences max>
### What changed in the skill
<summary of skill edits — which sections were updated and why>
### Cross-skill impact
<list any downstream skills checked; note if PRs were opened for them>
### Review checklist
- [ ] Skill content is accurate
- [ ] Code examples are complete and copy-pasteable
- [ ] No other skills need corresponding updates
- [ ] Under 500 linesGrouping PRs
- If multiple skills for the same library are affected by the same commit, group them in a single PR
- If a cross-skill update is needed (Step 4), open a separate PR for the downstream skill to keep review scopes clean
- Never mix skills from different libraries in the same PR
No-op behavior
Exit silently (no PR, no notification, no issue) when ANY of these are true:
- No changed files match any skill's
sources - All matched diffs are classified as "no impact" in Step 2
- The sync-skills.mjs report shows all skills are current
Operational notes
GitHub API usage
The sync-skills.mjs script uses the gh CLI for GitHub API access. It
requires:
ghCLI installed and authenticated- Read access to upstream TanStack package repos (query, router, db, form, table)
- Write access to the intent repo for creating branches and PRs
Rate limiting
When checking multiple libraries or many source files, the script makes
one API call per source file per skill. For large batches, the GitHub API
rate limit (5000 requests/hour for authenticated users) may apply. The
script does not currently batch or cache API responses — if this becomes
an issue, add caching at the getRemoteFileSha level.
Manual triggering
Maintainers can run staleness detection manually:
# Check a specific library
node scripts/sync-skills.mjs db
# Check and write a report
node scripts/sync-skills.mjs db --report
# After reviewing and regenerating, mark as synced
node scripts/sync-skills.mjs db --mark-synced --allConstraints
| Rule | Detail |
|---|---|
| Silent when nothing changes | No noise — exit cleanly if no updates needed |
| Surgical updates over full rewrites | Only change sections affected by the diff |
| One cascade level | Cross-skill checks go one level deep, not recursive |
| PRs scoped to one library | Never mix libraries in a single PR |
| Version bumps are separate from content updates | A version-only bump doesn't require regeneration |
| Commit messages include co-author | Include the coding agent's co-author tag |
Decide Fit First
Design Intent
How To Use It
Boundaries And Review