[dpol1]

Summary

• refactor(utilities): slim the authoring skills and teach optimize-skill to rewrite #1331 renamed write-skill's ### Step 5 — Apply the security checklist to ## Step 5 — Secure it, if it reads outside content and moved the rules to security-checklist.md.
  The write-skill/step-5-security-checklist step-config still named the old heading, so load_step_config raised Heading … not found and the suite failed before any case reached a model.
• The step-config now names the new heading and adds security-checklist.md through also_include, as other suites already do, because output-spec.md refers to the checklist's patterns.
• skill-eval <path> --check builds every step's system prompt without running a case, prints one line per fixtures dir whose prompt cannot be built, and exits 1 if there is any.
  The new check-eval-prompts prek hook runs it over tools/skill-evals/evals whenever a Markdown file changes.
  workspace-pytest skips Markdown-only changes, so before this hook a renamed heading passed the PR that renamed it.

Type of change

• Skill change (.claude/skills/<name>/) — eval fixtures updated below
• Tool / bridge contract (tools/<system>/*.md)
• Python package (tools/*/ with pyproject.toml)
• Groovy reference impl
• Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
• Documentation (docs/, README.md, CONTRIBUTING.md)
• Project template (projects/_template/)
• CI / dev loop (prek, workflows, validators)
• Other: one eval step-config (tools/skill-evals/evals/write-skill/step-5-security-checklist/fixtures/step-config.json)

Test plan

• prek run --all-files passes — run as AGENTS.md describes: prek run --all-files --skip workspace-pytest, then workspace-pytest on the changed files; both pass
• For Python packages touched: uv run pytest / ruff check / mypy passes — tools/skill-evals: full suite, ruff check, ruff format --check and the mypy (workspace) hook clean.
  A direct mypy run inside tools/skill-evals reports 8 errors in runner.py (lines 586–609, code this PR does not touch); main reports the same 8.
• For Groovy bridges touched: command-line invocation tested end-to-end
• For skill changes: eval suite passes for the affected skill — not run against a model.
  Print mode now builds every prompt in the tree; before the fix it failed on this step.
• For skill behaviour changes: a new or updated eval fixture is included in this PR — not applicable: no skill behaviour changes
• Other: test_check_reports_a_step_heading_the_skill_no_longer_has in tools/skill-evals/tests/test_runner.py failed before the change (unrecognized arguments: --check) and passes after.
  On the real tree, skill-eval tools/skill-evals/evals --check takes about 1.5 s.
  With the old step-config it exits 1 with one line, …/write-skill/step-5-security-checklist/fixtures: Heading '### Step 5 — Apply the security checklist' not found in …/write-skill/SKILL.md; with the fix it exits 0.

RFC-AI-0004 compliance

No principle touched: the change adds a read-only check and no mutation.

Linked issues

Refs #1331

Notes for reviewers (optional)

• The hook's files: filter matches every .md, not only SKILL.md, because step-configs also extract sections from docs/adapters/codex.md, docs/setup/agentic-overrides.md, tools/asf-nexus/operations.md and tools/dev/preflight-block.md.
• --check catches OSError, ValueError and KeyError: what load_step_config raises for a missing file, a missing heading, a path outside the repo, invalid JSON, or a missing key.

Generative AI disclosure: prepared with Claude Code (Opus 5.5); I reviewed and tested the change.

[potiuk]

Rebinding step 5 to its renamed section and adding --check as a prek gate closes the gap where a renamed heading passes its own PR.

The one open point was that the rebound step-5 suite had not been run against a model: its prompt is now the new Step 5 section plus the whole of security-checklist.md, while the cases' expected.json were written against the old inline checklist. I ran it on this head (1eaa98d7) with magpie-run-evals.sh tools/skill-evals/evals/write-skill/step-5-security-checklist/ (Claude Code, Opus 5): 5 of 5 cases pass, so no expected output needed updating and nothing was pushed to the branch. Approving and merging.

---

This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. The maintainer
approving this PR has read the findings and signed off. If
something feels off, please reply on the PR and a maintainer
will follow up.

More on how Apache Magpie handles maintainer review:
Contributing guide.