Skip to content

Add README snippet verification hook and skill#38

Open
jssmith wants to merge 11 commits intomainfrom
readme-snippet-hook
Open

Add README snippet verification hook and skill#38
jssmith wants to merge 11 commits intomainfrom
readme-snippet-hook

Conversation

@jssmith
Copy link
Copy Markdown
Collaborator

@jssmith jssmith commented Jan 22, 2026

Summary

  • Add pre-commit hook that verifies README code snippets match source files
  • Add /check-readme-snippets skill for interactive checking and fixing

Components

File Purpose
scripts/verify_readme_snippets.py Verification script (runs as hook)
.claude/settings.json Hook config (PostToolUse on Edit/Write, PreToolUse on Bash)
.claude/commands/check-readme-snippets.md Interactive skill

How it works

Hook (automatic):

  • Fires on Edit/Write to Python files - warns if edited file's README snippet is stale
  • Fires on Edit/Write to README files - warns if snippets don't match sources
  • Fires on git commit commands - blocks commit (exit 2) if staged files have mismatched snippets

Skill (interactive):

  • Run /check-readme-snippets to see mismatches
  • Choose sync direction: update README or revert source
  • Claude makes the fix

Annotations supported

  • *File: path/to/file.py* - full file match required
  • *File: path/to/file.py (excerpt)* - substring match

Test plan

  • Hook blocks commits when README snippets don't match source
  • Hook passes when snippets match
  • Hook exits quickly for non-commit bash commands
  • Post-edit warnings appear for Python and README files
  • Skill identifies mismatches and offers to fix

🤖 Generated with Claude Code

jssmith and others added 6 commits January 22, 2026 12:40
- Use SimplePlugin with data_converter callback (correct API)
- Remove unused aws_profile parameter from ClaimCheckCodec
- Require temporalio>=1.19.0 (for SimplePlugin support)
- Require python>=3.10 (required by temporalio 1.19+)
- Update README code example to match implementation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
SimplePlugin accepts either a DataConverter instance or a callable.
The direct approach is simpler and sufficient for this use case.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Verifies that code snippets in README files match their source files
before allowing commits. Checks only changed Python files.

Annotations:
- *File: path/to/file.py* - full file match required
- *File: path/to/file.py (excerpt)* - substring match

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Interactive skill that:
- Finds README snippets with file annotations
- Compares them to source files
- Reports mismatches
- Offers to fix them automatically

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Now asks user whether to:
- Update README to match source (source is correct)
- Update source to match README (revert unwanted changes)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jssmith jssmith marked this pull request as draft January 23, 2026 18:42
jssmith and others added 5 commits January 28, 2026 09:59
- PostToolUse on Edit/Write for .py: warns if README snippet is stale
- PostToolUse on Edit/Write for .md: warns if snippets don't match source
- PreToolUse on Bash for git commit: blocks if staged files have mismatches

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jssmith jssmith marked this pull request as ready for review January 29, 2026 03:28
@jssmith
Copy link
Copy Markdown
Collaborator Author

jssmith commented Jan 29, 2026

README sync issues are fixed in #43

@jssmith jssmith assigned jssmith and unassigned jssmith Jan 29, 2026
@webchick webchick added the sdk: python Example using Python label Apr 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

sdk: python Example using Python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants