Skip to content

feature: skill <-> example index and a single machine-readable examples manifest with version support #377

Description

@TMHSDigital

Value

The 64 runnable examples are the repo's strongest asset, but the skills barely point to them, so neither agents nor humans find the proof for a given skill.

Evidence

  • 10 of 16 skills link no examples/ path.
    • slotted-actions-animation never mentions turntable, even though turntable exists to show the channelbag bridge.
    • headless-batch-scripting never mentions temp-override-join.
    • geometry-nodes-python names 2 of its 7 GN examples.
  • An agent has to join three overlapping manifests: examples/gallery.json (56 entries), tests/smoke/catalog.json (142 rows, with names like vse-cut-list-pixels ≠ vse-cut-list), and .cursor-plugin/plugin.json.
  • Catalog min_version exists on only a few rows, and gallery detail pages show no supported-version range.

Suggested approach

  • Add a skills: [...] field per example.
  • Generate examples/index.json with name, path, skills, min_version, render/check-only, try-it command, every falsifier flag with its expected exit, and the exit-code table.
  • Generate a "Runnable examples" section into each SKILL.md from the index, and fail validation when a skill has none.
  • Render 4.5 / 5.1 / 5.2 badges and a "falsify it" copy line on gallery detail pages.

Done when

Every skill links its examples automatically, and one JSON file describes all examples.

Activity

  1. TMHSDigital commented on Oct 5, 2026

    @TMHSDigital
    OwnerAuthor

    #444 delivered the Done-when: examples/skills.json maps every example to the skills it proves, examples/index.json describes all examples (script, skills, render, min_version, run command, every falsifier with its exit, README exit table), every SKILL.md has a generated Runnable examples section, and build_examples_index.py --check gates it in Validate. Still open from the suggested approach: 4.5 / 5.1 / 5.2 badges and a "falsify it" line on gallery detail pages. Leaving this issue open for that.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    examplesRunnable smoke-gated examples under examples/featureNew capabilitypriority: mediumImportant, not urgentskills

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions