microsoft-foundry Cookbook Review Skill
Review Forgebook recipes as runnable lessons, not as API demos. A good recipe teaches one transferable Microsoft Foundry pattern with a thesis, evidence, and a takeaway artifact the reader can reuse tomorrow.
Use this skill in read-only review mode by default. Do not edit notebooks or registry files unless the user explicitly asks you to apply fixes.
Review contract
Every review should answer:
- Can the reader run this top-to-bottom?
- Can the reader tell what pattern they are learning in the first 30 seconds?
- Does the recipe teach one reusable decision, or does it drift into a feature tour?
- Is there evidence that the technique worked?
- Does the reader leave with a copyable artifact, template, command, or pattern?
Load these references as needed:
| Need | Read |
|---|---|
| Full scoring criteria | references/rubric-detail.md |
| Forgebook registry, author, tag, media, and notebook rules | references/forgebook-contract.md |
| Dev-to-dev voice, banned AI phrases, concision rules | references/writing-quality.md |
| How to write findings and severity labels | references/review-comment-style.md |
| Final report shape | assets/review-report-template.md |
Intake
Start by identifying the review target:
- Notebook review: a
.ipynbfile, notebook diff, or rendered notebook page. - Registry review: a
registry.yamlentry or cookbook metadata. - Publication review: full PR/content readiness, including notebook, registry, authors, tags, media/data paths, and narrative quality.
- Writing-only review: prose voice, AI-isms, structure, and clarity.
If the user did not specify scope, assume publication review for new recipes and changed-content review for PR diffs.
Before scoring, state a short hypothesis:
Hypothesis: This is a [quickstart/tutorial/deep-dive/demo/reference] for [beginner/intermediate/expert] readers.
Success criterion: After running it, the reader should be able to [do one concrete thing].
Confidence: [high/medium/low] based on [title/imports/sections/registry entry].
Ask at most one clarifying question only if the answer would change the verdict. Otherwise proceed with reasonable assumptions and list them in the report.
Workflow
Phase 1: Mechanical gates
Check the fast, objective rules first. In the Forgebook repository, use the optional script when possible:
python .agents/skills/cookbook-review/scripts/recipe-health-check.py <notebook.ipynb> --repo-root .
Mechanical gates:
- Registry fields are valid when a registry entry is present.
- Notebook path starts with
notebooks/and ends with.ipynb. - Slug follows
^[a-z0-9]+(?:-[a-z0-9]+)*$. - Authors exist in
authors.yamlwithnameandtitle. - Tags exist in
tags.yaml. - Notebook does not start with
# H1; the page title comes fromregistry.yaml. - Notebook contains no site-specific publishing metadata.
- Media references use
media/<slug>/...; data references usedata/<slug>/.... - Code cells are not bare code dumps: each should be introduced by a directive, explained by nearby prose, or produce meaningful output.
Treat mechanical failures as high-signal. Do not bury them under style feedback.
Phase 2: Ten-axis recipe score
Score against the ten qualities in references/rubric-detail.md. Use the default weights unless the user asks for pass/fail only:
| Axis | Weight |
|---|---|
| Thesis | 15 |
| Opinionated defaults | 10 |
| When / What / How triad | 10 |
| Code cell discipline | 10 |
| Before/after evidence | 15 |
| Runnability | 15 |
| Scope | 10 |
| Dev-to-dev voice | 5 |
| Failure modes | 5 |
| Takeaway artifact | 5 |
Verdict tiers:
| Score | Verdict |
|---|---|
| 90-100 | Publish |
| 75-89 | Publish after fixes |
| 60-74 | Revise and resubmit |
| <60 | Not ready |
Override rule: a recipe with a critical runnability failure, missing thesis, or no reproducible evidence cannot receive "Publish" even if the weighted score is high.
Phase 3: Adversarial pass
Before finalizing, run a skeptical pass:
- Is the thesis just a feature description?
- Are defaults actually opinionated, or hedged with "you can also"?
- Are outputs committed but not reproducible?
- Is the before/after evidence specific enough to calibrate the improvement?
- Are failure modes named as first-class content?
- Is the takeaway a copyable artifact, or merely "the notebook"?
Use this pass to catch false positives, not to invent issues.
Phase 4: Report
Use the template in assets/review-report-template.md. Keep findings direct and evidence-based:
- Lead with the verdict.
- Separate blockers from advisory improvements.
- Give one finding per bullet.
- For each required fix, include why it matters and what to change.
- Include at least one thing the recipe already does well.
Modes
Support these scope flags if the user uses them:
--registry-only: validate only registry, authors, tags, slug, and paths.--writing-only: review thesis, structure, voice, AI-isms, and takeaway artifact.--mechanical-only: run objective checks and skip subjective scoring.--score-only: return only scorecard and verdict.--fix-plan: return a prioritized patch plan without editing files.
Approval standard
Approve when the recipe clearly increases the cookbook's value and a reader can reproduce the lesson. Do not require perfection. Do not rubber-stamp. The bar is: "Would a Microsoft Foundry engineer share this as the reference example in a teammate's chat?"