Skip to content

ci: the generated skill catalog serialises every open PR #167

Closed

Description

@hanthor

What happens

docs/skills/index.json and docs/skills/index.md are generated by scripts/generate_skill_index.py and committed. Both carry a generated_at / Generated: date at the top of the file, so any PR that touches any skill document rewrites line 2 of both files.

The result is that two PRs which change unrelated skills conflict with each other, on a line neither author wrote, and only the second one to merge finds out. Today alone #142, #143, #152 and #153 all collided on exactly this; three of them are otherwise mergeable and are now waiting on their authors to rebase, regenerate and re-run a full image matrix. With roughly two dozen PRs open, the catalog is effectively a global lock on the documentation tree.

Why it is worth fixing rather than tolerating

The conflict carries no information. The generated files are a pure function of the skill front matter, so resolving them by hand is not review work — it is transcription, and transcription that just check will reject if done wrong. Every one of these rebases also re-runs four image builds for a docs change.

Options, roughly in order of preference

  1. Drop the timestamp. generated_at is the only field that changes when nothing semantic did. Without it, two PRs editing different skills produce disjoint diffs and merge cleanly. The freshness question it is presumably there to answer is better answered by just check failing when the index does not match the sources — which it already does.
  2. Generate in CI instead of committing. Keep --check as the gate on PRs, and have the index built as an artifact (or regenerated on push to main). Removes the files from the conflict surface entirely, at the cost of not being able to read the catalog from a checkout.
  3. Merge driver. A .gitattributes entry pointing docs/skills/index.* at a union or regenerate-on-conflict driver. Works, but only for people who have configured the driver locally, so it does not help the GitHub-side merge that is failing here.

Option 1 is a two-line change and removes most of the pain; option 2 removes all of it.

Acceptance

  • Two PRs that each edit a different file under docs/skills/ can both merge without touching each other.
  • A stale or hand-edited catalog still fails just check.

Found while reviewing #142, #143, #152 and #153.

Activity

  1. added a commit that references this issue on Sep 21, 2026
    f4379b0
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

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions