docs(review-skill prompt): enforce SKILL.md inline-code trim convention#57
Merged
Conversation
PR #56 codified the convention that SKILL.md inline blocks should be the verification core only and link to examples/ for the full handler. That change updated generate-skill.md and AGENTS.md but not review-skill.md, so running `./scripts/generate-skills.sh review <provider>` on an existing heavy-inline skill wouldn't currently flag the issue. This patch adds two checklist items to the Consistency section of review-skill.md: 1. Inline code is verification-core only (flag full-handler blocks in SKILL.md and propose replacing them with the verification core + an examples pointer). 2. Pointer to examples present (flag if the link block is missing). Includes brief guidance on how to fix a violation cleanly, and points at stripe-webhooks/github-webhooks/shopify-webhooks as the worked pattern. https://claude.ai/code/session_01NNTgQRJss1V7gyzzJ9rjnB
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to PR #56. That PR codified the SKILL.md inline-code trim convention in
AGENTS.md"Content Guidelines" and the generator'sgenerate-skill.mdprompt — but didn't touchreview-skill.md. So./scripts/generate-skills.sh review <provider>wouldn't currently flag the issue when run on an already-merged heavy-inline skill (the existing consistency check "SKILL.md code snippets match example code — no copy-paste drift" passes when they match, regardless of length).This patch adds two checklist items to the Consistency section of
review-skill.mdso review-mode now enforces the convention:SKILL.mdand propose replacing it with the verification core (~10-20 lines per language) plus a pointer toexamples/.Includes brief fix guidance: keep the verification snippet exactly as it appears in the example handler (so the existing "snippets match example code" check still holds), strip the surrounding wiring, replace with the pointer block. Points the reviewer at
stripe-webhooks/github-webhooks/shopify-webhooksas the worked pattern.Test result
Verified end-to-end by running
./scripts/generate-skills.sh review paddle --config providers.yaml --model claude-opus-4-7with this patch applied. The reviewer correctly:skills/paddle-webhooks/SKILL.mdas the convention violationThe resulting trim (
skills/paddle-webhooks/SKILL.md: −97 lines net, 178 → 139 lines) is opened as a separate PR for review.Test plan
IS_SANDBOX=1 ./scripts/generate-skills.sh review paddle --config providers.yaml --model claude-opus-4-7(or any other not-yet-trimmed skill) and confirm:examples/<framework>/stripe,github,shopify) does NOT flag a false positivehttps://claude.ai/code/session_01NNTgQRJss1V7gyzzJ9rjnB
Generated by Claude Code