技能陈旧性检查
- 作者仓库星标 291
- 作者仓库 intent
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @TanStack · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- Node.js
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
第 1 步 — 将更改的文件与技能进行匹配
阅读`packages/intent/skills/`下的所有SKILL.md文件。对于每项技能,从 frontmatter 中提取`sources`。将 webhook 中的 `changed_files` 与所有技能的 `sources` 条目进行匹配。源参考使用格式`Owner/repo:relative-path`并支持全局模式。
第 2 步 — 评估每位候选人
对于每个匹配的技能: 读取当前 SKILL.md 内容 从源存储库中的触发提交中获取文件差异 对更改进行分类:分类 · 标准 · 操作
第 3 步 — 更新过时的技能
对于分类为需要内容更新的技能:加载技能生成元技能为其提供:现有的 SKILL.md 内容源差异
第 4 步 — 检查跨技能参考资料
在步骤 3 中更新技能后,检查跨技能的陈旧性: 对于每项更新的技能,阅读其 `name` 扫描所有其他技能,查找引用更新技能的 `requires` 条目或 `sources` 对于引用更新技能的每项技能,评估是否
第 5 步 — 将技能标记为已同步
更新后,将受影响的技能标记为已同步,以便将来的过时性检查有一个干净的基线:这会使用当前源文件 SHA、树生成器 SHA 和同步时间戳更新`sync-state.json`。
第 6 步 — 公开 PR
对于更新的每项技能(或技能组): 创建分支:`skill-update/<skill-name>-<short-sha>` 提交更新的 SKILL.md 文件 使用结构化主体打开 PR
# 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:
```json
{
"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:
```bash
node scripts/sync-skills.mjs <library>
```
This checks:
- Source file SHA drift (compares stored SHAs in `sync-state.json` against
current remote SHAs via GitHub API)
- Library version drift (frontmatter `library_version` vs 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`:
```bash
node scripts/sync-skills.mjs <library> --report
```
The report classifies skills as needing regeneration (source changed) or
version bump only.
---
## 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:
| 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:
1. Load the skill-generate meta skill
2. Provide it with:
- The existing SKILL.md content
- The source diff
- The current source documentation (fetch the updated file)
3. Use regeneration mode (surgical update, not full rewrite)
4. Validate the updated skill against all checks
For version bump only:
```bash
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:
1. For each skill that was updated, read its `name`
2. Scan all other skills for `requires` entries or `sources` that reference
the updated skill
3. For each skill that references an updated skill, evaluate whether the
update makes the referencing skill stale or inconsistent
4. If stale → update using the same process as Step 3
5. 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:
```bash
# 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 --all
```
This 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:
1. Create branch: `skill-update/<skill-name>-<short-sha>`
2. Commit updated SKILL.md file(s)
3. Open PR with structured body
### PR format
**Title:** `skill: update <skill-name> (<package>@<short-sha>)`
**Body:**
```markdown
### 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 lines
```
### Grouping 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:
- `gh` CLI 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:
```bash
# 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 --all
```
---
## Constraints
| 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 |
章节与文件索引
按说明文件中的顺序排列。
输入
第 1 步 — 将更改的文件与技能进行匹配
使用sync-skills.mjs
第 2 步 — 评估每位候选人
两遍分类
文件/命令 -> packages/intent/skills/ · sources · changed_files · Owner/repo:relative-path · scripts/sync-skills.mjs · sync-state.json · library_version · --report
内容校验值 -> 2beaed624c22
当前原文的自动摘译,尚未人工审校。
输入
来自上游包存储库的 Webhook 负载合并到 main:
使用sync-skills.mjs
该存储库包含用于程序化陈旧性检测的
scripts/sync-skills.mjs。对于给定的库:这会检查: 源文件 SHA 漂移(通过 GitHub API 将sync-state.json中存储的 SHA 与当前远程 SHA 进行比较)两遍分类
第 1 遍 — 快速扫描:阅读差异摘要(更改的文件、插入、删除)。确定哪些技能部分可能受到影响。第 2 步 — 详细评估:对于每个可能受影响的部分,阅读完整的差异块并与技能内容进行比较。确定更改是否确实影响技能文档的内容。