Skip to content

chore(skills): add reference TOC sync script, pre-commit hook, and CI check - #45

Merged
ssbushi merged 4 commits into
mainfrom
sb/toc-sync-tooling
Nov 6, 2026
Merged

ssbushi merged 4 commits into
mainfrom
sb/toc-sync-tooling

Conversation

@ssbushi

@ssbushi ssbushi commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator

Follow-up to #44.

Adds zero-dependency Python 3 stdlib tooling to keep reference Tables of Contents and skill markdown files in sync before downstream import:

  • scripts/sync_tocs.py: regenerates - [Title](#anchor): Lines start-end entries on skills/*/references/*.md files over 100 lines (and removes them when files shrink to 100 lines or fewer), skips CommonMark fenced code blocks, and checks fence balance, Caution: LeakR keywords, and SKILL.md frontmatter (name, description <= 1024 UTF-8 bytes).
  • .githooks/pre-commit: runs python3 scripts/sync_tocs.py --staged to update and restage drifted reference TOCs on commit (enable locally with git config core.hooksPath .githooks).
  • .github/workflows/validate-skills.yml and scripts/test_sync_tocs.py: runs hermetic unittest coverage and python3 scripts/sync_tocs.py --check on pushes and pull requests to main.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a pre-commit hook and a Python script (sync_tocs.py) with accompanying unit tests to deterministically generate Table of Contents (TOC) and validate markdown hygiene for skills. The reviewer feedback highlights several key areas for improvement, including fixing a YAML parsing bug with empty lines in block scalars, preventing false positives in the Caution: keyword check by ignoring fenced code blocks, handling OSError when executing git commands, ensuring cross-platform path consistency on Windows using .as_posix(), and removing a non-hermetic unit test that checks the active workspace.

Comment thread scripts/sync_tocs.py Resolved
Comment thread scripts/sync_tocs.py Resolved
Comment thread scripts/sync_tocs.py Resolved
Comment thread scripts/sync_tocs.py Resolved
Comment thread scripts/sync_tocs.py Resolved
Comment thread scripts/test_sync_tocs.py Resolved
Base automatically changed from sb/python-skill-review-cl-1014958313 to main November 6, 2026 15:56
@ssbushi ssbushi changed the title tooling(skills): add deterministic reference TOC sync, pre-commit hook, and CI check chore(skills): add reference TOC sync script, pre-commit hook, and CI check Nov 6, 2026
@ssbushi
ssbushi force-pushed the sb/toc-sync-tooling branch from b3a849d to f89564b Compare November 6, 2026 16:20
@ssbushi
ssbushi requested a review from pavelgj November 6, 2026 17:18
@ssbushi
ssbushi merged commit 44aa9c9 into main Nov 6, 2026
8 checks passed
@ssbushi
ssbushi deleted the sb/toc-sync-tooling branch November 6, 2026 20:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants