Skip to content

docs(review-skill prompt): enforce SKILL.md inline-code trim convention#57

Merged
leggetter merged 1 commit into
mainfrom
chore/review-prompt-trim-check
May 11, 2026
Merged

docs(review-skill prompt): enforce SKILL.md inline-code trim convention#57
leggetter merged 1 commit into
mainfrom
chore/review-prompt-trim-check

Conversation

@leggetter
Copy link
Copy Markdown
Collaborator

Summary

Follow-up to PR #56. That PR codified the SKILL.md inline-code trim convention in AGENTS.md "Content Guidelines" and the generator's generate-skill.md prompt — but didn't touch review-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.md so review-mode now enforces the convention:

  1. Inline code is verification-core only — flag any full-handler block in SKILL.md and propose replacing it with the verification core (~10-20 lines per language) plus a pointer to examples/.
  2. Pointer to examples present — flag if the link block is missing, propose adding it with the canonical wording.

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-webhooks as the worked pattern.

Test result

Verified end-to-end by running ./scripts/generate-skills.sh review paddle --config providers.yaml --model claude-opus-4-7 with this patch applied. The reviewer correctly:

  • Identified the full Express + FastAPI handlers in skills/paddle-webhooks/SKILL.md as the convention violation
  • Trimmed them to a "Verification (core)" block with just the HMAC helpers (~30 lines each)
  • Added the canonical "For complete handlers with route wiring, event dispatch, and tests, see..." pointer block
  • Touched only the affected files; preserved the verification logic byte-for-byte against the examples

The resulting trim (skills/paddle-webhooks/SKILL.md: −97 lines net, 178 → 139 lines) is opened as a separate PR for review.

Test plan

  • Run 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:
    • It flags the inline handler as an issue
    • The proposed fix replaces the handler with the verification core + pointer
    • The verification snippet itself still matches examples/<framework>/
  • Confirm running review on an already-trimmed skill (e.g. stripe, github, shopify) does NOT flag a false positive

https://claude.ai/code/session_01NNTgQRJss1V7gyzzJ9rjnB


Generated by Claude Code

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
@leggetter leggetter marked this pull request as ready for review May 11, 2026 17:48
@leggetter leggetter merged commit 57ed0ae into main May 11, 2026
5 checks passed
@leggetter leggetter deleted the chore/review-prompt-trim-check branch May 11, 2026 17:49
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