skill-best-practices-sync
Check whether the local copies of the skill-authoring best-practice docs (Anthropic, agentskills.io, OpenAI) still match the live pages, refresh the ones that changed, and fold the changes into the distilled best-practices digest. Use when the user wants to check, refresh, update, or sync skill best practices, asks whether the skill guidelines are up to date, or before running a skills audit.
- License 许可
- MIT
- 最近更新
- 2026-10-08
- Stars
- ★ 11
- Forks
- 3
01 前言 Front Matter
- name
- skill-best-practices-sync
- description
- Check whether the local copies of the skill-authoring best-practice docs (Anthropic, agentskills.io, OpenAI) still match the live pages, refresh the ones that changed, and fold the changes into the distilled best-practices digest. Use when the user wants to check, refresh, update, or sync skill best practices, asks whether the skill guidelines are up to date, or before running a skills audit.
02 资源文件 6
- 参考文档references/best-practices.md10.5 KB
- 参考文档references/sources.json2.3 KB
- 参考文档references/sources/agentskills-best-practices.md14.5 KB
- 参考文档references/sources/anthropic-skill-authoring.md41.0 KB
- 参考文档references/sources/openai-build-skills.md10.7 KB
- 参考文档references/sources/openai-codex-best-practices.md13.7 KB
03 SKILL.md 正文
Skill Best Practices Sync
Keep references/best-practices.md — the rubric the skills-audit skill applies — faithful
to its upstream sources. Sources, their fetch URLs, hashes and fetch dates live in
references/sources.json; verbatim copies live in references/sources/<slug>.md.
"Up to date" means content unchanged, not fetched recently: none of the upstream pages expose a version or last-updated date, so the script compares normalized text hashes.
Phase 0 — Check
Run: python3 scripts/sync_sources.py check
One row per source: UNCHANGED, CHANGED, NEW, or FETCH-ERR. Exit code 1 means at least
one source differs. If every row is UNCHANGED, report that and stop — nothing else to do.
FETCH-ERR is not a change. Report it, keep the local copy, and continue with the others.
Phase 1 — Update the local copies
Run: python3 scripts/sync_sources.py update
For each changed source the script prints a unified diff (local → live), overwrites
references/sources/<slug>.md, and records the new hash and timestamp in sources.json.
Read every diff in full — the diffs are the input to Phase 2.
To preview without writing: python3 scripts/sync_sources.py diff [slug].
Phase 2 — Fold changes into the digest
references/best-practices.md is a distilled rubric with a source tag on every rule
([A] Anthropic, [S] agentskills.io, [O1] OpenAI build-skills, [O2] OpenAI Codex
guide). For each diff hunk decide:
- New or changed rule → add or edit the rule under the matching section, keep the tag.
- Removed rule → remove it, or drop the tag if another source still states it.
- Wording-only / navigation / marketing change → no digest edit.
- Two sources now disagree → record it under "Where the sources differ" with both positions.
Keep the digest's shape: MUST for hard validation rules, SHOULD for judgment calls, one line per rule, tags on every line. Do not paste source prose in; distill it.
Phase 3 — Verify
python3 scripts/sync_sources.py check→ allUNCHANGED.- Every rule you touched in the digest still carries a source tag, and the tag's source actually says it (grep the source file).
references/best-practices.mdstill opens with its Contents list and stays under ~250 lines.
Report
## Best-practices sync — <date>
| source | status | lines changed |
|--------|--------|---------------|
### Digest changes
- <rule added / changed / removed, with tag>
### Not folded in (and why)
- <hunk that was navigation noise, marketing, etc.>
If nothing changed: a one-line "All <N> sources unchanged since <last fetched_at>."
Notes & edge cases
- Adding a source: append an entry to
sources.json(slug,title,url,fetch_url,format,relevance,notes,sha256: null,fetched_at: null), pick a new tag letter for the digest, runupdate <slug>, then distill it into the digest. - Markdown endpoints:
platform.claude.com,agentskills.ioandlearn.chatgpt.com/docs/*serve raw markdown via a.mdsuffix. Always prefer that over HTML — it diffs cleanly. - HTML fallback:
format: "html"runs a minimal HTML→text conversion scoped to<article>(then<main>). If a page redesign floods the diff with navigation text, fix the extractor inscripts/sync_sources.py, not the digest. - Noisy diffs: whitespace is normalized before hashing. If a source still flips
between runs with no meaningful change (nonces, timestamps), add a normalization rule
in
normalize()rather than ignoring the source. [O2]is low relevance: only its skills,AGENTS.md, and common-mistakes sections matter. A big diff there is usually not a digest change.- Commits: do not commit; the user decides when the dotfiles repo gets a commit.
04 同仓库更多 Skills
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
python-api
Programmatic Object-Detection-Metrics API guidance for BoundingBox, BoundingBoxes, Evaluator, enums, coordinate conversion, AP/mAP semantics, and source-style import diagnostics.
file-evaluation
Folder-based PASCAL VOC AP/mAP evaluation from ground-truth and detection text files.
object-detection-metrics
Guides legacy Object-Detection-Metrics PASCAL VOC AP/mAP evaluation from detection text folders and direct Python API classes.
nx-workspace-patterns
Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.