Skip to content

feat(skills): link every skill to the examples that prove it - #444

Merged
TMHSDigital merged 1 commit into
mainfrom
feat/examples-index
Oct 5, 2026
Merged

TMHSDigital merged 1 commit into
mainfrom
feat/examples-index

Conversation

@TMHSDigital

Copy link
Copy Markdown
Owner

Refs #377. This meets the issue's "Done when": every skill links its examples automatically, and one JSON file describes all examples. The gallery version badges and "falsify it" line from the suggested approach are not in this PR, so the issue stays open for them.

What changed

  • examples/skills.json (hand-edited): example → skills it proves, for all 64 examples. I mapped them from each README and script. Where a README claimed more than the script does, I checked: e.g. "engine-export-presets" only where the script actually calls an exporter.
    • 52 examples map to at least one skill.
    • 12 cover subjects no skill teaches (grease pencil, compositor, light linking, constraints…) and map to [].
  • scripts/build_examples_index.py generates:
  • --check runs in Validate and tests/run_all.py.
  • CLAUDE.md and docs/new-example-prompt.md add the mapping to the example wiring list.

Evidence (local runs)

  • build_examples_index.py --check passes.
  • check_skill_refs.py: every link is a live absolute link.
  • tests/run_all.py: 31 passed, 0 failed.
  • Falsifiers:
    • Deleting turntable and adding a bogus ghost-example → no-such-skill gives 4 errors, exit 1: unmapped example, unknown directory, unknown skill, and slotted-actions-animation left without an example.
    • Hand-editing a generated SKILL.md section gives "is stale", exit 1.
  • Fixed during the falsifier run: a broken mapping first crashed with a KeyError instead of reporting. It now reports and exits 1.
  • With fix(plugin): point skills at the files the plugin installed #439: the plugin dist pins these tree/main/examples/... links to the release tag.

Inspection only: the skill assignments are judgment calls. Reviewers should check examples/skills.json.

🤖 Generated with Claude Code

@github-actions github-actions Bot added skills examples Runnable smoke-gated examples under examples/ documentation Improvements or additions to documentation ci labels Oct 5, 2026
10 of 16 skills linked no example, and an agent had to join three
manifests to learn what an example runs, on which Blender, and how to
break it.

- examples/skills.json (hand-edited) maps each of the 64 examples to
  the skills it proves; 52 map to at least one.
- scripts/build_examples_index.py generates examples/index.json: one
  record per example with script, skills, render or check-only,
  min_version, run command, one-line summary, every smoke falsifier with
  its expected exit, and the README exit-code table.
- The same script writes a marked "Runnable examples" section into each
  SKILL.md, with an absolute link, summary and one falsifier per example.
  addon-scaffolding, bl-info-migration and ui-panels say no example
  exists yet and point at #378.
- --check runs in Validate and tests/run_all.py. It fails when an
  example is unmapped, a skill name is unknown, a skill has no example
  and is not pending, or the generated files are stale.
- CLAUDE.md and docs/new-example-prompt.md add the mapping to the wiring
  list.

Gallery version badges and a "falsify it" line on detail pages are left
for a follow-up.

Refs #377

Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@TMHSDigital

Copy link
Copy Markdown
Owner Author

CI evidence before merge: all checks pass ( 13 pass ). Blender Smoke on PR head: Blender 5.2.2 LTS / Blender 4.5.14 LTS. Summaries (happy path; falsifiers) per leg: 143 passed, 1 skipped, 0 failed;162 passed, 0 skipped, 0 failed;141 passed, 3 skipped, 0 failed;147 passed, 15 skipped, 0 failed;

@TMHSDigital
TMHSDigital merged commit f80411b into main Oct 5, 2026
13 checks passed
@TMHSDigital
TMHSDigital deleted the feat/examples-index branch October 5, 2026 02:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci documentation Improvements or additions to documentation examples Runnable smoke-gated examples under examples/ skills

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant